@bakers-build/addon-ports 0.0.0-stage → 0.1.0-next.38

package/dist/src/deps-node.d.ts

@@ -0,0 +1,91 @@
+import type { HttpProbe } from './claims.js';
+import type { HostDiscoveryDeps } from './discovery.js';
+import { type StateDeps } from './state.js';
+/** The filesystem seams for the state file. */
+export declare const nodeStateDeps: StateDeps;
+/** The discovery seams: `ss` and `/proc/<pid>`. */
+export declare const nodeDiscoveryDeps: HostDiscoveryDeps;
+/**
+ * AC6 — `/proc/<pid>/stat`'s 22nd field (start time, in clock ticks since
+ * boot): a stronger PID-reuse guard than cmdline/deleted-cwd alone, which
+ * could coincidentally match a reused pid running a similar-looking process.
+ * Pure and exported so the field-counting (the 2nd field is `(comm)`, which
+ * may itself contain spaces/parens) is directly testable without `/proc`.
+ */
+export declare function parseProcStatStartTime(stat: string): number | null;
+/** `null` when the process is gone or the field cannot be parsed — no
+ *  process to compare a start time against either way. */
+export declare function processStartTime(pid: number): Promise<number | null>;
+/**
+ * BB-681 Task 4 — a process whose cmdline carries ANY pluggable-transport
+ * package's own ownership marker: `addon-ports-cloudflare-quick`'s private
+ * per-route `--config <BB_HOME>/ports/quick/<hash>/gen-<n>/config.yaml`,
+ * or a Named Cloudflare connector's `tunnel run` invocation. This generic
+ * legacy-reap scan predates per-route managed processes (BB-676) and its
+ * only signal for "legacy" is `cmdline.includes('--url')` (see
+ * `index.ts`'s reap handler) — which the new Quick package's OWN managed
+ * processes also match, since they use the same `--url` flag. Without this
+ * guard, generic reap would treat every quick-tunnel package process as an
+ * orphan it's free to kill; the quick package owns its OWN revalidated
+ * reap (`reconcileQuick`'s `desired: 'absent'` path) and this generic scan
+ * must never duplicate or race it.
+ */
+export declare function isPluggableTransportManaged(cmdline: string): boolean;
+/**
+ * BB-676 Task 4 — scans the process table for `cloudflared`, keeping
+ * `cmdline` so a caller can tell a legacy `tunnel --url …` quick-tunnel
+ * (reap's cleanup target) apart from the machine's named `tunnel run`
+ * connector, which reap must never touch (plan review focus 4). BB-681
+ * Task 4: also excludes anything `isPluggableTransportManaged` recognizes —
+ * a pluggable transport's own managed process, never generic reap's to kill.
+ */
+export declare function listCloudflaredProcesses(): Promise<{
+    pid: number;
+    cwd: string;
+    deleted: boolean;
+    cmdline: string;
+    startTime: number | null;
+}[]>;
+/**
+ * AC6 — read a worktree's OLD pre-BB-676 per-port quick-tunnel state
+ * (`.bakers/ports-tunnels.json`, written by the `transport.ts`/`state.ts` path
+ * this feature replaced) purely as migration evidence: a legacy-process
+ * candidate whose pid appears here is additional corroboration reap may use,
+ * never a replacement for the existing argv/owner/cwd checks. Never written
+ * or removed by this addon. Absent or malformed reads as "no evidence", not
+ * an error — a half-written or already-cleaned-up legacy file must not block
+ * reap.
+ */
+export declare function readLegacyTunnelPids(worktree: string): Promise<ReadonlySet<number>>;
+/**
+ * Is `pid` owned by this process's own user? Legacy reap must never kill
+ * another user's process (plan review focus 4) — even an own-user match is
+ * re-validated by the caller against fresh `processInfo` immediately before
+ * `SIGTERM`, to close the PID-reuse race between listing and killing.
+ */
+export declare function isOwnedByCurrentUser(pid: number): Promise<boolean>;
+/** BB-676 Task 4 — a bounded, non-redirecting Storybook probe over real `fetch`. */
+export declare const nodeHttpProbe: HttpProbe;
+/** Everything a command needs, bundled. */
+export declare const nodeDeps: {
+    run(cmd: string, args: string[], cwd?: string): Promise<{
+        stdout: string;
+        ok: boolean;
+    }>;
+    processInfo(pid: number): Promise<{
+        path: string;
+        deleted: boolean;
+        cmdline: string;
+    } | null>;
+    readFile(path: string): Promise<string | null>;
+};
+/** BB-681 Task 2 — everything `bringUpTunnel`/`takeDownTunnel`/`reapTunnels`
+ *  need: state + lock I/O only. Provider I/O (e.g. Cloudflare's REST API)
+ *  lives inside the configured transport package instead. */
+export declare const nodeTunnelOpsDeps: {
+    spawn: typeof import("child_process").spawn;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string, mode: number): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+};

package/dist/src/deps-node.js

@@ -0,0 +1,234 @@
+// BB-475 — the real seams behind discovery and transport, for the CLI.
+//
+// The I/O edge of the package: the `defaultSpawn` half of the conductor-host
+// pattern. Everything here is substituted in tests; nothing here is unit-tested,
+// exactly as `createConductorProcessHost`'s defaults are not — the seams exist so
+// the LOGIC above them can be. `reap` and `discoverHostPorts` above carry the
+// behaviour; this file only wires them to `child_process` and `/proc`.
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile, readlink, stat } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { nodeLockDeps } from './lock.js';
+import { readTunnelState } from './state.js';
+import { nodeTunnelStateDeps } from './tunnel-state.js';
+// `execFile`, never `exec`: no shell, so a value that ends up in an argument —
+// notably a tunnel `target` derived from a DISCOVERED service address — cannot
+// be interpreted as a shell metacharacter. The argv array is the whole point.
+const execFile = promisify(execFileCallback);
+// G: a paused/hung container must not hang `list`/`reap` (which holds the
+// machine lock) forever — `docker exec`/`inspect`/`ps` all get a bounded
+// deadline; a timeout is reported as a failed probe (surfaced as a
+// diagnostic upstream), never left to hang.
+const EXEC_TIMEOUT_MS = 5_000;
+/** The filesystem seams for the state file. */
+export const nodeStateDeps = {
+    readFile: async (path) => {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/** The discovery seams: `ss` and `/proc/<pid>`. */
+export const nodeDiscoveryDeps = {
+    run: async (cmd, args, cwd) => {
+        try {
+            const { stdout } = await execFile(cmd, args, {
+                maxBuffer: 8 * 1024 * 1024,
+                timeout: EXEC_TIMEOUT_MS,
+                ...(cwd ? { cwd } : {}),
+            });
+            return { stdout, ok: true };
+        }
+        catch (err) {
+            // A non-zero exit still carries stdout for a command like `ddev describe`
+            // outside a project; hand it back so the parser can decide. `code` is
+            // the numeric exit code when the process actually ran (e.g. 127 =
+            // command not found inside the container); a spawn-level failure
+            // carries a string errno instead, so only a number is surfaced.
+            // `stderr` is also threaded through (BB-681 review I3): without it,
+            // `isPermissionDenied126` can never fire against a REAL `docker exec`,
+            // so every exit 126 reads as a missing binary even when the container
+            // actually refused for a permission reason.
+            const withOut = err;
+            const exitCode = typeof withOut.code === 'number' ? withOut.code : undefined;
+            return {
+                stdout: withOut.stdout ?? '',
+                ok: false,
+                ...(exitCode !== undefined ? { exitCode } : {}),
+                ...(withOut.stderr ? { stderr: withOut.stderr } : {}),
+            };
+        }
+    },
+    processInfo: async (pid) => {
+        try {
+            const link = await readlink(`/proc/${pid}/cwd`);
+            // The kernel appends ` (deleted)` to the symlink TARGET when the working
+            // directory has been removed — the orphan signal (spec C3). `stat` on the
+            // magic link resolves the CURRENT directory, so it throws ENOENT for a
+            // reaped worktree; the two agree, and the stat is the reliable one.
+            const cmdlineRaw = await readFile(`/proc/${pid}/cmdline`, 'utf8').catch(() => '');
+            const cmdline = cmdlineRaw.replace(/\0/g, ' ').trim();
+            const deleted = link.endsWith(' (deleted)') ||
+                !(await stat(`/proc/${pid}/cwd`)
+                    .then(() => true)
+                    .catch(() => false));
+            return {
+                path: link.replace(/ \(deleted\)$/, ''),
+                deleted,
+                cmdline,
+            };
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * AC6 — `/proc/<pid>/stat`'s 22nd field (start time, in clock ticks since
+ * boot): a stronger PID-reuse guard than cmdline/deleted-cwd alone, which
+ * could coincidentally match a reused pid running a similar-looking process.
+ * Pure and exported so the field-counting (the 2nd field is `(comm)`, which
+ * may itself contain spaces/parens) is directly testable without `/proc`.
+ */
+export function parseProcStatStartTime(stat) {
+    const afterComm = stat.slice(stat.lastIndexOf(')') + 2);
+    const fields = afterComm.split(' ');
+    // Field 3 is state (already consumed above as field 2's successor is index
+    // 0 here); starttime is the 22nd field overall, i.e. index 19 of this
+    // remainder (22 - 3 = 19, since fields 1-2 are `pid`/`comm`).
+    const startTime = Number(fields[19]);
+    return Number.isFinite(startTime) ? startTime : null;
+}
+/** `null` when the process is gone or the field cannot be parsed — no
+ *  process to compare a start time against either way. */
+export async function processStartTime(pid) {
+    try {
+        return parseProcStatStartTime(await readFile(`/proc/${pid}/stat`, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * BB-681 Task 4 — a process whose cmdline carries ANY pluggable-transport
+ * package's own ownership marker: `addon-ports-cloudflare-quick`'s private
+ * per-route `--config <BB_HOME>/ports/quick/<hash>/gen-<n>/config.yaml`,
+ * or a Named Cloudflare connector's `tunnel run` invocation. This generic
+ * legacy-reap scan predates per-route managed processes (BB-676) and its
+ * only signal for "legacy" is `cmdline.includes('--url')` (see
+ * `index.ts`'s reap handler) — which the new Quick package's OWN managed
+ * processes also match, since they use the same `--url` flag. Without this
+ * guard, generic reap would treat every quick-tunnel package process as an
+ * orphan it's free to kill; the quick package owns its OWN revalidated
+ * reap (`reconcileQuick`'s `desired: 'absent'` path) and this generic scan
+ * must never duplicate or race it.
+ */
+export function isPluggableTransportManaged(cmdline) {
+    if (/\/ports\/quick\//.test(cmdline))
+        return true; // addon-ports-cloudflare-quick
+    if (/\btunnel\s+run\b/.test(cmdline))
+        return true; // Named Cloudflare connector
+    return false;
+}
+/**
+ * BB-676 Task 4 — scans the process table for `cloudflared`, keeping
+ * `cmdline` so a caller can tell a legacy `tunnel --url …` quick-tunnel
+ * (reap's cleanup target) apart from the machine's named `tunnel run`
+ * connector, which reap must never touch (plan review focus 4). BB-681
+ * Task 4: also excludes anything `isPluggableTransportManaged` recognizes —
+ * a pluggable transport's own managed process, never generic reap's to kill.
+ */
+export async function listCloudflaredProcesses() {
+    const { stdout } = await execFile('ps', ['-eo', 'pid,comm'], {
+        timeout: EXEC_TIMEOUT_MS,
+    }).catch(() => ({
+        stdout: '',
+    }));
+    const processes = [];
+    for (const line of stdout.split('\n')) {
+        if (!/cloudflared/.test(line))
+            continue;
+        const pid = Number(line.trim().split(/\s+/)[0]);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        const info = await nodeDiscoveryDeps.processInfo(pid);
+        if (info && !isPluggableTransportManaged(info.cmdline))
+            processes.push({
+                pid,
+                cwd: info.path,
+                deleted: info.deleted,
+                cmdline: info.cmdline,
+                startTime: await processStartTime(pid),
+            });
+    }
+    return processes;
+}
+/**
+ * AC6 — read a worktree's OLD pre-BB-676 per-port quick-tunnel state
+ * (`.bakers/ports-tunnels.json`, written by the `transport.ts`/`state.ts` path
+ * this feature replaced) purely as migration evidence: a legacy-process
+ * candidate whose pid appears here is additional corroboration reap may use,
+ * never a replacement for the existing argv/owner/cwd checks. Never written
+ * or removed by this addon. Absent or malformed reads as "no evidence", not
+ * an error — a half-written or already-cleaned-up legacy file must not block
+ * reap.
+ */
+export async function readLegacyTunnelPids(worktree) {
+    const state = await readTunnelState(worktree, nodeStateDeps);
+    return new Set(state.tunnels.map((t) => t.pid));
+}
+/**
+ * Is `pid` owned by this process's own user? Legacy reap must never kill
+ * another user's process (plan review focus 4) — even an own-user match is
+ * re-validated by the caller against fresh `processInfo` immediately before
+ * `SIGTERM`, to close the PID-reuse race between listing and killing.
+ */
+export async function isOwnedByCurrentUser(pid) {
+    try {
+        const status = await readFile(`/proc/${pid}/status`, 'utf8');
+        const match = /^Uid:\s+(\d+)/m.exec(status);
+        return (match !== undefined &&
+            match !== null &&
+            Number(match[1]) === process.getuid?.());
+    }
+    catch {
+        return false;
+    }
+}
+/** BB-676 Task 4 — a bounded, non-redirecting Storybook probe over real `fetch`. */
+export const nodeHttpProbe = async (url, opts) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            redirect: 'manual',
+        });
+        if (res.type === 'opaqueredirect' ||
+            (res.status >= 300 && res.status < 400))
+            return null;
+        const body = await res.text();
+        return { ok: res.ok, status: res.status, body };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** Everything a command needs, bundled. */
+export const nodeDeps = {
+    ...nodeStateDeps,
+    ...nodeDiscoveryDeps,
+};
+/** BB-681 Task 2 — everything `bringUpTunnel`/`takeDownTunnel`/`reapTunnels`
+ *  need: state + lock I/O only. Provider I/O (e.g. Cloudflare's REST API)
+ *  lives inside the configured transport package instead. */
+export const nodeTunnelOpsDeps = {
+    ...nodeTunnelStateDeps,
+    ...nodeLockDeps,
+};

package/dist/src/discovery.d.ts

@@ -0,0 +1,28 @@
+import { parseSocketListeners, type RawDiscovery, type SocketListener } from '@bakers-build/addon-ddev';
+export { parseSocketListeners, type SocketListener };
+/** The injected seams for host-listener discovery. */
+export interface HostDiscoveryDeps {
+    /** Run a command, capturing stdout; `ok` is false when it could not run. */
+    run(cmd: string, args: string[], cwd?: string): Promise<{
+        stdout: string;
+        ok: boolean;
+    }>;
+    /**
+     * A process's working directory and command line — `/proc/<pid>/cwd` and
+     * `/proc/<pid>/cmdline`. `deleted` is the `(deleted)` suffix `readlink`
+     * reports when the directory is gone (the orphan signal), and `cmdline` is
+     * what names the service: the socket table gives only `node`, and `node` is
+     * Storybook, Vite and a dozen other things.
+     */
+    processInfo(pid: number): Promise<{
+        path: string;
+        deleted: boolean;
+        cmdline: string;
+    } | null>;
+}
+/**
+ * Discover this worktree's host listeners (AC1): `ss -ltnpH`, dedupe PIDs
+ * before reading `/proc` (one read per pid), match owner against the
+ * worktree. `list` calls only this — no Docker, no Cloudflare, no mutation.
+ */
+export declare function discoverHostPorts(worktree: string, deps: HostDiscoveryDeps): Promise<RawDiscovery>;

package/dist/src/discovery.js

@@ -0,0 +1,100 @@
+// BB-676 spec v2 — host-listener discovery only. Docker/DDEV discovery
+// moved to `@bakers-build/addon-docker-compose`/`@bakers-build/addon-ddev` (operator
+// decision 2026-10-15: `bakers ports` must not fire `docker` itself). This file
+// now does exactly one thing: `ss -ltnpH` plus `/proc/<pid>` — no external
+// binary beyond `ss`, no root.
+//
+// The parsers are pure and exported so a test drives them with captured
+// output; the orchestrator takes an injected `run`/`processInfo` so no real
+// socket is ever read in a test.
+import { parseSocketListeners, } from '@bakers-build/addon-ddev';
+// BB-676 pass-6 review cleanup — `parseSocketListeners`/`SocketListener`
+// used to be reimplemented here byte-for-byte; `@bakers-build/addon-docker-compose`
+// is the one home now (the lower-level package), re-exported through
+// `@bakers-build/addon-ddev` because this addon may not edge to
+// `@bakers-build/addon-docker-compose` directly (`scripts/assert-acyclic.mjs`).
+export { parseSocketListeners };
+/** Is `path` inside `worktree` (or the worktree itself)? */
+function underWorktree(path, worktree) {
+    const root = worktree.replace(/\/+$/, '');
+    return path === root || path.startsWith(`${root}/`);
+}
+/**
+ * Discover this worktree's host listeners (AC1): `ss -ltnpH`, dedupe PIDs
+ * before reading `/proc` (one read per pid), match owner against the
+ * worktree. `list` calls only this — no Docker, no Cloudflare, no mutation.
+ */
+export async function discoverHostPorts(worktree, deps) {
+    const diagnostics = [];
+    const ports = [];
+    // C3: a listener is only THIS worktree's observation when its owning
+    // process's cwd resolves under it. A foreign worktree's listener (another
+    // ticket, the main checkout) is not included at all — not even as an
+    // orphan, because it was never ours. A pid-less row (no permission to see
+    // the owner) cannot be attributed to any worktree, so it is also excluded
+    // here, with a diagnostic recording that evidence was incomplete.
+    // macOS compatibility: `ss`/`/proc` are Linux-only (ticket scope: "Linux
+    // discovery") — there is no BSD/macOS equivalent attempted here (lsof/
+    // netstat parity is out of scope). Rather than let a raw `ENOENT` surface
+    // as "ss -ltnpH failed" with no further context, name the real cause when
+    // we know it, so this reads as an honest platform limitation rather than a
+    // mysterious probe failure. Docker/DDEV-routed services are unaffected —
+    // the Linux VM behind Docker Desktop still answers these probes fine
+    // in-container; only THIS host-process scan is skipped.
+    const host = await deps.run('ss', ['-ltnpH']);
+    if (!host.ok) {
+        diagnostics.push({
+            source: 'host',
+            wholePass: true,
+            message: process.platform !== 'linux'
+                ? `host-process discovery requires Linux (\`ss\`/\`/proc\`), not available on ${process.platform}; container-routed services are still discoverable`
+                : '`ss -ltnpH` failed',
+        });
+        return { ports, diagnostics };
+    }
+    const listeners = parseSocketListeners(host.stdout);
+    const pids = [
+        ...new Set(listeners
+            .map((l) => l.pid)
+            .filter((pid) => pid !== undefined)),
+    ];
+    const infoByPid = new Map();
+    await Promise.all(pids.map(async (pid) => infoByPid.set(pid, await deps.processInfo(pid))));
+    for (const listener of listeners) {
+        if (listener.pid === undefined) {
+            diagnostics.push({
+                source: 'host',
+                message: `listening port ${listener.port} has no visible owner (permission?); evidence incomplete`,
+            });
+            continue;
+        }
+        const info = infoByPid.get(listener.pid) ?? null;
+        // cloudflared is the transport, never a service to tunnel (BB-500).
+        if (info?.cmdline.toLowerCase().includes('cloudflared'))
+            continue;
+        if (!info) {
+            diagnostics.push({
+                source: 'host',
+                message: `pid ${listener.pid} on port ${listener.port} vanished before its cwd could be read`,
+            });
+            continue;
+        }
+        // A deleted cwd under this worktree is a genuine orphan (kept, no rule);
+        // a deleted or live cwd under a DIFFERENT worktree is simply not this
+        // worktree's listener.
+        if (!underWorktree(info.path, worktree))
+            continue;
+        ports.push({
+            worktree,
+            hostAddress: listener.address,
+            hostPort: listener.port,
+            pid: listener.pid,
+            cmdline: info.cmdline,
+            cwd: info.path,
+            cwdDeleted: info.deleted,
+            listening: true,
+            exposed: 'unknown',
+        });
+    }
+    return { ports, diagnostics };
+}

package/dist/src/inbox.d.ts

@@ -0,0 +1,35 @@
+import type { InboxMessageHandler } from '@bakers-build/conductor/contract';
+import type { ClaimedDiscovery, ClaimedService } from './claims.js';
+import { type OperationContext, type PortsTransport, type TunnelDesiredRecord } from './core.js';
+/** The I/O the handler needs, injected so a test drives it with fixtures.
+ *  `loadTransport` is the SAME shared loader the CLI uses (`config.ts`'s
+ *  `loadPortsTransport`) — one code path for both, so settings validation
+ *  cannot be bypassed by going through the inbox instead of the CLI. A
+ *  missing/invalid/unresolvable transport resolves to `null`: the message
+ *  answers a stable "no ports configuration" line rather than throwing a
+ *  raw stack trace into the ticket's addon card. */
+export interface TunnelHandlerDeps {
+    discover(worktree: string, ticket: string, zone: string): Promise<ClaimedDiscovery>;
+    readRecords(worktree: string): Promise<readonly TunnelDesiredRecord[]>;
+    bringUp(service: ClaimedService, ctx: OperationContext): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Same shared loader the CLI uses, surfaced with its own redacted
+     *  diagnostic on failure — BB-681 review I5: a missing config and an
+     *  unresolvable/invalid transport package are different problems and must
+     *  not collapse onto one generic "no configuration" line here while the
+     *  CLI reports the real one. */
+    loadTransport(): Promise<{
+        readonly ok: true;
+        readonly transport: PortsTransport;
+    } | {
+        readonly ok: false;
+        readonly message: string;
+    }>;
+    home(): string;
+}
+export declare function tunnelHandlers(deps: TunnelHandlerDeps): Record<string, InboxMessageHandler>;
+/** The live handlers for the conductor's effective ports entry `with`
+ *  (`options`, machine entry wins) — the conductor passes it per dispatch. */
+export declare function handlersFor(options: unknown): Record<string, InboxMessageHandler>;

package/dist/src/inbox.js

@@ -0,0 +1,91 @@
+// BB-676 Task 4 — the ports addon's contract-2 handler (BB-661): a single
+// `tunnel` message claims every eligible service of the worktree and shares
+// each one not yet applied, then answers with one Markdown list.
+//
+// Only a claim with `rules.length > 0` is ever shared — an unknown, dead,
+// stopped or not-exposed service never reaches `bringUp` (spec "Addon
+// claims": "No unclaimed tunnels"). Liveness is read from the machine's
+// APPLIED state, never a per-route PID — a route is up because its record
+// says so, not because some process on this host answers to a signal.
+import { realpathSync } from 'node:fs';
+import { homeBbDir } from '@bakers-build/core';
+import { servicesToShare, shareAll } from './claim-share.js';
+import { discoverClaimedServices } from './claims.js';
+import { assertNoMachinePorts, bringUpTunnel, loadPortsTransport, readMachineTunnelRecords, withProblems, } from './core.js';
+import { nodeDeps, nodeHttpProbe, nodeTunnelOpsDeps } from './deps-node.js';
+import { serviceRules } from './service-config.js';
+import { tunnelMarkdown } from './tunnel-result.js';
+/** The worktree as the CLI sees it (`process.cwd()` is already real): DDEV
+ *  labels containers with the real path and discovery matches it exactly, so a
+ *  symlinked path from the server would find nothing (BB-693). */
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+export function tunnelHandlers(deps) {
+    return {
+        tunnel: async (request) => {
+            const loaded = await deps.loadTransport();
+            if (!loaded.ok) {
+                return { markdown: loaded.message };
+            }
+            const transport = loaded.transport;
+            const ticket = request.ticket.identifier;
+            const worktree = canonicalPath(request.worktreePath);
+            const discovery = await deps.discover(worktree, ticket, transport.zone ?? '');
+            const ctx = {
+                worktree,
+                ticket,
+                home: deps.home(),
+                transport,
+                signal: request.signal,
+            };
+            const outcomes = await shareAll(servicesToShare(discovery), (s) => deps.bringUp(s, ctx));
+            const failures = outcomes
+                .filter(({ result }) => !result.ok)
+                .map(({ service, result }) => ({ service, message: result.message }));
+            const after = await deps.readRecords(worktree);
+            return { markdown: tunnelMarkdown(discovery, after, failures) };
+        },
+    };
+}
+/** The live handlers for the conductor's effective ports entry `with`
+ *  (`options`, machine entry wins) — the conductor passes it per dispatch. */
+export function handlersFor(options) {
+    return tunnelHandlers({
+        discover: (worktree, ticket, zone) => discoverClaimedServices(worktree, nodeDeps, {
+            ticket,
+            zone,
+            probe: nodeHttpProbe,
+            rules: serviceRules(options),
+        }),
+        readRecords: (worktree) => readMachineTunnelRecords(worktree, homeBbDir(), nodeTunnelOpsDeps),
+        bringUp: (service, ctx) => bringUpTunnel(service.rules[0], ctx, nodeTunnelOpsDeps),
+        loadTransport: async () => {
+            // The conductor hands the merged `with`; a bad setting answers here
+            // instead of a silently empty claim list.
+            const [problem] = withProblems(options);
+            if (problem)
+                return { ok: false, message: problem };
+            try {
+                await assertNoMachinePorts();
+                const transport = await loadPortsTransport(options, homeBbDir());
+                return { ok: true, transport };
+            }
+            catch (err) {
+                // The loader already produces a bounded, redacted diagnostic (missing
+                // entry, unresolvable package, rejected settings) — the SAME message
+                // the CLI prints, never a raw stack trace into the ticket's addon card.
+                return {
+                    ok: false,
+                    message: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+        home: () => homeBbDir(),
+    });
+}