@naswerks/periscope 1.0.0

package/dist/bin/command.js

@@ -0,0 +1,141 @@
+/**
+ * Which command the binary was asked for.
+ *
+ * Extracted out of the composition root so it can be called without starting a host, the same
+ * reason, and the same shape, as `workspaces.ts`. `bin/periscope.ts` calls `main()` on load, so
+ * importing it to test one function starts a host, opens a socket and spawns nothing useful. The
+ * fix is to split the function out; it is not to add a startup guard to the entry point, because
+ * changing production behaviour to make a test possible is how a suite starts describing a system
+ * nobody ships.
+ *
+ * The parser is deliberately tiny and not an option library. This package's direct dependencies
+ * are the agent SDK with its peer closure, `ws` and `zod`; a CLI framework for a handful of verbs
+ * would be a new dependency in a package whose boundary claims are auditable from one directory.
+ */
+/**
+ * Read the command from an argv tail (`process.argv.slice(2)`).
+ *
+ * No arguments means `serve`, and that is a contract rather than a preference: a supervisor or
+ * container starts this binary with no arguments, so a bare invocation is the daemon.
+ *
+ * An unrecognised first argument is `unknown`, never `serve`. Falling back to the default would
+ * mean `periscope logn` silently starts a host: the operator believes they are signing in, the
+ * process dials out and starts accepting sessions, and the mistake surfaces much later as an empty
+ * token cache. A typo must fail loudly at the only moment it is cheap to fix.
+ */
+export function readCommand(argv) {
+    const first = argv[0];
+    if (first === undefined || first === '')
+        return { kind: 'serve' };
+    switch (first) {
+        case 'serve':
+            return { kind: 'serve' };
+        case 'login':
+            return { kind: 'login' };
+        case 'pair':
+            return readPairArguments(argv.slice(1));
+        case 'config': {
+            if (argv[1] === '--unset') {
+                const key = argv[2];
+                return {
+                    kind: 'config',
+                    key: key === undefined || key === '' ? null : key,
+                    value: null,
+                    unset: true,
+                };
+            }
+            const key = argv[1];
+            const value = argv[2];
+            return {
+                kind: 'config',
+                key: key === undefined || key === '' ? null : key,
+                value: value === undefined || value === '' ? null : value,
+                unset: false,
+            };
+        }
+        case 'version':
+        case '--version':
+        case '-v':
+            return { kind: 'version' };
+        case 'status':
+            return { kind: 'status' };
+        case 'help':
+        case '--help':
+        case '-h':
+            return { kind: 'help' };
+        default:
+            return { kind: 'unknown', name: first };
+    }
+}
+/** The two flags `pair` takes. A closed set: anything else starting with `--` is a problem, never the code. */
+const PAIR_FLAGS = ['--controller', '--label'];
+/**
+ * `pair`'s tail: one positional (the code) and two optional flags, each as `--flag value` or
+ * `--flag=value`. Hand-rolled for the same reason the whole parser is: two flags do not earn an
+ * option library. An unknown `--x` is a problem rather than the code, so a typo'd flag cannot be
+ * sent to the controller as a pair code and refused there with the wrong message.
+ */
+function readPairArguments(rest) {
+    let code = null;
+    let controller = null;
+    let label = null;
+    let problem = null;
+    for (let index = 0; index < rest.length; index += 1) {
+        const argument = rest[index] ?? '';
+        if (argument.startsWith('--')) {
+            const equals = argument.indexOf('=');
+            const name = equals === -1 ? argument : argument.slice(0, equals);
+            if (!PAIR_FLAGS.includes(name)) {
+                problem ??= `unknown option '${name}'`;
+                continue;
+            }
+            let value;
+            if (equals === -1) {
+                value = rest[index + 1];
+                index += 1;
+            }
+            else {
+                value = argument.slice(equals + 1);
+            }
+            if (value === undefined || value === '') {
+                problem ??= `${name} needs a value`;
+                continue;
+            }
+            if (name === '--controller')
+                controller = value;
+            else
+                label = value;
+            continue;
+        }
+        if (argument === '')
+            continue;
+        if (code === null)
+            code = argument;
+        else
+            problem ??= `unexpected argument '${argument}'`;
+    }
+    return { kind: 'pair', code, controller, label, problem };
+}
+/** What `help` prints. Kept beside the parser so a new verb cannot be added without a line here. */
+export const USAGE = [
+    'periscope — hosts Claude Code sessions for a remote controller.',
+    '',
+    'Usage:',
+    '  periscope [serve]        Dial the controller and serve sessions (the default).',
+    '  periscope login          Sign in and write the token cache this host presents.',
+    '  periscope pair <code> [--controller <origin>] [--label <name>]',
+    "                           Trade a pair code for this machine's durable credential. The controller",
+    '                           origin names where to redeem and writes the link URLs to the config file;',
+    '                           the label is what the controller lists this machine as.',
+    '  periscope config                 Show the config file and every value in it.',
+    '  periscope config <key> [value]   Read one config value, or write it.',
+    '  periscope config --unset <key>   Remove one config value from the file.',
+    '  periscope status         Say what this host is: its link, credential, ids, workspace and where',
+    '                           each setting came from. Reads what serve left behind; never dials.',
+    '  periscope version        Print the package version.',
+    '  periscope help           Show this.',
+    '',
+    'Configuration is read from the environment first, then the config file (the environment wins);',
+    'see README.md.',
+].join('\n');
+//# sourceMappingURL=command.js.map

package/dist/bin/config.d.ts

@@ -0,0 +1,7 @@
+/** What one invocation produced: the lines to print, and whether it succeeded. */
+export interface ConfigOutcome {
+    readonly ok: boolean;
+    readonly lines: readonly string[];
+}
+export declare function runConfig(key: string | null, value: string | null, env: NodeJS.ProcessEnv, unset?: boolean): ConfigOutcome;
+//# sourceMappingURL=config.d.ts.map

package/dist/bin/config.js

@@ -0,0 +1,90 @@
+/**
+ * `periscope config` — read or write the config file the daemon falls back to.
+ *
+ * Why this is a command: the binary reads its configuration from the environment first and the
+ * file second (every consuming verb: `serve`, `login`, `pair`), and nothing else in this package
+ * ever writes that file. Without it, a user installing the host on a machine with no UI has
+ * exactly one configuration surface, env vars at process start, which is a supervisor's surface,
+ * not a person's. This verb is the person's.
+ *
+ * It orchestrates only. The filesystem work lives in `host/config-file.ts`, because `src/host/`
+ * is the one directory allowed to touch the machine; this module composes that seam and formats
+ * lines, exactly the split `login` and `pair` use.
+ *
+ * The output says what wins. Every listing line marks a value the environment currently
+ * overrides, because "set it and nothing changed" with a stale env var standing in front of the
+ * file is otherwise confusing; the rule is env-wins and the listing repeats it where the operator
+ * is looking.
+ */
+import { CONFIG_KEYS, configFilePath, readConfigFile, writeConfigEntries, writeConfigEntry, } from '../host/config-file.js';
+import { configValueProblem } from './reconfigure.js';
+export function runConfig(key, value, env, unset = false) {
+    const path = configFilePath(env);
+    if (path === null) {
+        return {
+            ok: false,
+            lines: ['there is nowhere to keep a config file — no home directory and no PERISCOPE_CONFIG_DIR'],
+        };
+    }
+    if (unset) {
+        if (key === null)
+            return { ok: false, lines: ['usage: periscope config --unset <key>'] };
+        const reading = readConfigFile(env);
+        if (reading.problem !== null)
+            return { ok: false, lines: [reading.problem] };
+        if (reading.values[key] === undefined)
+            return { ok: true, lines: [`${key} is not set in ${path}`] };
+        const problem = writeConfigEntries(env, [{ key, value: null }]);
+        if (problem !== null)
+            return { ok: false, lines: [problem] };
+        return { ok: true, lines: [`${key} removed from ${path}`] };
+    }
+    if (key === null) {
+        const reading = readConfigFile(env);
+        if (reading.problem !== null)
+            return { ok: false, lines: [reading.problem] };
+        const entries = Object.entries(reading.values);
+        const lines = [
+            `config file: ${path}`,
+            ...(entries.length === 0 ? ['(empty — set a value with: periscope config <key> <value>)'] : []),
+            ...entries.map(([name, stored]) => {
+                const fromEnv = env[name];
+                const overridden = fromEnv !== undefined && fromEnv !== '' ? '  (currently overridden by the environment)' : '';
+                return `  ${name} = ${stored}${overridden}`;
+            }),
+            `keys this host reads: ${CONFIG_KEYS.join(', ')}`,
+        ];
+        return { ok: true, lines };
+    }
+    if (value === null) {
+        const reading = readConfigFile(env);
+        if (reading.problem !== null)
+            return { ok: false, lines: [reading.problem] };
+        const stored = reading.values[key];
+        if (stored === undefined) {
+            return { ok: false, lines: [`${key} is not set in ${path}`] };
+        }
+        return { ok: true, lines: [stored] };
+    }
+    // The same screen the wire runs on `host_configure`, before anything is written: a value the
+    // daemon would refuse at its next start is refused here, where the person typing it is looking.
+    const screened = configValueProblem(key, value);
+    if (screened !== null)
+        return { ok: false, lines: [screened] };
+    const problem = writeConfigEntry(env, key, value);
+    if (problem !== null)
+        return { ok: false, lines: [problem] };
+    const fromEnv = env[key];
+    return {
+        ok: true,
+        lines: [
+            `${key} written to ${path}`,
+            ...(fromEnv !== undefined && fromEnv !== ''
+                ? [
+                    `note: ${key} is currently set in the environment, and the environment wins — the file value is a fallback`,
+                ]
+                : []),
+        ],
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/bin/login.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `periscope login` — acquire a token interactively and write it to the cache the daemon reads.
+ *
+ * Why this is a command rather than something the daemon does: `bin/serve.ts` presents a
+ * token that is already there; there is no interactive flow in the shipped daemon, deliberately,
+ * because a host meant to run unattended must not block on a browser at start-up. So the
+ * interactive half is a separate act, run once by a person, and the daemon is unchanged by this
+ * file existing.
+ *
+ * It writes the same cache the daemon reads, derived from the same call. `tokenCachePath(env)` is
+ * the one source for the location, and `credentialPaths(env)`, which the gate uses to build its
+ * protected set, derives from it too. Nothing here may compute a path of its own, or the thing the
+ * gate refuses to let an agent read and the thing this writes could drift apart.
+ *
+ * The flow is derived from config, never chosen here. `protocolFor(config)` picks loopback or
+ * device-code, and the daemon's credential calls the same function to decide what it expects, so a
+ * cache written under one protocol can never be read under the other. (`TokenCredential` discards a
+ * cache whose protocol does not match, so getting this wrong would look like "signing in did
+ * nothing".) Setting `PERISCOPE_IDENTITY_DEVICE_CODE=1` moves both ends together, which is the
+ * property that makes it safe to expose as one environment variable.
+ */
+import type { Result } from '../core/result.js';
+import type { CachedTokens, TokenStore } from '../identity/index.js';
+import { signIn, signInWithDeviceCode } from '../host/index.js';
+/** The edges, injected so the whole command is testable without a browser, a socket or a clock. */
+export interface LoginDeps {
+    /** Where operator-facing instructions go. Defaults to stdout. */
+    readonly write?: (line: string) => void;
+    /** Replaced in tests; the real ones talk to the provider. */
+    readonly signIn?: typeof signIn;
+    readonly signInWithDeviceCode?: typeof signInWithDeviceCode;
+    /** Replaced in tests so nothing touches the real cache path. Defaults to the file cache at `path`. */
+    readonly store?: (path: string) => TokenStore;
+    /**
+     * Whether a paired credential is present at `path`. Replaced in tests. The daemon prefers a
+     * paired credential over the token this verb writes, so a signed-in operator on a paired box is
+     * told the token will not be the one presented.
+     */
+    readonly pairedCredentialPresent?: (path: string) => boolean;
+}
+/**
+ * Run the login command.
+ *
+ * Returns a `Result` rather than exiting, so the caller owns the process and this stays callable
+ * from a test. Every failure is a named refusal, the same posture the rest of the package holds.
+ */
+export declare function runLogin(env: NodeJS.ProcessEnv, deps?: LoginDeps): Promise<Result<CachedTokens>>;
+//# sourceMappingURL=login.d.ts.map

package/dist/bin/login.js

@@ -0,0 +1,82 @@
+import { ok, refuse } from '../core/result.js';
+import { isAuthFlowBlocked, readIdentityConfig } from '../identity/index.js';
+import { FilePairedCredential, FileTokenCache, pairedCredentialPath, protocolFor, signIn, signInWithDeviceCode, tokenCachePath, } from '../host/index.js';
+/**
+ * Run the login command.
+ *
+ * Returns a `Result` rather than exiting, so the caller owns the process and this stays callable
+ * from a test. Every failure is a named refusal, the same posture the rest of the package holds.
+ */
+export async function runLogin(env, deps = {}) {
+    const write = deps.write ?? ((line) => process.stdout.write(`${line}\n`));
+    // Said once, on success: the daemon prefers a paired credential over the token this verb writes,
+    // so an operator signing in on a paired box is told the token will not be the one presented.
+    const pairedPath = pairedCredentialPath(env);
+    const pairedPresent = deps.pairedCredentialPresent ?? ((path) => new FilePairedCredential(path).read().ok);
+    const pairedNotice = pairedPath !== null && pairedPresent(pairedPath)
+        ? `note: this machine holds a paired credential at ${pairedPath}, and the daemon presents that on ` +
+            'every dial in preference to this token'
+        : null;
+    // The config module's own read and its own refusal, restated nowhere.
+    //
+    // Two reasons, and the second is enforced. (1) "Configured" must mean the identical thing here and
+    // in the daemon; an operator who can sign in but whose host then refuses to start is the worst
+    // outcome available. (2) `pins/identity-generic.test.ts` asserts that exactly one shipped file
+    // names the authority environment variable, because a second mention is a second answer to "which
+    // provider is this host talking to". Naming those variables here, even in a comment or a message
+    // string, since the pin reads source text, trips it, and it is right to: the fix is to carry the
+    // one refusal that already exists rather than write a second copy that can drift.
+    //
+    // Not a default, a refusal. There is no fallback issuer and no implicit tenant: signing in
+    // "somewhere" would mint a token this controller cannot validate, and the failure would surface
+    // much later as a 401 on the upgrade with nothing naming the cause.
+    const read = readIdentityConfig(env);
+    if (!read.ok)
+        return refuse(read.refusal.reason, read.refusal.detail);
+    const config = read.value;
+    const cachePath = tokenCachePath(env);
+    if (cachePath === null) {
+        return refuse('identity-config-invalid', 'identity is configured but there is nowhere to keep the token cache — set PERISCOPE_CONFIG_DIR');
+    }
+    const store = (deps.store ?? ((path) => new FileTokenCache(path)))(cachePath);
+    const protocol = protocolFor(config);
+    if (protocol === 'device-code') {
+        // The headless flow, and it must stay reachable without a redirect port. This is the flow for
+        // a box with no browser, such as a server or a container. It takes no listener and binds
+        // nothing.
+        const run = deps.signInWithDeviceCode ?? signInWithDeviceCode;
+        const result = await run(config, store, (instruction) => {
+            write(`open ${instruction.verificationUri} and enter the code: ${instruction.userCode}`);
+        });
+        return finish(result, cachePath, write, pairedNotice);
+    }
+    // Loopback + PKCE: the primary flow. `signIn` binds an ephemeral port and closes it on every path;
+    // its default `present` prints the URL, which is what works over SSH.
+    const run = deps.signIn ?? signIn;
+    const result = await run(config, store, {
+        present: (url) => write(`open this to sign in:\n${url}`),
+    });
+    return finish(result, cachePath, write, pairedNotice);
+}
+/**
+ * Report the outcome once, in the operator's words.
+ *
+ * A policy-blocked flow is surfaced with its do-not-retry rule attached. A provider policy blocking
+ * the device-code flow refuses identically every time, so an operator who reads a bare failure will
+ * re-run it, and the second attempt costs the same and fails the same way.
+ */
+function finish(result, cachePath, write, pairedNotice) {
+    if (!result.ok) {
+        write(`sign-in failed: ${result.refusal.reason} — ${result.refusal.detail}`);
+        if (isAuthFlowBlocked(result.refusal.detail)) {
+            write('do not re-run the device code flow: the same policy will block it, every time. ' +
+                'Use the loopback flow (unset PERISCOPE_IDENTITY_DEVICE_CODE) or have the policy changed.');
+        }
+        return result;
+    }
+    write(`signed in; token cache written to ${cachePath}`);
+    if (pairedNotice !== null)
+        write(pairedNotice);
+    return ok(result.value);
+}
+//# sourceMappingURL=login.js.map

package/dist/bin/main.d.ts

@@ -0,0 +1,33 @@
+import { runConfig } from './config.js';
+import { runLogin } from './login.js';
+import { runPair } from './pair.js';
+import type { ServeOutcome, ServeViews } from './serve.js';
+import { runStatus } from './status.js';
+/** The process edges. `processIo()` is the real set; a test supplies recording ones. */
+export interface Io {
+    /** One stdout line, without its newline. */
+    readonly stdout: (line: string) => void;
+    /** One stderr line, without its newline. */
+    readonly stderr: (line: string) => void;
+    readonly setExitCode: (code: number) => void;
+    /** The verbs, replaceable so the dispatch is testable without a provider, a controller or a host. */
+    readonly runLogin?: typeof runLogin;
+    readonly runPair?: typeof runPair;
+    readonly runConfig?: typeof runConfig;
+    readonly serve?: (views: ServeViews) => ServeOutcome;
+    readonly runStatus?: typeof runStatus;
+    /** The package version, replaceable so the dispatch test does not read the manifest. */
+    readonly version?: () => string;
+}
+/** The real process edges: stdout, stderr and the exit code. The verbs take their defaults. */
+export declare function processIo(): Io;
+/**
+ * The command dispatch.
+ *
+ * `serve` runs synchronously, which is the path every supervisor takes. `login` and `pair` are the
+ * asynchronous verbs; each returns its own promise so a caller can await the outcome, and nothing
+ * about the daemon's start-up ordering depends on them. `raw` is the process environment as
+ * received; the merged view, where the config file fills absences, is derived per verb.
+ */
+export declare function main(argv: readonly string[], raw: NodeJS.ProcessEnv, io: Io): Promise<void> | void;
+//# sourceMappingURL=main.d.ts.map

package/dist/bin/main.js

@@ -0,0 +1,173 @@
+/**
+ * The composition root, and the only place this package reads the environment.
+ *
+ * Everything below takes its configuration as arguments. That is what makes the rest of the
+ * package testable without a process, and it is why "where does this value come from?" has one
+ * answer instead of one per module. `main` itself takes the environment and the process edges as
+ * arguments for the same reason; `bin/periscope.ts` is the one line that hands it the real ones.
+ */
+import { readConfigFile, withConfigFallback } from '../host/config-file.js';
+import { packageVersion } from '../host/package-facts.js';
+import { USAGE, readCommand } from './command.js';
+import { runConfig } from './config.js';
+import { runLogin } from './login.js';
+import { runPair } from './pair.js';
+import { runServe } from './serve.js';
+import { runStatus } from './status.js';
+/** The real process edges: stdout, stderr and the exit code. The verbs take their defaults. */
+export function processIo() {
+    return {
+        stdout: (line) => {
+            process.stdout.write(`${line}\n`);
+        },
+        stderr: (line) => {
+            process.stderr.write(`${line}\n`);
+        },
+        setExitCode: (code) => {
+            process.exitCode = code;
+        },
+    };
+}
+/**
+ * The config file fills absences, and only absences, for every verb that consumes configuration
+ * (`serve`, `login`, `pair`), which is what makes USAGE's unconditional env-first-then-file
+ * sentence true. The merged view is consulted for the closed key set only, so a deployment that
+ * sets env vars is configured by them alone, and nothing outside that set (identity configuration,
+ * the config dir itself) can arrive from a file. A file that exists and cannot be used is fatal
+ * rather than silently empty: a corrupt file must not impersonate a deliberate absence (the paired
+ * credential takes the same posture, for the same reason).
+ *
+ * `pair` belongs on that list: `PERISCOPE_DECISION_URL` is a legal config key and is exactly what
+ * `redemptionUrl` derives the redemption door from, so a config-file-only machine handed raw env
+ * would answer "nowhere to redeem the code" at the first step of the very flow the config verb was
+ * built for. `login` reads no config key today; it rides the merged view so the help text's claim
+ * is true by wiring rather than by coincidence.
+ */
+function environmentWithConfigFile(raw) {
+    const fileConfig = readConfigFile(raw);
+    if (fileConfig.problem !== null)
+        return fileConfig.problem;
+    return withConfigFallback(raw, fileConfig.values);
+}
+/** `error` as one line, for a verb that threw instead of returning. */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The command dispatch.
+ *
+ * `serve` runs synchronously, which is the path every supervisor takes. `login` and `pair` are the
+ * asynchronous verbs; each returns its own promise so a caller can await the outcome, and nothing
+ * about the daemon's start-up ordering depends on them. `raw` is the process environment as
+ * received; the merged view, where the config file fills absences, is derived per verb.
+ */
+export function main(argv, raw, io) {
+    const command = readCommand(argv);
+    if (command.kind === 'help') {
+        io.stdout(USAGE);
+        return;
+    }
+    if (command.kind === 'version') {
+        io.stdout((io.version ?? packageVersion)());
+        return;
+    }
+    if (command.kind === 'unknown') {
+        // Named rather than defaulted to `serve` (see `readCommand`): a typo that silently starts a host
+        // is discovered much later, as an empty token cache.
+        io.stderr(`periscope: unknown command '${command.name}'\n\n${USAGE}`);
+        io.setExitCode(1);
+        return;
+    }
+    if (command.kind === 'login') {
+        const env = environmentWithConfigFile(raw);
+        if (typeof env === 'string') {
+            io.stderr(`periscope: ${env}`);
+            io.setExitCode(1);
+            return;
+        }
+        // The interactive half is a separate act by design; the daemon never signs anyone in.
+        return (io.runLogin ?? runLogin)(env).then((result) => {
+            if (!result.ok) {
+                io.stderr(`periscope: login failed - ${result.refusal.reason} - ${result.refusal.detail}`);
+                io.setExitCode(1);
+            }
+        }, 
+        // `runLogin` returns refusals rather than throwing, so this branch is for the failure it did
+        // not model. Without it a throw here would be an unhandled rejection followed by exit 0: a
+        // sign-in that crashed reporting success to whoever scripted it.
+        (error) => {
+            io.stderr(`periscope: login failed - ${describe(error)}`);
+            io.setExitCode(1);
+        });
+    }
+    if (command.kind === 'status') {
+        const outcome = (io.runStatus ?? runStatus)({ raw, merged: environmentWithConfigFile(raw) });
+        const sink = outcome.ok ? io.stdout : io.stderr;
+        for (const line of outcome.lines)
+            sink(outcome.ok ? line : `periscope: ${line}`);
+        if (!outcome.ok)
+            io.setExitCode(1);
+        return;
+    }
+    if (command.kind === 'config') {
+        // Synchronous by nature: one file read or one file write, no network, no process.
+        //
+        // Raw env, deliberately. This is the one verb that must never see the merged view, twice over:
+        // its "currently overridden by the environment" marker exists to distinguish env from file,
+        // and a merged env would mark every file value as overridden by itself; and this verb is the
+        // escape hatch that makes fatal-on-corrupt safe everywhere else. A corrupt file must still
+        // leave `periscope config` able to say which file is broken and why, rather than refusing
+        // before the verb runs.
+        const outcome = (io.runConfig ?? runConfig)(command.key, command.value, raw, command.unset);
+        const sink = outcome.ok ? io.stdout : io.stderr;
+        for (const line of outcome.lines)
+            sink(line);
+        if (!outcome.ok)
+            io.setExitCode(1);
+        return;
+    }
+    if (command.kind === 'pair') {
+        if (command.problem !== null) {
+            io.stderr(`periscope: ${command.problem} - usage: periscope pair <code> [--controller <origin>] [--label <name>]`);
+            io.setExitCode(1);
+            return;
+        }
+        const env = environmentWithConfigFile(raw);
+        if (typeof env === 'string') {
+            io.stderr(`periscope: ${env}`);
+            io.setExitCode(1);
+            return;
+        }
+        // The same shape as `login`, for the same reasons, including the rejection branch, because a
+        // pairing that crashed must not report success to whoever scripted it.
+        return (io.runPair ?? runPair)(command.code, env, undefined, {
+            controller: command.controller,
+            label: command.label,
+        }).then((result) => {
+            if (!result.ok) {
+                io.stderr(`periscope: pair failed - ${result.detail}`);
+                io.setExitCode(1);
+            }
+        }, (error) => {
+            io.stderr(`periscope: pair failed - ${describe(error)}`);
+            io.setExitCode(1);
+        });
+    }
+    // The daemon reads two views: configuration from the merged one, credentials and the session
+    // environment from the raw one. `runServe` says which reads which, and reports its own refusals.
+    const serve = io.serve ?? ((views) => runServe(views, processServeDeps(io)));
+    serve({ raw, merged: environmentWithConfigFile(raw) });
+}
+/** The daemon's edges over a caller-supplied `io`, with the process itself behind exit and signals. */
+function processServeDeps(io) {
+    return {
+        log: io.stdout,
+        stderr: io.stderr,
+        setExitCode: io.setExitCode,
+        exit: (code) => process.exit(code),
+        onSignal: (signal, handler) => {
+            process.on(signal, handler);
+        },
+    };
+}
+//# sourceMappingURL=main.js.map

package/dist/bin/pair.d.ts

@@ -0,0 +1,28 @@
+import type { PairedCredentialStore } from '../identity/paired-credential.js';
+/** The two flags: null means "not given", and the environment path applies. */
+export interface PairAsk {
+    readonly controller?: string | null;
+    readonly label?: string | null;
+}
+/** The verb's outcome: plain, CLI-local, and deliberately not the wire's refusal vocabulary.
+ * Nothing here crosses the link, so nothing here may widen it. */
+export type PairOutcome = {
+    readonly ok: true;
+    readonly hostId: string;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** The edges, injected so the whole verb is testable without a controller or a disk. */
+export interface PairDeps {
+    /** Where operator-facing lines go. Defaults to stdout. */
+    readonly write?: (line: string) => void;
+    /** The HTTP edge. Defaults to global fetch. */
+    readonly transport?: typeof fetch;
+    /** Replaced in tests so nothing touches the real credential path. */
+    readonly store?: (path: string) => PairedCredentialStore;
+}
+/** Run the pair command. Returns rather than exits, so the caller owns the process. */
+export declare function runPair(code: string | null, env: NodeJS.ProcessEnv, deps?: PairDeps, asked?: PairAsk): Promise<PairOutcome>;
+//# sourceMappingURL=pair.d.ts.map