@fusionkit/cli 0.1.3 → 0.1.5

package/dist/gateway.js

@@ -10,6 +10,7 @@ import { join, resolve } from "node:path";
 import { runFusionPanels, runUnifiedHarnessE2E } from "@fusionkit/ensemble";
 import { emitTrace, newSpanId, newTraceId } from "@fusionkit/protocol";
 import { FusionBackend, installAcpAdapters, runAcpAgent, runFrontDoorAcceptance, startFusionGateway, startGateway } from "@fusionkit/model-gateway";
+import { buildCursorAcpProducer } from "./cursor-acp.js";
 // Once an interactive coding agent owns the terminal, the per-turn panel chatter
 // would corrupt its full-screen TUI. The launcher flips this off before handing
 // over; trace events (for --observe) keep flowing regardless.
@@ -293,10 +294,21 @@ export async function runGatewayAcceptance(input) {
         port: 0
     });
     try {
+        const cursorAcp = buildCursorAcpProducer({
+            cursorKitDir: input.config.cursorKitDir,
+            gatewayUrl: gateway.url(),
+            sentinel: input.sentinel,
+            repo: input.config.repo,
+            ...(input.config.models[0]?.id !== undefined
+                ? { modelName: input.config.models[0].id }
+                : {}),
+            ...(input.config.timeoutMs !== undefined ? { timeoutMs: input.config.timeoutMs } : {})
+        });
         const report = await runFrontDoorAcceptance({
             gatewayUrl: gateway.url(),
             sentinel: input.sentinel,
-            acpRunner: buildAcpRunner(input.config)
+            acpRunner: buildAcpRunner(input.config),
+            ...(cursorAcp !== undefined ? { cursorAcp } : {})
         });
         mkdirSync(resolve(input.outPath, ".."), { recursive: true });
         writeFileSync(input.outPath, JSON.stringify(report, null, 2) + "\n");

package/dist/shared/portless.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Programmatic portless integration for the fusion stack.
+ *
+ * Every dev server and CLI-spawned service the launcher starts is registered
+ * with portless as a stable, named `.localhost` route, so humans and external
+ * coding agents get clean HTTPS URLs instead of raw ports, and a service can be
+ * discovered + reused across runs (a singleton) via the shared route table.
+ *
+ * Routes are managed entirely against the `portless` *library* (its exported
+ * `RouteStore` writes the same file-locked `routes.json` the running proxy reads
+ * live) — we never shell out to the `portless` binary. The privileged TLS proxy
+ * daemon + CA trust are a one-time user setup (`portless service install` +
+ * `portless trust`); here we only detect that it is running and register routes.
+ *
+ * `portless` requires Node >= 24 and is declared an optional dependency, so on
+ * older Node (or when the package/proxy is absent) the session degrades to
+ * plain loopback URLs with no discovery — identical code paths, just unproxied.
+ */
+/** Resolve the portless state directory (honoring `PORTLESS_STATE_DIR`). */
+export declare function stateDir(): string;
+/** Path to the portless CA, for `NODE_EXTRA_CA_CERTS` / `SSL_CERT_FILE`. */
+export declare function caCertPath(): string;
+/** The TLD portless serves routes under (default `.localhost`). */
+export declare function tld(): string;
+/** A running portless proxy, as detected from on-disk state + a live probe. */
+export type DetectedProxy = {
+    port: number;
+    tls: boolean;
+};
+/**
+ * Detect a running portless proxy: read `<stateDir>/proxy.port`, confirm the
+ * owning pid is alive, and probe the port for the `X-Portless` header (a plain
+ * HTTP probe works even against a TLS proxy, which 302-redirects to https and
+ * still stamps the header). Returns `undefined` when no proxy is reachable.
+ */
+export declare function detectProxy(): Promise<DetectedProxy | undefined>;
+/** A service the launcher started, addressable through portless. */
+export type SpawnedService = {
+    port: number;
+    /** Owning pid for the route (defaults to this process). */
+    pid?: number;
+    close: () => Promise<void> | void;
+};
+export type DiscoverOrSpawnInput = {
+    /** Short service name; the `.fusion` project suffix + TLD are added here. */
+    name: string;
+    /** Expected identity token of a reusable instance (model set, config hash, ...). */
+    identity: string;
+    /** Probe a candidate instance on its loopback URL; return its identity token. */
+    healthCheck: (loopbackUrl: string) => Promise<string | undefined>;
+    /** Start a fresh instance when none can be reused. */
+    spawn: () => Promise<SpawnedService>;
+};
+export type DiscoverOrSpawnResult = {
+    /** The URL callers should surface/inject (portless name, or loopback). */
+    url: string;
+    /** The loopback URL for in-process CLI fetches (avoids the CA-at-startup hazard). */
+    loopbackUrl: string;
+    port: number;
+    /** True when this run spawned the instance (and therefore owns teardown). */
+    owned: boolean;
+    /** Tear down only an owned instance; reused instances are left running. */
+    close: () => Promise<void> | void;
+};
+/**
+ * A live portless session threaded through the launcher. When `enabled` is
+ * false (portless off, package absent, or no proxy detected) every method
+ * degrades to plain loopback behavior with no proxy registration or discovery.
+ */
+export type PortlessSession = {
+    enabled: boolean;
+    /** Portless CA path when active, else undefined. */
+    caCertPath: string | undefined;
+    /** Register `127.0.0.1:<port>` under `<name>.<project>.localhost`; returns the URL. */
+    register(name: string, appPort: number): string;
+    /** Remove a route this process owns. */
+    unregister(name: string): void;
+    /** Reuse a compatible running instance, or spawn + register a new one. */
+    discoverOrSpawn(input: DiscoverOrSpawnInput): Promise<DiscoverOrSpawnResult>;
+};
+export type CreateSessionInput = {
+    /** Whether portless is requested (CLI flag / config / PORTLESS env). */
+    enabled: boolean;
+    log?: (line: string) => void;
+};
+/**
+ * Create a portless session. Returns a disabled (loopback) session when
+ * portless is off, the library is unavailable (Node < 24 / not installed), or
+ * no proxy is running; otherwise an active session backed by `RouteStore`.
+ */
+export declare function createPortlessSession(input: CreateSessionInput): Promise<PortlessSession>;
+/**
+ * Reap fusion singleton services: terminate the owning pid of every registered
+ * `*.fusion.<tld>` / `scope.<tld>` route and drop the route. Returns the number
+ * of services stopped. A no-op when portless is unavailable.
+ */
+export declare function reapFusionServices(log?: (line: string) => void): Promise<number>;

package/dist/shared/portless.js

@@ -0,0 +1,253 @@
+/**
+ * Programmatic portless integration for the fusion stack.
+ *
+ * Every dev server and CLI-spawned service the launcher starts is registered
+ * with portless as a stable, named `.localhost` route, so humans and external
+ * coding agents get clean HTTPS URLs instead of raw ports, and a service can be
+ * discovered + reused across runs (a singleton) via the shared route table.
+ *
+ * Routes are managed entirely against the `portless` *library* (its exported
+ * `RouteStore` writes the same file-locked `routes.json` the running proxy reads
+ * live) — we never shell out to the `portless` binary. The privileged TLS proxy
+ * daemon + CA trust are a one-time user setup (`portless service install` +
+ * `portless trust`); here we only detect that it is running and register routes.
+ *
+ * `portless` requires Node >= 24 and is declared an optional dependency, so on
+ * older Node (or when the package/proxy is absent) the session degrades to
+ * plain loopback URLs with no discovery — identical code paths, just unproxied.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The npm scope-less project prefix for fusion service hostnames. */
+const PROJECT = "fusion";
+/** Resolve the portless state directory (honoring `PORTLESS_STATE_DIR`). */
+export function stateDir() {
+    return process.env.PORTLESS_STATE_DIR ?? join(homedir(), ".portless");
+}
+/** Path to the portless CA, for `NODE_EXTRA_CA_CERTS` / `SSL_CERT_FILE`. */
+export function caCertPath() {
+    return join(stateDir(), "ca.pem");
+}
+/** The TLD portless serves routes under (default `.localhost`). */
+export function tld() {
+    return process.env.PORTLESS_TLD ?? "localhost";
+}
+/**
+ * Detect a running portless proxy: read `<stateDir>/proxy.port`, confirm the
+ * owning pid is alive, and probe the port for the `X-Portless` header (a plain
+ * HTTP probe works even against a TLS proxy, which 302-redirects to https and
+ * still stamps the header). Returns `undefined` when no proxy is reachable.
+ */
+export async function detectProxy() {
+    const dir = stateDir();
+    const portFile = join(dir, "proxy.port");
+    if (!existsSync(portFile))
+        return undefined;
+    const port = Number.parseInt(readFileSync(portFile, "utf8").trim(), 10);
+    if (!Number.isInteger(port) || port <= 0)
+        return undefined;
+    const pidFile = join(dir, "proxy.pid");
+    if (existsSync(pidFile)) {
+        const pid = Number.parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+        if (Number.isInteger(pid) && pid > 0 && !isAlive(pid))
+            return undefined;
+    }
+    // Prefer the proxy's recorded TLS mode; fall back to inferring it from the
+    // redirect a plain-HTTP probe gets (a TLS proxy 302s to https).
+    const tlsFile = join(dir, "proxy.tls");
+    const tlsFromFile = existsSync(tlsFile)
+        ? ["1", "true"].includes(readFileSync(tlsFile, "utf8").trim().toLowerCase())
+        : undefined;
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/`, {
+            redirect: "manual",
+            signal: AbortSignal.timeout(1500)
+        });
+        if (response.headers.get("x-portless") === null)
+            return undefined;
+        const location = response.headers.get("location");
+        const tls = tlsFromFile ?? (port === 443 || (location !== null && location.startsWith("https://")));
+        return { port, tls };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but is owned by another user (e.g. the
+        // portless proxy installed as a root LaunchDaemon) — still alive. Only
+        // ESRCH ("no such process") means it is actually gone.
+        return error?.code === "EPERM";
+    }
+}
+async function loadPortless() {
+    // Variable specifier + dynamic import: `portless` is an optional dependency
+    // (Node >= 24 only), so this must not be a static import — it would break the
+    // build/install on Node 22. Documented exception to the no-inline-imports rule.
+    const specifier = "portless";
+    try {
+        return (await import(specifier));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Names that stay bare (`<name>.localhost`) instead of being namespaced under the project. */
+const BARE_NAMES = new Set(["scope"]);
+/** Map a short service name to its portless hostname. */
+function hostnameFor(portless, name) {
+    // `scope` stays bare (`scope.localhost`); everything else is namespaced under
+    // the project (`gateway.fusion.localhost`). A name already containing a dot or
+    // equal to the project is treated as an explicit subdomain path.
+    const full = name === PROJECT || name.includes(".") || BARE_NAMES.has(name) ? name : `${name}.${PROJECT}`;
+    return portless.parseHostname(full, tld());
+}
+const loopback = (port) => `http://127.0.0.1:${port}`;
+/** Build a disabled session: pure loopback, no proxy, no discovery. */
+function disabledSession() {
+    return {
+        enabled: false,
+        caCertPath: undefined,
+        register: (_name, appPort) => loopback(appPort),
+        unregister: () => { },
+        discoverOrSpawn: async (input) => {
+            const service = await input.spawn();
+            const url = loopback(service.port);
+            return { url, loopbackUrl: url, port: service.port, owned: true, close: service.close };
+        }
+    };
+}
+/**
+ * Create a portless session. Returns a disabled (loopback) session when
+ * portless is off, the library is unavailable (Node < 24 / not installed), or
+ * no proxy is running; otherwise an active session backed by `RouteStore`.
+ */
+export async function createPortlessSession(input) {
+    if (!input.enabled)
+        return disabledSession();
+    const portless = await loadPortless();
+    if (portless === undefined) {
+        input.log?.("fusion: portless not installed (needs Node >= 24); using loopback URLs");
+        return disabledSession();
+    }
+    const proxy = await detectProxy();
+    if (proxy === undefined) {
+        // Portless is installed but its proxy isn't running: degrade to loopback
+        // (never block a run) and point the user at the one-time setup for stable
+        // HTTPS names.
+        input.log?.("fusion: portless proxy not running; using loopback URLs " +
+            "(run `portless service install` + `portless trust` for stable https://*.localhost names)");
+        return disabledSession();
+    }
+    const store = new portless.RouteStore(stateDir(), {
+        onWarning: (message) => input.log?.(`fusion: portless: ${message}`)
+    });
+    const urlFor = (hostname) => portless.formatUrl(hostname, proxy.port, proxy.tls);
+    const register = (name, appPort) => {
+        try {
+            const hostname = hostnameFor(portless, name);
+            store.addRoute(hostname, appPort, process.pid, true);
+            return urlFor(hostname);
+        }
+        catch (error) {
+            // Never let a routing hiccup break a run; fall back to the raw port.
+            input.log?.(`fusion: portless register(${name}) failed: ${errorText(error)}`);
+            return loopback(appPort);
+        }
+    };
+    const unregister = (name) => {
+        try {
+            store.removeRoute(hostnameFor(portless, name), process.pid);
+        }
+        catch {
+            // best-effort
+        }
+    };
+    const discoverOrSpawn = async (req) => {
+        const hostname = hostnameFor(portless, req.name);
+        // Discover: is a compatible instance already registered and alive?
+        try {
+            const existing = store.loadRoutes().find((route) => route.hostname === hostname);
+            if (existing !== undefined) {
+                const candidate = loopback(existing.port);
+                const identity = await req.healthCheck(candidate);
+                if (identity === req.identity) {
+                    return {
+                        url: urlFor(hostname),
+                        loopbackUrl: candidate,
+                        port: existing.port,
+                        owned: false,
+                        close: () => { }
+                    };
+                }
+            }
+        }
+        catch (error) {
+            input.log?.(`fusion: portless discover(${req.name}) failed: ${errorText(error)}`);
+        }
+        // Spawn + register a fresh instance, owned by the service pid so the proxy's
+        // liveness filter keeps the route across runs and only drops it when the
+        // service itself exits.
+        const service = await req.spawn();
+        let url = loopback(service.port);
+        try {
+            store.addRoute(hostname, service.port, service.pid ?? process.pid, true);
+            url = urlFor(hostname);
+        }
+        catch (error) {
+            input.log?.(`fusion: portless register(${req.name}) failed: ${errorText(error)}`);
+        }
+        return {
+            url,
+            loopbackUrl: loopback(service.port),
+            port: service.port,
+            owned: true,
+            close: service.close
+        };
+    };
+    return { enabled: true, caCertPath: caCertPath(), register, unregister, discoverOrSpawn };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Reap fusion singleton services: terminate the owning pid of every registered
+ * `*.fusion.<tld>` / `scope.<tld>` route and drop the route. Returns the number
+ * of services stopped. A no-op when portless is unavailable.
+ */
+export async function reapFusionServices(log) {
+    const portless = await loadPortless();
+    if (portless === undefined)
+        return 0;
+    const store = new portless.RouteStore(stateDir(), {
+        onWarning: (message) => log?.(`fusion: portless: ${message}`)
+    });
+    const suffix = `.${PROJECT}.${tld()}`;
+    const scopeHost = portless.parseHostname("scope", tld());
+    let stopped = 0;
+    for (const route of store.loadRoutes()) {
+        if (!route.hostname.endsWith(suffix) && route.hostname !== scopeHost)
+            continue;
+        try {
+            process.kill(route.pid, "SIGTERM");
+            stopped += 1;
+            log?.(`fusion: stopped ${route.hostname} (pid ${route.pid})`);
+        }
+        catch {
+            // process already gone; still drop the stale route below
+        }
+        try {
+            store.removeRoute(route.hostname);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return stopped;
+}

package/dist/test/cli.test.js

@@ -6,16 +6,14 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { after, before, test } from "node:test";
+import { test } from "node:test";
 import { MODEL_FUSION_SCHEMA_BUNDLE_HASH } from "@fusionkit/protocol";
-import { makeRepo as makeStackRepo, mockRunRequest, startStack, uploadWorkspace } from "@fusionkit/testkit";
 const CLI = fileURLToPath(new URL("../index.js", import.meta.url));
 const SMOKE_ENV_KEYS = [
     "WARRANT_CLAUDE_SMOKE",
     "WARRANT_CODEX_SMOKE",
     "WARRANT_ENSEMBLE_LIVE_SMOKE"
 ];
-let home;
 async function readBody(req) {
     const chunks = [];
     for await (const chunk of req)
@@ -100,7 +98,7 @@ function warrant(args, options = {}) {
         else
             env[key] = value;
     }
-    const result = spawnSync(process.execPath, [CLI, "--dir", options.dir ?? home, ...args], {
+    const result = spawnSync(process.execPath, [CLI, ...args], {
         encoding: "utf8",
         env,
         input: options.input
@@ -122,7 +120,7 @@ async function warrantAsync(args, options = {}) {
             env[key] = value;
     }
     return await new Promise((resolve) => {
-        const child = spawn(process.execPath, [CLI, "--dir", options.dir ?? home, ...args], {
+        const child = spawn(process.execPath, [CLI, ...args], {
             env,
             stdio: ["pipe", "pipe", "pipe"]
         });
@@ -145,18 +143,11 @@ async function warrantAsync(args, options = {}) {
         }
     });
 }
-before(() => {
-    home = mkdtempSync(join(tmpdir(), "warrant-cli-test-"));
-    rmSync(home, { recursive: true, force: true });
-});
-after(() => {
-    rmSync(home, { recursive: true, force: true });
-});
 test("help prints usage and lists the top-level commands", () => {
     const result = warrant(["help"]);
     assert.equal(result.status, 0);
     assert.match(result.stdout, /real model fusion behind your coding agent/);
-    for (const command of ["run", "continue", "ensemble", "local", "fusion", "ui", "codex", "claude", "cursor", "serve"]) {
+    for (const command of ["init", "ensemble", "local", "fusion", "codex", "claude", "cursor", "serve"]) {
         assert.match(result.stdout, new RegExp(`\\b${command}\\b`));
     }
 });
@@ -203,78 +194,29 @@ test("fusion help documents the flags-before-tool contract", () => {
     assert.equal(result.status, 0);
     assert.match(result.stdout, /must precede the tool name/);
 });
-test("init creates keys, config, and policy; refuses to re-init", () => {
-    const result = warrant(["init"]);
-    assert.equal(result.status, 0, result.stderr);
-    assert.match(result.stdout, /initialized warrant home/);
-    assert.match(result.stdout, /admin token \(for the control panel\)/);
-    assert.ok(existsSync(join(home, "config.json")));
-    assert.ok(existsSync(join(home, "policy.json")));
-    // The org private key is sealed at rest; a master key file is generated.
-    assert.ok(existsSync(join(home, "keys", "plane.key.enc")));
-    assert.ok(existsSync(join(home, "keys", "plane.pub.pem")));
-    assert.ok(existsSync(join(home, "master.key")));
-    const config = JSON.parse(readFileSync(join(home, "config.json"), "utf8"));
-    assert.equal(config.version, "warrant.config.v2");
-    assert.equal(config.host, "127.0.0.1");
-    // No key material lives in config.json anymore.
-    assert.equal(config.secretsKeyHex, undefined);
-    const again = warrant(["init"]);
-    assert.equal(again.status, 1);
-    assert.match(again.stderr, /already initialized/);
-});
-test("secrets are stored encrypted and listed by name only", () => {
-    const set = warrant(["secrets", "set", "NPM_TOKEN", "super-secret-value"]);
-    assert.equal(set.status, 0, set.stderr);
-    assert.match(set.stdout, /encrypted at rest/);
-    const list = warrant(["secrets", "list"]);
-    assert.equal(list.status, 0);
-    assert.equal(list.stdout.trim(), "NPM_TOKEN");
-    const stored = readFileSync(join(home, "secrets.enc"), "utf8");
-    assert.ok(!stored.includes("super-secret-value"), "value must be encrypted");
-});
-test("ui prints the control panel address and login token", () => {
-    const result = warrant(["ui"]);
-    assert.equal(result.status, 0);
-    assert.match(result.stdout, /control panel: http:\/\/127\.0\.0\.1:7172\/ui\//);
-    assert.match(result.stdout, /login token: {3}\S+/);
+test("init scaffolds a fusionkit.json and refuses to clobber without --force", () => {
+    const fixture = makeRepo();
+    try {
+        const result = warrant(["init", "--repo", fixture.repo]);
+        assert.equal(result.status, 0, result.stderr);
+        const configPath = join(fixture.repo, "fusionkit.json");
+        assert.ok(existsSync(configPath));
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+        assert.equal(config.version, "fusionkit.fusion.v1");
+        const again = warrant(["init", "--repo", fixture.repo]);
+        assert.equal(again.status, 1);
+        assert.match(again.stderr, /already exists/);
+        const forced = warrant(["init", "--repo", fixture.repo, "--force"]);
+        assert.equal(forced.status, 0, forced.stderr);
+    }
+    finally {
+        fixture.cleanup();
+    }
 });
-test("unknown commands and missing arguments fail with guidance", () => {
+test("unknown commands fail with guidance", () => {
     const unknown = warrant(["frobnicate"]);
     assert.equal(unknown.status, 1);
     assert.match(unknown.stderr, /unknown command/);
-    const missingAgent = warrant(["run", "do things"]);
-    assert.equal(missingAgent.status, 1);
-    assert.match(missingAgent.stderr, /--agent is required/);
-    const missingTask = warrant(["continue", "--agent", "mock"]);
-    assert.equal(missingTask.status, 1);
-    assert.match(missingTask.stderr, /task prompt is required/);
-    const badAgent = warrant(["continue", "--agent", "nonsense", "task"]);
-    assert.equal(badAgent.status, 1);
-    assert.match(badAgent.stderr, /unknown agent kind/);
-});
-test("verify fails closed on a tampered bundle file", () => {
-    const path = join(home, "garbage.bundle.json");
-    const fake = {
-        version: "warrant.bundle.v1",
-        contract: { signatures: [], workspace: { baseRef: "x" } },
-        receipt: {
-            contractHash: "0".repeat(64),
-            signatures: [],
-            status: "completed",
-            workspaceIn: { baseRef: "y", manifestHash: "z" },
-            workspaceOut: { diffHash: "", artifactHashes: [] },
-            secretsReleased: [],
-            eventsHead: "",
-            eventCount: 0
-        },
-        events: [],
-        keys: { planePublicKeyPem: "", runnerPublicKeyPem: "" }
-    };
-    writeFileSync(path, JSON.stringify(fake));
-    const result = warrant(["verify", path]);
-    assert.equal(result.status, 1);
-    assert.match(result.stderr, /VERIFICATION FAILED/);
 });
 function makeRepo() {
     const root = mkdtempSync(join(tmpdir(), "warrant-ensemble-cli-"));
@@ -630,7 +572,7 @@ test("ensemble dashboard writes markdown and run-result records", () => {
         assert.match(result.stdout, /records: 6/);
         assert.ok(existsSync(join(fixture.output, "dashboard.md")));
         assert.ok(existsSync(join(fixture.output, "harness-run-results", "mock-success.json")));
-        assert.ok(existsSync(join(fixture.output, "harness-run-results", "cursor-missing.json")));
+        assert.ok(existsSync(join(fixture.output, "harness-run-results", "cursor-skipped.json")));
         const dashboard = readFileSync(join(fixture.output, "dashboard.md"), "utf8");
         assert.match(dashboard, /Capability Matrix/);
         assert.match(dashboard, /command-failure/);
@@ -808,60 +750,3 @@ test("ensemble gateway test runs the unified front-door acceptance suite", async
         fixture.cleanup();
     }
 });
-test("lifecycle commands read a real run from a live plane", async () => {
-    const stack = await startStack({
-        policy: (policy) => {
-            policy.agents.allow = ["mock"];
-        }
-    });
-    const repo = makeStackRepo({ files: { "README.md": "# cli lifecycle\n" } });
-    const liveHome = mkdtempSync(join(tmpdir(), "warrant-cli-live-"));
-    rmSync(liveHome, { recursive: true, force: true });
-    try {
-        // The plane runs in this test process, so every CLI call must use the async
-        // spawner: a synchronous spawn would block the event loop and deadlock the
-        // in-process plane.
-        const init = await warrantAsync(["init"], { dir: liveHome });
-        assert.equal(init.status, 0, init.stderr);
-        // Point the freshly initialized home at the in-process test stack.
-        const configPath = join(liveHome, "config.json");
-        const config = JSON.parse(readFileSync(configPath, "utf8"));
-        config.planeUrl = stack.planeUrl;
-        config.adminToken = stack.adminToken;
-        writeFileSync(configPath, JSON.stringify(config, null, 2));
-        // Create one completed run through the SDK so the CLI has something to read.
-        const captured = await uploadWorkspace(stack.client, repo);
-        const created = await stack.client.requestRun(mockRunRequest({ prompt: "lifecycle probe", pool: stack.pool, workspace: captured.manifest }));
-        if (created.status === "awaiting_approval") {
-            await stack.client.approve(created.runId, { kind: "human", id: "cli-tester" });
-        }
-        assert.ok(await stack.runOnce());
-        const runs = await warrantAsync(["runs"], { dir: liveHome });
-        assert.equal(runs.status, 0, runs.stderr);
-        assert.match(runs.stdout, new RegExp(created.runId));
-        const receipt = await warrantAsync(["receipt", created.runId], { dir: liveHome });
-        assert.equal(receipt.status, 0, receipt.stderr);
-        const bundlePath = join(liveHome, "out.bundle.json");
-        const bundle = await warrantAsync(["bundle", created.runId, "--out", bundlePath], {
-            dir: liveHome
-        });
-        assert.equal(bundle.status, 0, bundle.stderr);
-        assert.match(bundle.stdout, /bundle written to/);
-        assert.ok(existsSync(bundlePath));
-        // The CLI round-trips its own bundle through offline verification.
-        const verify = await warrantAsync(["verify", bundlePath], { dir: liveHome });
-        assert.equal(verify.status, 0, verify.stderr);
-        assert.match(verify.stdout, /VERIFIED/);
-        const exported = await warrantAsync(["export"], { dir: liveHome });
-        assert.equal(exported.status, 0, exported.stderr);
-        assert.match(exported.stdout, new RegExp(created.runId));
-        const pull = await warrantAsync(["pull", created.runId, "--repo", repo], { dir: liveHome });
-        assert.equal(pull.status, 0, pull.stderr);
-        assert.match(pull.stdout, /applied|nothing to pull|branch/);
-    }
-    finally {
-        await stack.stop();
-        rmSync(repo, { recursive: true, force: true });
-        rmSync(liveHome, { recursive: true, force: true });
-    }
-});

package/dist/test/portless.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/portless.test.js

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import { caCertPath, createPortlessSession, detectProxy, stateDir } from "../shared/portless.js";
+const tmpRoots = [];
+function freshStateDir() {
+    const dir = mkdtempSync(join(tmpdir(), "portless-state-"));
+    tmpRoots.push(dir);
+    process.env.PORTLESS_STATE_DIR = dir;
+    return dir;
+}
+after(() => {
+    delete process.env.PORTLESS_STATE_DIR;
+    for (const dir of tmpRoots)
+        rmSync(dir, { recursive: true, force: true });
+});
+test("stateDir + caCertPath honor PORTLESS_STATE_DIR", () => {
+    const dir = freshStateDir();
+    assert.equal(stateDir(), dir);
+    assert.equal(caCertPath(), join(dir, "ca.pem"));
+});
+test("detectProxy returns undefined when no proxy.port file exists", async () => {
+    freshStateDir();
+    assert.equal(await detectProxy(), undefined);
+});
+test("detectProxy returns undefined for a dead proxy pid", async () => {
+    const dir = freshStateDir();
+    writeFileSync(join(dir, "proxy.port"), "443");
+    // pid 1 is alive but won't answer a portless probe; a clearly-dead pid keeps
+    // this deterministic without binding a port.
+    writeFileSync(join(dir, "proxy.pid"), "999999999");
+    assert.equal(await detectProxy(), undefined);
+});
+test("a disabled session uses loopback URLs and never registers", async () => {
+    const session = await createPortlessSession({ enabled: false });
+    assert.equal(session.enabled, false);
+    assert.equal(session.caCertPath, undefined);
+    assert.equal(session.register("scope", 4317), "http://127.0.0.1:4317");
+    assert.equal(session.register("gateway", 5123), "http://127.0.0.1:5123");
+    session.unregister("scope"); // no throw
+    let spawned = 0;
+    const result = await session.discoverOrSpawn({
+        name: "router",
+        identity: "gpt,sonnet",
+        healthCheck: async () => "gpt,sonnet",
+        spawn: async () => {
+            spawned += 1;
+            return { port: 6001, close: () => { } };
+        }
+    });
+    assert.equal(spawned, 1, "a disabled session always spawns (no discovery)");
+    assert.equal(result.owned, true);
+    assert.equal(result.url, "http://127.0.0.1:6001");
+    assert.equal(result.loopbackUrl, "http://127.0.0.1:6001");
+});
+test("enabled session with no reachable proxy degrades to loopback", async () => {
+    freshStateDir(); // empty: no proxy.port
+    const session = await createPortlessSession({ enabled: true });
+    // Whether or not portless is installed, an unreachable proxy degrades to
+    // loopback (never a hard failure) so a fresh install always runs.
+    assert.equal(session.enabled, false, "no proxy detected -> disabled");
+    assert.equal(session.register("scope", 4317), "http://127.0.0.1:4317");
+});