@ashlr/hub 3.5.0 → 3.7.0

package/dist/core/local-runtime/llama/proxy-process.js

@@ -0,0 +1,250 @@
+/**
+ * Identity and invocation for the DETACHED Anthropic proxy host process.
+ *
+ * Two jobs, both of which are "a pid is not an identity" problems:
+ *
+ *  1. HOW TO START ONE. The proxy runs as a child of the hub's own CLI, so
+ *     something has to answer "what argv re-enters this program?" — and the
+ *     answer differs in all three shipping runtimes. See
+ *     {@link anthropicProxyHostInvocation}.
+ *
+ *  2. HOW TO RECOGNISE ONE. `proxy-supervisor.ts` must be able to adopt a proxy
+ *     it did not spawn, refuse a listener it does not own, and terminate only
+ *     what is genuinely ours after a pid has possibly been recycled. That is
+ *     the same discipline process.ts applies to llama-server, with the same
+ *     rule: EVERY condition must hold, because any one of them alone is
+ *     forgeable by an unrelated command line.
+ *
+ * WHY THE ENTRY POINT IS A SUBCOMMAND AND NOT A TOP-LEVEL FLAG: the hub already
+ * has internal re-entry flags (`--_cutoff-checkpoint-supervisor`, the probe
+ * helpers), all dispatched from `src/cli/index.ts`. This one is reached as
+ * `local-runtime --_proxy-host` instead, so the whole dispatch lives inside the
+ * `local-runtime` command that owns it. The flag is operand-free apart from two
+ * integers, absent from help and completions, and — the part that matters —
+ * CANNOT carry a bind host. The child re-derives its host from the persisted
+ * config and re-applies `gateBindHost`, so no argv anywhere can move the
+ * listener off loopback. See proxy-host.ts.
+ */
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { bundledIntoSingleFileBinary, insideSingleFileBinaryRoot, } from '../../resources/probe-helper-invocation.js';
+import { processTable } from './process.js';
+/** The `local-runtime` subcommand word that re-enters this program as a proxy. */
+export const ANTHROPIC_PROXY_HOST_FLAG = '--_proxy-host';
+/** The command word the internal flag lives under. */
+export const ANTHROPIC_PROXY_COMMAND = 'local-runtime';
+/** Flag naming the port the PROXY binds. */
+export const ANTHROPIC_PROXY_PORT_FLAG = '--anthropic-port';
+/** Flag naming the llama-server port the proxy forwards to. */
+export const ANTHROPIC_PROXY_UPSTREAM_PORT_FLAG = '--upstream-port';
+/**
+ * Argv (after argv[0]) for a proxy host serving `port` from `upstreamPort`.
+ *
+ * PURE, so the exact spelling is pinned by unit tests rather than discovered
+ * from a running process — and so {@link argvMatchesProxyRecord} and this
+ * function cannot drift apart into a supervisor that can start a proxy it can
+ * never recognise again.
+ */
+export function anthropicProxyHostArgs(port, upstreamPort) {
+    return [
+        ANTHROPIC_PROXY_COMMAND,
+        ANTHROPIC_PROXY_HOST_FLAG,
+        ANTHROPIC_PROXY_PORT_FLAG,
+        String(port),
+        ANTHROPIC_PROXY_UPSTREAM_PORT_FLAG,
+        String(upstreamPort),
+    ];
+}
+/**
+ * Pin a loader specifier to an absolute file URL.
+ *
+ * The child is spawned with `cwd: homedir()` — deliberately, because a detached
+ * process must not hold a working directory that can be deleted out from under
+ * it. That makes a BARE specifier a live bug: `node --import tsx/esm
+ * src/cli/index.ts …` puts the literal string `tsx/esm` in `execArgv`, the
+ * child resolves it from the home directory, finds no `node_modules/tsx`
+ * there, and dies with ERR_MODULE_NOT_FOUND before it can even log why.
+ *
+ * (Not hypothetical: the supervisor test spawns the CLI exactly that way and
+ * caught this. Running `tsx` through its own launcher happens to put ABSOLUTE
+ * paths in execArgv, so the defect is invisible until someone uses the plain
+ * `--import` spelling — a fine way to ship something that works on the
+ * maintainer's machine and nowhere else.)
+ *
+ * Resolution failure returns the specifier untouched: a loader we could not
+ * resolve is still more likely to work than one we dropped, and the child's
+ * own error message is more useful than a silent omission.
+ */
+function absoluteLoaderSpecifier(specifier, cwd) {
+    if (specifier.startsWith('file://') || isAbsolute(specifier))
+        return specifier;
+    try {
+        // The filename is a resolution anchor, not a file that has to exist.
+        return pathToFileURL(createRequire(join(cwd, 'noop.js')).resolve(specifier)).href;
+    }
+    catch {
+        return specifier;
+    }
+}
+/**
+ * Forward only the loader flags a child genuinely needs to run our source.
+ *
+ * `--import` / `--require` is how tsx registers its TypeScript loader; without
+ * them a child spawned in dev would be handed a `.ts` entry point that plain
+ * Node refuses to parse. Everything else in `execArgv` (inspector ports above
+ * all) is deliberately dropped: inheriting `--inspect` would make the child
+ * fight the parent for the debug port and die.
+ *
+ * Every forwarded value is made absolute first — see
+ * {@link absoluteLoaderSpecifier}.
+ */
+function childRuntimeArgs(execArgv, cwd) {
+    const args = [];
+    for (let index = 0; index < execArgv.length; index += 1) {
+        const arg = execArgv[index];
+        for (const flag of ['--import', '--require']) {
+            if (arg.startsWith(`${flag}=`)) {
+                args.push(`${flag}=${absoluteLoaderSpecifier(arg.slice(flag.length + 1), cwd)}`);
+            }
+            else if (arg === flag) {
+                const value = execArgv[index + 1];
+                if (value !== undefined)
+                    args.push(flag, absoluteLoaderSpecifier(value, cwd));
+                index += 1;
+            }
+        }
+    }
+    return args;
+}
+/**
+ * Build the command + argv that re-enters this program as a proxy host.
+ *
+ * THREE SHIPPING RUNTIMES, and the middle one is the trap:
+ *
+ *   dev / tsx   → node <tsx --require/--import> src/cli/index.ts local-runtime …
+ *   npm dist    → node dist/cli/index.js local-runtime …
+ *   Bun binary  → <the binary itself> local-runtime …
+ *
+ * "Compiled" means: re-invoking `execPath` alone re-enters this program, so the
+ * entry script must NOT be passed as a command word. Four independent signals
+ * decide it, because each covers a case the others miss — this is the same
+ * reasoning as `cutoffCaptureCliInvocation` in the daemon, and it is written
+ * out again here rather than imported because that function's name, flag
+ * argument and failure mode all belong to cutoff capture:
+ *
+ *   1. `bundledIntoSingleFileBinary(moduleUrl)` — INTRINSIC. Inside a Bun
+ *      single-file binary every bundled module's URL collapses onto the virtual
+ *      root, and that is true no matter how the process was invoked. This is
+ *      the signal argv cannot fool.
+ *   2. no `entry` at all — a packaged binary invoked with no script operand.
+ *   3. `insideSingleFileBinaryRoot(entry)` — Bun sets argv[1] to
+ *      `/$bunfs/root/_entry.js`, a path that does not exist on disk. Spawning
+ *      it would hand the CLI a command word it parses as an unknown command and
+ *      rejects with exit 2 — a proxy that never starts and never says why. This
+ *      is also the only form a unit test can simulate, since `import.meta.url`
+ *      cannot be stubbed.
+ *   4. `entry === execPath` — a Node SEA, where argv[1] IS the executable and
+ *      `import.meta.url` is an ordinary on-disk path.
+ *
+ * This repository has shipped the /$bunfs/root defect three times (both account
+ * probes, then cutoff capture). Signals 1 and 3 are precisely what
+ * probe-helper-invocation.ts exports to stop it happening a fourth.
+ */
+export function anthropicProxyHostInvocation(port, upstreamPort, context) {
+    const hostArgs = anthropicProxyHostArgs(port, upstreamPort);
+    const { entry } = context;
+    const compiled = bundledIntoSingleFileBinary(context.moduleUrl) ||
+        entry === undefined ||
+        entry.length === 0 ||
+        insideSingleFileBinaryRoot(entry) ||
+        resolve(entry) === resolve(context.execPath);
+    return {
+        command: context.execPath,
+        args: compiled
+            ? hostArgs
+            : [...childRuntimeArgs(context.execArgv, context.cwd), entry, ...hostArgs],
+    };
+}
+/** This process's own facts, for the non-test call site. */
+export function currentHostInvocationContext(moduleUrl) {
+    return {
+        execPath: process.execPath,
+        entry: process.argv[1],
+        execArgv: process.execArgv,
+        moduleUrl,
+        cwd: process.cwd(),
+    };
+}
+/**
+ * Does an argv line carry `--anthropic-port <n>` for exactly this port?
+ *
+ * Matches the `=` spelling too, so a hand-typed invocation is still recognised
+ * as ours rather than becoming an unkillable stranger on our own port.
+ */
+export function argvBindsAnthropicPort(argv, port) {
+    const pattern = new RegExp(`(?:^|\\s)${ANTHROPIC_PROXY_PORT_FLAG}(?:=|\\s+)${port}(?:\\s|$)`);
+    return pattern.test(argv);
+}
+/**
+ * Is this argv line a proxy host invocation (and not, say, a grep for one)?
+ *
+ * Requires BOTH the command word and the internal flag as standalone tokens.
+ * The flag is undocumented and absent from help, parsing and completions, so an
+ * argv carrying it is one this program wrote — but requiring the command word
+ * as well keeps a stray mention in some other tool's arguments from being
+ * mistaken for a process we may terminate.
+ */
+export function isAnthropicProxyHostArgv(argv) {
+    const tokens = argv.trim().split(/\s+/);
+    return tokens.includes(ANTHROPIC_PROXY_COMMAND) && tokens.includes(ANTHROPIC_PROXY_HOST_FLAG);
+}
+/**
+ * Does this argv line belong to the proxy host described by the record?
+ *
+ * Pure, so the rule is testable without a live process. Three independent facts
+ * must all hold before the recorded pid may be signalled — the direct analogue
+ * of {@link import('./process.js').argvMatchesRecord}:
+ *
+ *   1. argv[0] is the recorded executable,
+ *   2. it is a proxy host invocation at all, and
+ *   3. it binds the recorded proxy port.
+ *
+ * A recycled pid belongs to some other program, whose argv will not be our CLI
+ * re-entering itself on our port — which is what makes recycling harmless.
+ */
+export function argvMatchesProxyRecord(argv, record) {
+    const line = argv.trim();
+    if (!line || !record.execPath)
+        return false;
+    if (line !== record.execPath && !line.startsWith(`${record.execPath} `))
+        return false;
+    if (!isAnthropicProxyHostArgv(line))
+        return false;
+    return argvBindsAnthropicPort(line, record.port);
+}
+/**
+ * Find every live proxy host bound to `port`.
+ *
+ * Used to ADOPT a proxy this process did not spawn — the ordinary case, since
+ * `ashlr local-runtime start` exits and the next invocation is a different
+ * process entirely — and to let `stop` release the port afterwards.
+ */
+export function findAnthropicProxiesOnPort(port) {
+    const found = [];
+    for (const { pid, argv } of processTable()) {
+        if (!isAnthropicProxyHostArgv(argv))
+            continue;
+        if (!argvBindsAnthropicPort(argv, port))
+            continue;
+        const execPath = argv.split(/\s+/)[0];
+        // An argv[0] that is not an absolute path cannot be compared against a
+        // record, and cannot be re-derived either; treat it as unidentifiable
+        // rather than guessing, exactly as the llama-server scan does.
+        if (!isAbsolute(execPath))
+            continue;
+        found.push({ pid, argv, execPath });
+    }
+    return found;
+}
+//# sourceMappingURL=proxy-process.js.map

package/dist/core/local-runtime/llama/proxy-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-process.js","sourceRoot":"","sources":["../../../../src/core/local-runtime/llama/proxy-process.ts"],"names":[],"mappings":"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"}

package/dist/core/local-runtime/llama/proxy-record.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Anthropic proxy's ownership record — record.ts, for the second process.
+ *
+ * Written when the detached proxy host is spawned, read on the next start,
+ * deleted on a clean stop. Everything record.ts says applies here verbatim: it
+ * is the only thing that survives a crash, it is deliberately minimal, there is
+ * no field a credential could hide in, and reading NEVER throws — a missing,
+ * truncated, foreign or hand-edited record is simply "no record", which
+ * degrades the supervisor to the unmanaged path rather than taking the CLI
+ * down.
+ *
+ * It is a sibling of record.ts rather than an extension of it because the two
+ * describe processes with independent lifetimes. Folding the proxy into
+ * llama-server's record would make every field optional, and an optional field
+ * in a shape check that gates a kill decision is exactly the wrong place for
+ * ambiguity.
+ */
+import type { AnthropicProxyOwnershipRecord } from './types.js';
+/**
+ * Validate an untrusted parsed value into a proxy record.
+ *
+ * Exported because the shape check is the security boundary: a record that
+ * fails here is discarded, and a discarded record can never become a kill
+ * decision. Pure, so it is unit-testable without touching the filesystem.
+ */
+export declare function parseAnthropicProxyRecord(value: unknown): AnthropicProxyOwnershipRecord | null;
+/** Read the proxy record, or null when there is not a valid one. Never throws. */
+export declare function readAnthropicProxyRecord(path?: string): AnthropicProxyOwnershipRecord | null;
+/**
+ * Persist the proxy record atomically, 0600, fsynced.
+ *
+ * Returns false rather than throwing: failing to record ownership is a
+ * degradation (the next start cannot reclaim automatically), not a reason to
+ * kill a proxy that is already forwarding correctly.
+ */
+export declare function writeAnthropicProxyRecord(record: AnthropicProxyOwnershipRecord, path?: string): boolean;
+/** Forget the recorded proxy. Idempotent; never throws. */
+export declare function clearAnthropicProxyRecord(path?: string): void;
+/** Move a record aside without destroying it, for a corrupt-state postmortem. */
+export declare function quarantineAnthropicProxyRecord(path?: string): string | null;

package/dist/core/local-runtime/llama/proxy-record.js

@@ -0,0 +1,133 @@
+/**
+ * The Anthropic proxy's ownership record — record.ts, for the second process.
+ *
+ * Written when the detached proxy host is spawned, read on the next start,
+ * deleted on a clean stop. Everything record.ts says applies here verbatim: it
+ * is the only thing that survives a crash, it is deliberately minimal, there is
+ * no field a credential could hide in, and reading NEVER throws — a missing,
+ * truncated, foreign or hand-edited record is simply "no record", which
+ * degrades the supervisor to the unmanaged path rather than taking the CLI
+ * down.
+ *
+ * It is a sibling of record.ts rather than an extension of it because the two
+ * describe processes with independent lifetimes. Folding the proxy into
+ * llama-server's record would make every field optional, and an optional field
+ * in a shape check that gates a kill decision is exactly the wrong place for
+ * ambiguity.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { writePrivateFileAtomically } from '../../util/private-file-write.js';
+import { anthropicProxyRecordPath, localRuntimeDir } from './paths.js';
+/** A record larger than this is not one of ours; refuse to parse it. */
+const MAX_RECORD_BYTES = 64 * 1024;
+const OWNERS = ['cli', 'launchd', 'adopted'];
+/**
+ * Validate an untrusted parsed value into a proxy record.
+ *
+ * Exported because the shape check is the security boundary: a record that
+ * fails here is discarded, and a discarded record can never become a kill
+ * decision. Pure, so it is unit-testable without touching the filesystem.
+ */
+export function parseAnthropicProxyRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (raw['schemaVersion'] !== 1)
+        return null;
+    const pid = raw['pid'];
+    const port = raw['port'];
+    const upstreamPort = raw['upstreamPort'];
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 1)
+        return null;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)
+        return null;
+    if (typeof upstreamPort !== 'number' ||
+        !Number.isInteger(upstreamPort) ||
+        upstreamPort < 1 ||
+        upstreamPort > 65_535) {
+        return null;
+    }
+    const host = raw['host'];
+    const execPath = raw['execPath'];
+    const upstreamOrigin = raw['upstreamOrigin'];
+    const startedAt = raw['startedAt'];
+    if (typeof host !== 'string' || host.length === 0)
+        return null;
+    if (typeof execPath !== 'string' || execPath.length === 0)
+        return null;
+    if (typeof upstreamOrigin !== 'string' || upstreamOrigin.length === 0)
+        return null;
+    if (typeof startedAt !== 'string' || Number.isNaN(Date.parse(startedAt)))
+        return null;
+    const owner = raw['owner'];
+    if (typeof owner !== 'string' || !OWNERS.includes(owner))
+        return null;
+    return {
+        schemaVersion: 1,
+        pid,
+        port,
+        host,
+        execPath,
+        upstreamPort,
+        upstreamOrigin,
+        startedAt,
+        owner: owner,
+    };
+}
+/** Read the proxy record, or null when there is not a valid one. Never throws. */
+export function readAnthropicProxyRecord(path = anthropicProxyRecordPath()) {
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile() || stat.size > MAX_RECORD_BYTES)
+            return null;
+        return parseAnthropicProxyRecord(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the proxy record atomically, 0600, fsynced.
+ *
+ * Returns false rather than throwing: failing to record ownership is a
+ * degradation (the next start cannot reclaim automatically), not a reason to
+ * kill a proxy that is already forwarding correctly.
+ */
+export function writeAnthropicProxyRecord(record, path = anthropicProxyRecordPath()) {
+    try {
+        const dir = localRuntimeDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const temporaryPath = join(dir, `.anthropic-proxy.${randomUUID()}.tmp`);
+        writePrivateFileAtomically(temporaryPath, path, `${JSON.stringify(record, null, 2)}\n`, {
+            anchorPath: dir,
+            label: 'local-runtime anthropic proxy ownership record',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Forget the recorded proxy. Idempotent; never throws. */
+export function clearAnthropicProxyRecord(path = anthropicProxyRecordPath()) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Nothing to forget, or the file is not ours to remove.
+    }
+}
+/** Move a record aside without destroying it, for a corrupt-state postmortem. */
+export function quarantineAnthropicProxyRecord(path = anthropicProxyRecordPath()) {
+    try {
+        const target = `${path}.stale-${new Date().toISOString().replace(/[:.]/g, '')}`;
+        renameSync(path, target);
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=proxy-record.js.map

package/dist/core/local-runtime/llama/proxy-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-record.js","sourceRoot":"","sources":["../../../../src/core/local-runtime/llama/proxy-record.ts"],"names":[],"mappings":"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"}

package/dist/core/local-runtime/llama/proxy-supervisor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The proxy supervisor: start, adopt, stop and inspect the Anthropic lane.
+ *
+ * supervisor.ts, for the second process. The lifecycle is deliberately the same
+ * boring, idempotent shape, because an operator who has learned how
+ * `local-runtime start` treats llama-server should not have to learn a second
+ * set of rules for the listener in front of it:
+ *
+ *   * `ensure` on a healthy proxy of ours is a no-op that says so;
+ *   * a proxy already on the port that we can PROVE is ours is ADOPTED, never
+ *     duplicated — the ordinary case, since every CLI invocation is a new
+ *     process that spawned none of them;
+ *   * a listener we cannot prove is ours is REFUSED, never killed;
+ *   * `stop` with nothing running is a success, not an error;
+ *   * a record that no longer describes a live process of ours is discarded
+ *     rather than acted on, so a recycled pid can never become a kill.
+ *
+ * ONE DEPARTURE from llama-server's lifecycle, and it is deliberate: when we
+ * own the proxy but it is forwarding to a DIFFERENT llama-server than the one
+ * being started, it is restarted rather than reported. llama-server cannot be
+ * repointed cheaply — it holds 27 GB of mapped weights — so `start` there can
+ * only describe the drift. A proxy is a socket and a pipe; leaving one quietly
+ * forwarding to a runtime nobody is using is the two-endpoints failure this
+ * module family exists to make impossible, and here we can simply fix it.
+ *
+ * Nothing here consults `~/.ashlr/KILL`, creates it, or removes it.
+ */
+import type { AshlrConfig } from '../../types.js';
+import type { AnthropicProxyLifecycleResult } from './types.js';
+/**
+ * How long `ensure` waits for a freshly spawned host to answer.
+ *
+ * Unlike llama-server's five minutes this is short on purpose: the child binds
+ * a socket and opens a pipe. It loads no weights, so anything past a couple of
+ * seconds is a failure to launch, not a slow start, and a generous deadline
+ * would only delay the operator learning that.
+ */
+export declare const DEFAULT_PROXY_START_TIMEOUT_MS = 10000;
+export interface DetachedProxyOptions {
+    /** Config the ports, bind host and loopback opt-in are resolved from. */
+    cfg?: AshlrConfig;
+    /** Override the proxy's own port. */
+    port?: number;
+    /** Override llama-server's port — what the proxy forwards to. */
+    upstreamPort?: number;
+    /** Deadline for a freshly spawned host to start answering. */
+    timeoutMs?: number;
+    /** Terminate a listener on our port that we have no record for. */
+    force?: boolean;
+    /**
+     * How to build the child's command line. Injected ONLY by tests, which run
+     * under a test runner whose `process.argv[1]` is the runner rather than this
+     * CLI, so the real resolution would produce an argv that re-enters vitest.
+     */
+    invocation?: (port: number, upstreamPort: number) => {
+        command: string;
+        args: string[];
+    };
+}
+/**
+ * Does this port accept a TCP connection?
+ *
+ * This — not an HTTP round trip — is what "the child we just spawned has bound
+ * its socket" actually means, and it is deliberately the weaker question.
+ *
+ * The proxy pipes every path but `/v1/messages` byte-for-byte to llama-server
+ * and answers NOTHING for itself; that invariant is load-bearing (see the
+ * anthropic-proxy.ts header) and is not worth breaking for a health endpoint.
+ * The consequence is that an HTTP probe through the proxy measures llama-server
+ * too: a wedged upstream that accepts connections and never replies would make
+ * a perfectly healthy proxy look dead, and `start` would then report failure
+ * for a lane that was working. Asking the narrower question keeps the two
+ * processes' health independent, which is the whole reason they are two
+ * processes.
+ *
+ * Paired with `processAlive(pid)` on a pid we spawned, onto a port `isPortFree`
+ * said was free moments earlier, this is a sound proof of ownership.
+ *
+ * Never throws; an unreachable port is `false`, not an exception.
+ */
+export declare function anthropicProxyAccepts(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Is a proxy answering HTTP on this host/port, end to end?
+ *
+ * ANY HTTP response counts, including a 502. That is not laziness: a 502 from
+ * this listener means the proxy is up and llama-server is not, which is exactly
+ * the proxy being healthy at the only job it has. Requiring a 200 would make
+ * the Anthropic lane un-reportable whenever the runtime behind it was still
+ * loading.
+ *
+ * Used for REPORTING (`status`), not for lifecycle decisions — see
+ * {@link anthropicProxyAccepts} for why the two are separate questions.
+ *
+ * Never throws; an unreachable port is `false`, not an exception.
+ */
+export declare function anthropicProxyResponds(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/** Recover `--upstream-port` from an argv line. Pure; null when absent. */
+export declare function upstreamPortFromArgv(argv: string): number | null;
+/**
+ * Bring up the detached proxy, or prove one is already up.
+ *
+ * Never throws and never fails loudly for an expected state: llama-server
+ * serving correctly is still a success even when the Anthropic lane in front of
+ * it could not bind, so the caller gets a value it can fold into its own
+ * sentence rather than an exception it can forget to catch.
+ */
+export declare function ensureDetachedAnthropicProxy(options?: DetachedProxyOptions): Promise<AnthropicProxyLifecycleResult>;
+/**
+ * Stop the detached proxy and release the port.
+ *
+ * Idempotent: stopping what is not running is `not-running` and `ok: true`, not
+ * an error. A listener we cannot prove is ours is refused rather than killed,
+ * unless `force` is given — the same bargain `local-runtime stop --force`
+ * offers for llama-server.
+ */
+export declare function stopDetachedAnthropicProxy(options?: DetachedProxyOptions): Promise<AnthropicProxyLifecycleResult>;
+/** Read the proxy's state without changing anything. Never throws. */
+export declare function statusDetachedAnthropicProxy(options?: DetachedProxyOptions): Promise<AnthropicProxyLifecycleResult>;