@reticlehq/server 2.14.0 → 3.2.0

package/dist/cli/cli-flow-commands.d.ts

@@ -1,46 +0,0 @@
-/**
- * CLI commands that operate on SAVED FLOWS: watch, capsules, and the gate.
- *
- * Split out of cli.ts, which was 653 lines — over the project's own cap, and the file a contributor
- * opens first. These five functions form one cohesive group: they all read the flow store and report on
- * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
- */
-import { type ChangedFiles } from '../flows/git-changed.js';
-import { type FileSystemPort } from '../project/fs-port.js';
-import { type NamedFlow } from '../flows/flow-sources.js';
-/** Load the {name, steps} of every saved flow for the active project. */
-/** Explicit files plus, when --since is given, the git-changed files since that ref. */
-/**
- * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
- * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
- * where `git diff` answers about the wrong repository or about none.
- */
-export declare function resolveChangedFiles(files: string[], since: string | undefined, cwd: string): Promise<ChangedFiles>;
-/**
- * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
- * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
- * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
- * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
- * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
- * confident negative about somebody else's project, which is worse than an error.
- */
-export declare function loadNamedFlows(fs: FileSystemPort, reticleRoot: string, projectId: string | undefined): Promise<NamedFlow[]>;
-/**
- * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
- * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
- * change; auto-replaying the affected flows against the app is the next increment. Long-running.
- */
-export declare function handleWatch(): void;
-/**
- * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
- * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
- */
-export declare function handleCapsules(): Promise<void>;
-/**
- * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
- * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
- * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
- */
-export declare function handleGate(files: string[], since: string | undefined, 
-/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook?: boolean): Promise<void>;

package/dist/cli/cli-flow-commands.js

@@ -1,255 +0,0 @@
-/**
- * CLI commands that operate on SAVED FLOWS: watch, capsules, and the gate.
- *
- * Split out of cli.ts, which was 653 lines — over the project's own cap, and the file a contributor
- * opens first. These five functions form one cohesive group: they all read the flow store and report on
- * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
- */
-import { GateExit } from './gate-exit.js';
-import { gateHookMessage, GATE_SKIP_ENV } from './gate-hook-message.js';
-import { readProjectId } from './cli-port.js';
-import { changedFilesSince } from '../flows/git-changed.js';
-import { join } from 'node:path';
-import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
-import { FlowStore } from '../flows/flows.js';
-import { RunStore } from '../runs/run-store.js';
-import { createNodeFileSystem } from '../project/fs-port.js';
-import { affectedSavedFlows } from '../flows/flow-sources.js';
-import { gateDecision } from '../flows/gate.js';
-import { FlakeStore } from '../flows/flake-store.js';
-import { formatBuddyStatus } from '../flows/buddy-status.js';
-import { CapsuleStore } from '../capsule/capsule-store.js';
-import { AssertionTiersStore } from '../flows/assertion-tiers-store.js';
-import { detectDowngrades } from '../flows/assertion-integrity.js';
-import { computeCoverage, flowCoverageReport } from '../flows/coverage.js';
-import { createWatchBatcher } from '../flows/watch-batcher.js';
-import { watch } from 'node:fs';
-import { log } from '../log.js';
-/** Load the {name, steps} of every saved flow for the active project. */
-/** Explicit files plus, when --since is given, the git-changed files since that ref. */
-/**
- * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
- * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
- * where `git diff` answers about the wrong repository or about none.
- */
-export async function resolveChangedFiles(files, since, cwd) {
-    // No ref means no question was asked of git, which is not a failure to answer one.
-    if (since === undefined)
-        return { files, failed: false };
-    const changed = await changedFilesSince(since, cwd);
-    return {
-        files: [...new Set([...files, ...changed.files])],
-        failed: changed.failed,
-        ...(changed.reason === undefined ? {} : { reason: changed.reason }),
-    };
-}
-/**
- * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
- * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
- * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
- * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
- * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
- * confident negative about somebody else's project, which is worse than an error.
- */
-export async function loadNamedFlows(fs, reticleRoot, projectId) {
-    const store = new FlowStore(fs, reticleRoot, { now: () => Date.now() });
-    const flows = [];
-    for (const name of await store.list(projectId)) {
-        const loaded = await store.load(name, projectId);
-        if (loaded.ok)
-            flows.push({ name: loaded.value.name, steps: loaded.value.steps });
-    }
-    return flows;
-}
-/** File-change extensions worth reacting to (skip node_modules churn, dotfiles, build output). */
-/**
- * The buddy channel: one ambient line a human can park in a statusline. Deliberately best-effort
- * and silent on failure — a status line that throws is worse than no status line, and it must never
- * interfere with the watch loop it rides on.
- */
-async function emitBuddyStatus(fs, reticleRoot, flows, affected) {
-    try {
-        const latest = await new RunStore(fs, reticleRoot).latest();
-        const passingNames = new Set((latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name));
-        const quarantined = await new FlakeStore(fs, reticleRoot).flakyFlows();
-        const flaky = new Set(quarantined);
-        // A deviation is an at-risk flow with no passing artifact — and a quarantined flake is not a deviation.
-        const deviations = affected.filter((n) => !passingNames.has(n) && !flaky.has(n));
-        log('reticle_buddy', {
-            status: formatBuddyStatus({
-                total: flows.length,
-                passing: passingNames.size,
-                deviations,
-                quarantined,
-            }),
-        });
-    }
-    catch {
-        // never let the ambient line break the watcher
-    }
-}
-const WATCHED_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/;
-const WATCH_DEBOUNCE_MS = 200;
-/**
- * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
- * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
- * change; auto-replaying the affected flows against the app is the next increment. Long-running.
- */
-export function handleWatch() {
-    const fs = createNodeFileSystem();
-    const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-    const batcher = createWatchBatcher({
-        debounceMs: WATCH_DEBOUNCE_MS,
-        schedule: (fn, ms) => {
-            setTimeout(fn, ms).unref();
-        },
-        onFlush: (files) => {
-            void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
-                .then(async (flows) => {
-                const result = affectedSavedFlows(flows, files);
-                if (result.affected.length > 0) {
-                    log('reticle_watch_affected', { changed: files, affected: result.affected });
-                }
-                await emitBuddyStatus(fs, reticleRoot, flows, result.affected);
-            })
-                .catch((error) => {
-                log('reticle_watch_failed', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            });
-        },
-    });
-    log('reticle_watch_started', { cwd: process.cwd() });
-    // Print the ambient line once at startup so the human sees where they stand before touching anything.
-    void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
-        .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
-        .catch(() => undefined);
-    watch(process.cwd(), { recursive: true }, (_event, filename) => {
-        if ('string' === typeof filename && WATCHED_EXTENSIONS.test(filename))
-            batcher.onChange(filename);
-    });
-}
-/**
- * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
- * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
- */
-export async function handleCapsules() {
-    try {
-        const fs = createNodeFileSystem();
-        const capsules = await new CapsuleStore(fs, join(process.cwd(), ReticleDir.ROOT)).all();
-        log('reticle_capsules', {
-            count: capsules.length,
-            capsules: capsules.map((c) => ({
-                id: c.id,
-                ...(c.flow === undefined ? {} : { flow: c.flow }),
-                origin: c.origin,
-                expected: c.expected,
-                observed: c.observed,
-                steps: c.steps.length,
-            })),
-        });
-    }
-    catch (error) {
-        log('reticle_capsules_failed', {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        process.exitCode = 1;
-    }
-}
-/**
- * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
- * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
- * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
- */
-export async function handleGate(files, since, 
-/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook = false) {
-    try {
-        const fs = createNodeFileSystem();
-        const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-        // Same deliberate degradation as the gate: a terminal caller sees git's own error anyway.
-        const changed = (await resolveChangedFiles(files, since, process.cwd())).files;
-        const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
-        const affected = affectedSavedFlows(allFlows, changed).affected;
-        const latest = await new RunStore(fs, reticleRoot).latest();
-        const passing = (latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name);
-        const flaky = await new FlakeStore(fs, reticleRoot).flakyFlows();
-        // Anti-reward-hacking: diff each flow's CURRENT assertions against what it asserted the last
-        // time it passed. A mustHold that dropped from a real consequence to a fakeable presence check is a
-        // green bought by weakening the test — and a flow that covered a changed file but no longer exists
-        // is coverage deleted rather than satisfied. Both block.
-        const baseline = await new AssertionTiersStore(fs, reticleRoot).load();
-        const byName = new Map(allFlows.map((f) => [f.name, f]));
-        const downgraded = Object.entries(baseline)
-            .filter(([name]) => affected.includes(name) && byName.has(name))
-            .map(([name, before]) => {
-            const current = byName.get(name);
-            const after = (current?.steps ?? []).map((s, i) => ({
-                step: i,
-                ...(s.expect === undefined ? {} : { expect: s.expect }),
-            }));
-            return { flow: name, steps: detectDowngrades(before.steps, after).map((d) => d.step) };
-        })
-            .filter((d) => d.steps.length > 0);
-        // A flow with a recorded passing baseline that has since vanished, while its files changed.
-        // A flow that PASSED covering these files and has since vanished is coverage DELETED, not satisfied —
-        // and it can never appear in `affected` (that is derived from flows that still exist), so it must be
-        // matched against the baseline's own recorded sources. Missing this made deleting a flow turn the
-        // gate green, which is precisely the gaming move exists to stop.
-        const changedSet = new Set(changed);
-        const deleted = Object.entries(baseline)
-            .filter(([name, entry]) => !byName.has(name) && entry.sources.some((f) => changedSet.has(f)))
-            .map(([name]) => name);
-        const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
-        // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
-        const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
-        // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
-        // verdict already applies to `reticle verify`; see flowCoverageReport.
-        const flowCoverage = flowCoverageReport(coverage.flows);
-        const pass = result.pass && flowCoverage.outcome === undefined;
-        log('reticle_gate', {
-            pass,
-            uncovered: result.uncovered,
-            quarantined: result.quarantined,
-            ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
-            ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
-            coverage: flowCoverage,
-        });
-        // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
-        // problem to fail. A Stop hook wants to block a real regression and NOT block a project that
-        // has simply not recorded a flow yet — which is every project on its first day, and measured
-        // before this change as an exit 1 that would have blocked every stop. See GateExit.
-        if (!pass) {
-            const code = result.pass && flowCoverage.outcome !== undefined
-                ? GateExit.NOTHING_TO_CHECK
-                : GateExit.FAIL;
-            process.exitCode = code;
-            if (hook) {
-                // An honest escape hatch, because the alternative to one is not compliance — it is somebody
-                // deleting the hook, and a deleted gate protects nothing. Recorded either way.
-                if (process.env[GATE_SKIP_ENV] !== undefined) {
-                    process.stderr.write(`Reticle: gate skipped via ${GATE_SKIP_ENV}. This change is unverified.\n`);
-                    process.exitCode = GateExit.PASS;
-                    return;
-                }
-                const message = gateHookMessage(code, {
-                    uncovered: result.uncovered,
-                    quarantined: result.quarantined,
-                    // A downgrade is reported per flow with its step indices; the hook names the flow.
-                    downgraded: result.downgraded.map((d) => d.flow),
-                    deleted: result.deleted,
-                });
-                if (message !== undefined)
-                    process.stderr.write(`${message}\n`);
-            }
-        }
-    }
-    catch (error) {
-        log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exitCode = GateExit.FAIL;
-    }
-}

package/dist/cli/cli-kill.d.ts

@@ -1,59 +0,0 @@
-/**
- * `reticle kill` — free the bridge port without taking the agent's transport with it.
- *
- * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
- * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
- * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
- * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
- * because the process that writes it is the one that died. That is the mechanism behind most
- * "my MCP disconnected" reports (#114, #110).
- *
- * The safe form was written down, and a documented incantation is a worse answer than a command: it
- * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
- * the command, and it signals exactly one pid — the LISTENER.
- *
- * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
- * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
- * written, or belongs to a daemon from another checkout. `kill` asks the PORT, which is the thing the
- * user actually wants freed, and falls back to the pid file only where the lookup cannot run.
- */
-import { type PortHolder } from './port-holder.js';
-/** What the plan says to do with the port. */
-export declare const KillAction: {
-    readonly NOTHING: "nothing";
-    readonly KILL: "kill";
-    readonly REFUSE: "refuse";
-};
-export type KillAction = (typeof KillAction)[keyof typeof KillAction];
-interface KillPlan {
-    action: KillAction;
-    /** The single pid to signal. Present only for `kill`. */
-    pid?: number;
-    /** True when the target was not identifiable as Reticle's and `--force` overrode the refusal. */
-    forced: boolean;
-    /** False when the listener lookup could not run, so the pid came from our own records instead. */
-    identifiedListener: boolean;
-    /** Why we will not act, for `refuse`. */
-    reason?: string;
-    holder?: PortHolder;
-}
-export declare const FORCE_FLAG = "--force";
-/**
- * Decide what to signal. Pure.
- *
- * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
- * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
- * records. Refusing it would leave the port held by exactly the process this command exists to clear.
- */
-export declare function planKill(input: {
-    /** The listener on the port, from a `-sTCP:LISTEN` lookup. Null when there is none, or no `lsof`. */
-    listener: PortHolder | null;
-    /** The pid our records hold for this port, or null when there is none or it is dead. */
-    recordedPid: number | null;
-    /** Whether the port answers `/status`, i.e. whatever holds it is a Reticle daemon. */
-    answersStatus: boolean;
-    force: boolean;
-}): KillPlan;
-/** `reticle kill` — free the port. Resolves to whether the port is now free. */
-export declare function runKill(port: number, force: boolean): Promise<boolean>;
-export {};

package/dist/cli/cli-kill.js

@@ -1,162 +0,0 @@
-/**
- * `reticle kill` — free the bridge port without taking the agent's transport with it.
- *
- * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
- * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
- * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
- * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
- * because the process that writes it is the one that died. That is the mechanism behind most
- * "my MCP disconnected" reports (#114, #110).
- *
- * The safe form was written down, and a documented incantation is a worse answer than a command: it
- * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
- * the command, and it signals exactly one pid — the LISTENER.
- *
- * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
- * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
- * written, or belongs to a daemon from another checkout. `kill` asks the PORT, which is the thing the
- * user actually wants freed, and falls back to the pid file only where the lookup cannot run.
- */
-import { PortPresence, probePresence } from '../daemon/port-presence.js';
-import { isAlive, readPid, removePid } from '../daemon/daemon.js';
-import { probeDaemon } from '../mcp/mcp-proxy.js';
-import { log } from '../log.js';
-import { fetchStatus } from './cli-launch.js';
-import { captureLookup, findPortHolder } from './port-holder.js';
-/** What the plan says to do with the port. */
-export const KillAction = {
-    NOTHING: 'nothing',
-    KILL: 'kill',
-    REFUSE: 'refuse',
-};
-export const FORCE_FLAG = '--force';
-/**
- * Decide what to signal. Pure.
- *
- * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
- * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
- * records. Refusing it would leave the port held by exactly the process this command exists to clear.
- */
-export function planKill(input) {
-    const { listener, recordedPid, answersStatus, force } = input;
-    if (null === listener) {
-        // No listener identified. On Windows and in slim containers that means the lookup could not run
-        // rather than that the port is free, so the recorded pid is the best target we have — and the
-        // report says which of the two it is rather than implying a lookup we never made.
-        if (null === recordedPid)
-            return { action: KillAction.NOTHING, forced: false, identifiedListener: false };
-        return { action: KillAction.KILL, pid: recordedPid, forced: false, identifiedListener: false };
-    }
-    const ours = answersStatus || listener.pid === recordedPid;
-    if (ours || force) {
-        return {
-            action: KillAction.KILL,
-            pid: listener.pid,
-            forced: !ours,
-            identifiedListener: true,
-            holder: listener,
-        };
-    }
-    return {
-        action: KillAction.REFUSE,
-        forced: false,
-        identifiedListener: true,
-        holder: listener,
-        reason: `pid ${String(listener.pid)} ("${listener.command}") is listening, and it is not a Reticle ` +
-            `daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would ` +
-            `be killing someone else's process. Run it again with ${FORCE_FLAG} if that is what you ` +
-            `meant, or start Reticle on another port.`,
-    };
-}
-/** How long the target gets to exit on SIGTERM before we stop asking politely. */
-const GRACEFUL_KILL_MS = 5_000;
-/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
-const FORCED_KILL_MS = 2_000;
-const KILL_POLL_MS = 100;
-/**
- * Signal ONE pid and wait for it to go: SIGTERM, then SIGKILL, then give up and say it survived.
- *
- * The escalation is the reason this exists rather than a bare SIGTERM — there is a field report of a
- * daemon that ignored SIGTERM until a human ran `kill -9` by hand, which is the moment the `lsof -ti`
- * pipeline gets typed and the agent's proxy dies with the daemon.
- */
-async function terminate(pid) {
-    const signal = (name) => {
-        try {
-            process.kill(pid, name);
-        }
-        catch {
-            // Gone between the liveness check and here. The next poll reports it as gone.
-        }
-    };
-    signal('SIGTERM');
-    const started = Date.now();
-    let escalated = false;
-    for (;;) {
-        await new Promise((resolve) => setTimeout(resolve, KILL_POLL_MS));
-        if (!isAlive(pid))
-            return { gone: true, escalated };
-        const waited = Date.now() - started;
-        if (!escalated && waited > GRACEFUL_KILL_MS) {
-            escalated = true;
-            signal('SIGKILL');
-            continue;
-        }
-        if (waited > GRACEFUL_KILL_MS + FORCED_KILL_MS)
-            return { gone: false, escalated };
-    }
-}
-/**
- * What was NOT touched, said out loud on every kill.
- *
- * The command exists because of a pipeline that killed more than the reader intended and never told
- * them, so a report that lists only the casualty repeats half the mistake. An `reticle mcp` proxy on
- * this port survives, and its own recovery from a dead daemon is good: it goes dormant and restarts
- * one on the next request.
- */
-const PROXY_SPARED_NOTE = 'only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, ' +
-    'not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call.';
-/** `reticle kill` — free the port. Resolves to whether the port is now free. */
-export async function runKill(port, force) {
-    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
-    const recorded = readPid(port);
-    const plan = planKill({
-        listener: findPortHolder(port, captureLookup),
-        recordedPid: null !== recorded && isAlive(recorded) ? recorded : null,
-        answersStatus: presence === PortPresence.DAEMON,
-        force,
-    });
-    if (KillAction.NOTHING === plan.action) {
-        removePid(port);
-        log('reticle_kill_nothing_to_do', { port, presence });
-        return true;
-    }
-    if (KillAction.REFUSE === plan.action) {
-        log('reticle_kill_refused', { port, reason: plan.reason, holder: plan.holder?.command });
-        return false;
-    }
-    const pid = plan.pid;
-    if (pid === undefined) {
-        // Unreachable by construction (planKill never returns KILL without a pid, and a test pins that),
-        // but the alternative to this branch is a non-null assertion, which this codebase does not use.
-        log('reticle_kill_nothing_to_do', { port, presence });
-        return true;
-    }
-    const { gone, escalated } = await terminate(pid);
-    if (gone)
-        removePid(port);
-    log(gone ? 'reticle_killed' : 'reticle_kill_survived', {
-        port,
-        pid,
-        escalated,
-        ...(plan.forced ? { forced: true } : {}),
-        // Say where the pid came from. Without `lsof` this is the pid we recorded, not the pid we
-        // observed listening, and those are different claims.
-        listenerIdentified: plan.identifiedListener,
-        note: gone
-            ? PROXY_SPARED_NOTE
-            : `pid ${String(pid)} survived SIGKILL, so it is not yours to kill (permissions) or is an ` +
-                `unkillable zombie. The port is still held. ${PROXY_SPARED_NOTE}`,
-    });
-    return gone;
-}

package/dist/cli/cli-launch.d.ts

@@ -1,92 +0,0 @@
-/**
- * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
- * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
- * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
- */
-/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
-interface StatusSession {
-    sessionId: string;
-    url: string;
-    throttled: boolean;
-    stale: boolean;
-    pendingMarks: number;
-    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
-    unresponsive?: true;
-}
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export declare function summarizeStatus(payload: unknown): {
-    sessionCount: number;
-    sessions: StatusSession[];
-    why?: string;
-};
-/**
- * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
- *
- * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
- * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
- * another agent's session on a version bump, which is worse than a loud line.
- */
-export declare function warnOnDaemonSkew(port: number): Promise<void>;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export declare function fetchStatus(port: number): Promise<unknown>;
-/** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
-type OpenDecision = {
-    action: 'reuse';
-    url: string;
-}
-/** A tab on that origin exists, but on another page — kept, and NOT reported as done. */
- | {
-    action: 'left-as-is';
-    url: string;
-    requested: string;
-} | {
-    action: 'open';
-    url: string;
-} | {
-    action: 'need-url';
-};
-/**
- * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
- * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
- * - no url + nothing connected → ask for one.
- * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
- * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
- * - url + no matching tab → open it.
- *
- * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
- * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
- * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
- * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
- * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
- * is a bigger surprise than being told where the tab actually is.
- */
-export declare function decideOpen(all: {
-    url: string;
-    unresponsive?: boolean;
-}[], url: string | undefined): OpenDecision;
-/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
-export declare function openCommand(url: string, platform: NodeJS.Platform): {
-    cmd: string;
-    args: string[];
-};
-/**
- * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
- *
- * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
- * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
- * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
- * port problem while nothing had ever opened.
- */
-export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => Promise<string | null>): Promise<string | null>;
-/**
- * What a finished launcher means, or null when nothing is wrong.
- *
- * Exported for its own tests: the headless case is the one that matters and it cannot be produced
- * by spawning a real launcher on a developer machine.
- */
-export declare function launcherFailure(code: number | null, signal: NodeJS.Signals | null): string | null;
-export {};