@naswerks/periscope 1.0.0

package/dist/bin/serve.js

@@ -0,0 +1,441 @@
+import { FilePairedCredential, FileTokenCache, PeriscopeHost, defaultAgentHome, transcriptsRootUnder, claudeTranscriptResolver, credentialPaths, packageVersion, pairedCredentialPath, protocolFor, readMachineFacts, refresherFor, resolveEndpoints, tokenCachePath, } from '../host/index.js';
+import { escalatingDecider } from '../gate/escalate.js';
+import { PairedHostCredential, TokenCredential, identityPosture } from '../identity/index.js';
+import { SessionRegistry } from '../sessions/registry.js';
+import { readConfigFile } from '../host/config-file.js';
+import { writeLinkState } from '../host/link-state-file.js';
+import { describePosture, postureLine } from './posture.js';
+import { isAbsolutePath } from '../core/paths.js';
+import { systemClock, systemTicker } from '../core/time.js';
+import { configValueProblem, overriddenByEnvironment, reconfigureHost } from './reconfigure.js';
+import { hostConfigurationOf, workspaceCapabilitiesOf, workspacePostureProblem, workspacesFor, } from './workspaces.js';
+/**
+ * How long the fatal-credential path holds the event loop open before exiting explicitly.
+ *
+ * Long enough for the stdout trace and the stderr remedy to flush through their pipes, short enough
+ * that a supervisor sees the exit promptly. It is not a grace period for work in flight; the host
+ * is already stopped by the time this runs.
+ */
+export const FATAL_EXIT_FLUSH_MS = 50;
+function readConfig(env) {
+    const controllerUrl = env['PERISCOPE_CONTROLLER_URL'];
+    if (controllerUrl === undefined || controllerUrl === '') {
+        return 'PERISCOPE_CONTROLLER_URL is not set';
+    }
+    // A host with nowhere to ask must not start, and neither alternative is survivable. Defaulting
+    // to allow makes this a code-execution service for whoever reaches the socket. Defaulting to deny
+    // makes a host that comes up healthy, accepts sessions, and blocks every tool call, which reads
+    // to an operator as the agent being broken rather than as this host being unconfigured. So it is
+    // named at start-up, once, in the one place that reads the environment.
+    const decisionUrl = env['PERISCOPE_DECISION_URL'];
+    if (decisionUrl === undefined || decisionUrl === '') {
+        return ('PERISCOPE_DECISION_URL is not set — this host has nowhere to send a permission decision, and a ' +
+            'host that cannot ask is either an open door or a session where nothing runs. Set it to the ' +
+            'endpoint your controller answers on.');
+    }
+    // The same screen the wire runs on `host_configure`: a controller URL that is not ws(s), a
+    // decision URL that is not http(s), refused at boot by name instead of dialled forever.
+    for (const [key, value] of [
+        ['PERISCOPE_CONTROLLER_URL', controllerUrl],
+        ['PERISCOPE_DECISION_URL', decisionUrl],
+    ]) {
+        const problem = configValueProblem(key, value);
+        if (problem !== null)
+            return problem;
+    }
+    const configuredHostId = env['PERISCOPE_HOST_ID'];
+    return {
+        controllerUrl,
+        // An empty value counts as unset, as every other key reads it: a shell that exports the name
+        // with nothing behind it has not chosen a host id.
+        hostId: configuredHostId === undefined || configuredHostId === ''
+            ? readMachineFacts().hostname
+            : configuredHostId,
+        decisionUrl,
+        workspaceRoot: env['PERISCOPE_WORKSPACE_ROOT'] ?? null,
+        repositoryRoot: env['PERISCOPE_REPOSITORY_ROOT'] ?? null,
+        branchScheme: env['PERISCOPE_BRANCH_SCHEME'] ?? null,
+        workspaceKey: env['PERISCOPE_WORKSPACE_KEY'] ?? null,
+        agentHome: env['PERISCOPE_AGENT_HOME'] ?? null,
+    };
+}
+/**
+ * Which credential this host presents, or null when it presents none.
+ *
+ * The paired credential is preferred over the OIDC cache, and the preference is the point of
+ * pairing: an OIDC refresh token can expire after a period of inactivity, the paired credential has
+ * no clock. A machine that has run `periscope pair` dials on the paired credential even when a
+ * token cache also exists. A missing paired file falls through to the OIDC postures; a corrupt one
+ * is fatal rather than a fallback, because silently degrading to a maybe-dead refresh token would
+ * put the host back in exactly the ambiguous posture pairing exists to end.
+ *
+ * The OIDC three-way decision itself lives in `identity/config.ts` and is tested there; this is the
+ * wiring. A misconfiguration returns a string, which `runServe` treats as fatal: a host that was
+ * told to use identity and cannot must not come up looking healthy while authenticating as nobody.
+ *
+ * The `absent` posture returns null rather than a refusing credential, which is the whole
+ * difference between "no identity" and "no tool calls". `UnconfiguredCredential` refuses by name on
+ * every call, and `escalatingDecider` treats a refusing credential as an outage and does not send
+ * the request, so handing one to it would turn every escalation in every session into
+ * `permission-decision-unavailable`. That is the exact outcome `readConfig` above refuses to ship
+ * for the missing-URL case, in the same file, for the same stated reason: a host that comes up
+ * healthy, accepts sessions, and blocks every tool call reads to an operator as the agent being
+ * broken. Null means the option is omitted, which `EscalationOptions.credential` documents as the
+ * supported no-identity mode; the placeholder stays the exported shape for an embedder that wants a
+ * credential that says no out loud.
+ */
+export function readCredential(env, log) {
+    const pairedPath = pairedCredentialPath(env);
+    if (pairedPath !== null) {
+        const paired = new FilePairedCredential(pairedPath).read();
+        if (paired.ok) {
+            // The one posture line, matching the absent-case line in `runServe`: which credential this
+            // host is on is otherwise invisible until the first refusal.
+            log('credential', `paired as ${paired.value.hostId} - the paired credential is presented on every dial`, null);
+            return { credential: new PairedHostCredential(paired.value), pairedHostId: paired.value.hostId };
+        }
+        if (paired.refusal.reason !== 'token-unavailable') {
+            // Exists and is unreadable: fatal, loud, with the fix in the message (see the docblock).
+            return paired.refusal.detail;
+        }
+        // token-unavailable = this machine has never been paired: the normal fall-through.
+    }
+    const posture = identityPosture(env);
+    if (posture.kind === 'invalid')
+        return posture.detail;
+    if (posture.kind === 'absent')
+        return { credential: null, pairedHostId: null };
+    const cachePath = tokenCachePath(env);
+    if (cachePath === null) {
+        return 'identity is configured but there is nowhere to keep the token cache — set PERISCOPE_CONFIG_DIR';
+    }
+    const store = new FileTokenCache(cachePath);
+    const config = posture.config;
+    // The endpoints are resolved on first refresh, not at start-up. Discovery is a network call, and
+    // making it at construction would mean this host refuses to start when the provider is briefly
+    // unreachable, while holding a perfectly good cached token it could have presented. A host that
+    // cannot start is worse than one that refreshes late.
+    const refresh = async (cached) => {
+        const endpoints = await resolveEndpoints(config);
+        if (!endpoints.ok)
+            return endpoints;
+        return refresherFor(config, endpoints.value, store)(cached);
+    };
+    return {
+        credential: new TokenCredential({
+            store,
+            config,
+            // Loopback is the primary flow; the device-code fallback is a deliberate act, so a host running
+            // unattended is configured for the one it will actually use.
+            protocol: protocolFor(config),
+            nowMs: systemTicker,
+            refresh,
+            // The one line that tells an operator which of the three happened. Without it a cache hit, a
+            // silent refresh and "nobody ever signed in here" are the same silence, and the first difference
+            // is a 401 the user reads as a server fault. `[credential] refused` names the one thing they can
+            // act on, on the machine where they can act on it.
+            report: (outcome) => log('credential', outcome.kind === 'refused' ? `refused — ${outcome.reason}` : outcome.kind, outcome.kind === 'refused' ? outcome.detail : null),
+        }),
+        pairedHostId: null,
+    };
+}
+/**
+ * Running as root is refused by policy.
+ *
+ * An unattended agent running as root has the whole machine on every tool call, and a container
+ * built the obvious way runs as root. The gate decides which calls run; it does not shrink what a
+ * call can reach once it runs, and as uid 0 that is everything.
+ *
+ * Checked first, before configuration, so the answer arrives as one line at startup rather than as
+ * a session that can reach everything. A null `getuid` is win32, where the condition cannot arise.
+ */
+function rootRefusal(getuid) {
+    if (getuid === null)
+        return null;
+    if (getuid() !== 0)
+        return null;
+    return ('refusing to start as root: an unattended agent as uid 0 has the whole machine on every tool call. ' +
+        'Run as a non-root user (add a USER line to your container).');
+}
+/** Start the daemon. Returns the running host, or the refusal already written to stderr. */
+export function runServe(views, deps) {
+    const refuse = (detail) => {
+        deps.stderr(`periscope: ${detail}`);
+        deps.setExitCode(1);
+        return { ok: false, detail };
+    };
+    const log = (channel, message, detail) => {
+        const line = detail === null ? message : `${message} — ${detail}`;
+        deps.log(`${systemClock()} [${channel}] ${line}`);
+    };
+    const asRoot = rootRefusal(deps.getuid === undefined ? processUid() : deps.getuid);
+    if (asRoot !== null)
+        return refuse(asRoot);
+    // The config file fills absences, and only absences; the merge is `main.ts`'s, shared by every
+    // configuration-consuming verb, and a file that cannot be used is fatal rather than empty.
+    const env = views.merged;
+    if (typeof env === 'string')
+        return refuse(env);
+    const config = readConfig(env);
+    if (typeof config === 'string')
+        return refuse(config);
+    // The workspace posture is screened at startup, by name. A default workspace key that fails
+    // the union screen, or a branch scheme with a typo'd placeholder, would refuse every session,
+    // and a machine that will refuse every session must say so when it boots, where the person who
+    // can fix it is looking, not when someone finally opens a session.
+    const workspaceMisconfiguration = workspacePostureProblem({
+        workspaceRoot: config.workspaceRoot,
+        repositoryRoot: config.repositoryRoot,
+        branchScheme: config.branchScheme,
+        workspaceKey: config.workspaceKey,
+    });
+    if (workspaceMisconfiguration !== null)
+        return refuse(workspaceMisconfiguration);
+    // The transcripts root is read on demand and jailed, but a relative one means "relative to a
+    // cwd nobody chose"; refused at start-up like every other posture problem.
+    if (config.agentHome !== null && config.agentHome !== '' && !isAbsolutePath(config.agentHome)) {
+        return refuse(`PERISCOPE_AGENT_HOME must be an absolute path — got '${config.agentHome}'`);
+    }
+    const raw = views.raw;
+    // The posture line leads the output and the credential lines follow it: the one-line summary
+    // first, then the detail. The credential is read before the summary can be composed, so its
+    // lines are held until the summary has printed.
+    const held = [];
+    const hold = (...line) => {
+        held.push(line);
+    };
+    const posture = readCredential(raw, hold);
+    if (typeof posture === 'string')
+        return refuse(posture);
+    const credential = posture.credential;
+    if (credential === null) {
+        // A legitimate posture, and a silent one until this line existed: a host with no identity
+        // configured dials with no header, and "misconfigured to nobody" and "deliberately anonymous"
+        // looked identical from the outside. Said once, at start-up, where the other two postures
+        // already speak.
+        hold('credential', 'absent - no identity is configured, so this host will dial without authentication', null);
+    }
+    // A paired credential names its host, and the name wins. The controller refuses a link_hello
+    // whose hostId differs from the credential's, so announcing anything else guarantees a closed
+    // socket. Said out loud when the environment disagrees, because a silently ignored variable is a
+    // misconfiguration nobody finds.
+    const hostId = posture.pairedHostId ?? config.hostId;
+    if (posture.pairedHostId !== null &&
+        config.hostId !== posture.pairedHostId &&
+        raw['PERISCOPE_HOST_ID'] !== undefined) {
+        hold('credential', `PERISCOPE_HOST_ID ('${config.hostId}') is overridden by the paired credential's host id ('${posture.pairedHostId}')`, null);
+    }
+    // The one line status prints whole, from the same description, so the two cannot disagree.
+    const reading = readConfigFile(raw);
+    const cachePath = tokenCachePath(raw);
+    const cached = cachePath === null ? null : new FileTokenCache(cachePath).read();
+    log('host', `periscope ${packageVersion()} · ` +
+        postureLine(describePosture({
+            raw,
+            merged: env,
+            fileValues: reading.problem === null ? reading.values : {},
+            credential: posture,
+            tokenExpiresAtMs: cached !== null && cached.ok ? cached.value.tokens.expiresAt : null,
+            nowMs: Date.now(),
+            link: null,
+            pidAlive: () => false,
+            hostname: readMachineFacts().hostname,
+        })), null);
+    for (const line of held)
+        log(...line);
+    const workspaces = workspacesFor(config);
+    const agentHome = config.agentHome === null || config.agentHome === '' ? defaultAgentHome(raw) : config.agentHome;
+    // The transcripts root derives from the agent home; it is reported in the hello and never set on
+    // its own.
+    const transcriptsRoot = agentHome === null ? null : transcriptsRootUnder(agentHome);
+    const homeDir = raw['USERPROFILE'] ?? raw['HOME'] ?? '';
+    // Declared before the host so the event callback can reach it: the callback runs only after
+    // `start()` below, so the binding is always assigned by the time anything can fire.
+    let host = null;
+    // Whether the fatal path has latched the exit code. A later signal must not reset it.
+    let fatal = false;
+    /**
+     * The one event that ends this process unsuccessfully without anyone asking it to.
+     *
+     * Everything else this host reports is an observation. `credential_rejected` is a conclusion about
+     * the host itself: the identity provider has refused its material and will keep refusing until a
+     * person signs in, so there is nothing left for the process to do and staying up implies
+     * otherwise. Without this, the link fails, no ref'd handle remains, node drains, and the process
+     * exits zero, so a supervisor records a clean run and a dashboard shows a finished host that
+     * never once connected.
+     *
+     * The exit code and the stderr line are both required, and they answer different readers. The
+     * code is what a supervisor branches on; the line is what the person at the machine acts on. A
+     * non-zero exit whose reason appears only in the stdout trace still leaves somebody reading logs.
+     */
+    let linkStateProblemSaid = false;
+    const onEvent = (event) => {
+        if (event.kind === 'link') {
+            // The record status reads. A disk that will not take it is said once and never stops the link.
+            const problem = writeLinkState(raw, {
+                state: event.transition.to,
+                cause: event.transition.cause,
+                at: event.transition.at,
+                detail: event.transition.detail,
+                negotiatedVersion: host?.link.negotiatedVersion ?? null,
+                pid: process.pid,
+            });
+            if (problem !== null && !linkStateProblemSaid) {
+                linkStateProblemSaid = true;
+                log('config', `the link state file is not being written; periscope status will read nothing — ${problem}`, null);
+            }
+        }
+        report(event, log);
+        if (event.kind === 'link' && event.transition.cause === 'credential_rejected') {
+            // The process exits now, live sessions included, and the count says what that cost. The
+            // alternative (serve the survivors and exit when the last one ends) is declined: an idle
+            // session never ends on its own, so that shape is a process that can stay up forever behind
+            // a link that will never carry another frame, which is the quiet-death posture this file
+            // exists to prevent. The transcript mirror keeps what the sessions produced; the one number
+            // on this line tells the operator whether work was cut mid-flight.
+            const liveSessions = host?.registry.list().length ?? 0;
+            // The remedy names the credential the host was actually on: a paired credential is revived by
+            // re-pairing, not by signing in. Telling a paired operator to `login` sends them to a flow
+            // whose token this host would not even present.
+            const remedy = posture.pairedHostId !== null
+                ? 'run: periscope pair <code> with a freshly minted code, then start this host again'
+                : 'run: periscope login, then start this host again';
+            deps.stderr('periscope: the controller or its identity provider refused this credential ' +
+                `(${liveSessions} live session(s) stopped) - ${remedy}`);
+            fatal = true;
+            deps.setExitCode(1);
+            host?.stop("this host's credential was refused");
+            // Exit deliberately: draining is what lets a signal launder this failure. Latching the
+            // code and letting the loop empty leaves a window in which node has released the loop but the
+            // process still exists with its default signal dispositions restored; a SIGTERM landing there
+            // terminates by signal, so the exit code arrives as null and a supervisor reads "killed"
+            // rather than "failed", the exact laundering this terminal class exists to prevent. The
+            // ref'd timer holds the loop open, which keeps the handlers below installed while the pipes
+            // flush, and the explicit exit is then the only way this path can end. Node 22 on Linux
+            // loses this race where node 24 wins it.
+            setTimeout(() => deps.exit(1), FATAL_EXIT_FLUSH_MS);
+        }
+    };
+    host = new PeriscopeHost({
+        controllerUrl: config.controllerUrl,
+        hostId,
+        // Omitted, not nulled, when there is no identity. Both this option and the decision
+        // transport's are optional by type, and omitting is the documented no-identity mode on each.
+        // Spelling it as one spread keeps the two transports impossible to configure differently by
+        // accident (one authenticated, one not).
+        ...(credential === null ? {} : { credential }),
+        // The same credential the link presents, on the decision POST. The surface that decides
+        // whether a tool runs must not ship unauthenticated while the surface that merely reports is
+        // authenticated.
+        //
+        // Per host, not per session, and the distinction is a design constraint rather than a detail:
+        // one host serves many sessions, and this is read once from the environment, so nothing here can
+        // authenticate as the particular session a decision is about. That is what
+        // `DecisionRequest.sessionKey` is for: the controller attributes; the credential authenticates.
+        //
+        // And it is omitted when there is none, not passed as a credential that refuses. Passing one
+        // that refuses does not make the request unauthenticated; it makes there be no request, on
+        // every tool call, in every session. See `readCredential` above.
+        decide: escalatingDecider({
+            url: config.decisionUrl,
+            transport: deps.transport ?? fetch,
+            ...(credential === null ? {} : { credential }),
+        }),
+        // Derived, never spelled out here: `credentialPaths` is the one source both this and the token
+        // cache's own location come from, so they cannot disagree about what is protected.
+        protectedPaths: credentialPaths(raw, { agentHome }),
+        // The discovery door: read-only, jailed. The root is derived here because reading the
+        // environment is the composition root's job; a machine with no resolvable home gets a host
+        // whose door answers with a named failure rather than a guessed root. The bulk resolver
+        // serves `claude-transcript:` locators through the same jail, reads only; the gate's
+        // protection of `~/.claude` against the agent is untouched by either.
+        ...(transcriptsRoot === null ? {} : { transcriptsRoot, bulk: claudeTranscriptResolver(transcriptsRoot) }),
+        ...(workspaces === null ? {} : { workspaces }),
+        // The workspace mode rides the hello as capability markers, derived from the same config the
+        // selector above consumed: the read half of what `periscope config` writes, and what lets a
+        // controller verify a host is set up rather than trusting its operator's memory.
+        linkCapabilities: workspaceCapabilitiesOf(config),
+        // The values behind the markers, from the same reading: which roots, which scheme, which
+        // transcripts root, which controller this process dialled.
+        configuration: hostConfigurationOf(config, {
+            transcriptsRoot,
+            controllerUrl: config.controllerUrl,
+            decisionUrl: config.decisionUrl,
+            agentHome,
+        }),
+        overriddenByEnvironment: overriddenByEnvironment(raw),
+        // The configure seam: validates, writes the config file, rebuilds the provider. It reads
+        // the raw environment because the file fills absences in it, and only this file may read that.
+        // The addresses this process dialled ride in so a written URL is reported as pending rather than
+        // applied: the live link is never re-pointed, the next start reads the file.
+        reconfigure: (entries, hostBusy) => reconfigureHost(raw, entries, hostBusy, {
+            controllerUrl: config.controllerUrl,
+            decisionUrl: config.decisionUrl,
+        }),
+        // The default an unkeyed session_new resolves to, screened above at startup, so a bad
+        // value died before this line. Omitted (not nulled) when unset: absence is the documented mode.
+        ...(config.workspaceKey === null || config.workspaceKey === ''
+            ? {}
+            : { defaultWorkspaceKey: config.workspaceKey }),
+        // The registry is the host's own unless a test supplies the process starter; then it is built
+        // here over the same base environment and home the host would have used, and the pair goes to
+        // the registry alone: the host refuses the two beside a registry, where nothing would read them.
+        ...(deps.startProcess === undefined
+            ? { baseEnv: raw, homeDir }
+            : { registry: new SessionRegistry({ baseEnv: raw, homeDir, startProcess: deps.startProcess }) }),
+        ...(deps.link === undefined ? {} : { link: deps.link }),
+        report: onEvent,
+    });
+    // A signal must leave the process in a state a supervisor can distinguish from a crash, so the
+    // sessions and the link are closed deliberately and the exit code says which path was taken.
+    const shutdown = (signal) => {
+        host?.stop(`received ${signal}`);
+        // A signal does not erase a failure already recorded. If the credential was refused first,
+        // that exit code stands: a supervisor stopping a host it has just been told is unusable must not
+        // read its own stop as evidence the run was fine.
+        if (!fatal)
+            deps.setExitCode(0);
+    };
+    deps.onSignal('SIGTERM', () => shutdown('SIGTERM'));
+    deps.onSignal('SIGINT', () => shutdown('SIGINT'));
+    host.start();
+    return { ok: true, host };
+}
+/** The process's effective-uid reader, or null where the platform has none. */
+function processUid() {
+    return process.getuid?.bind(process) ?? null;
+}
+/** Every named thing the host reports, as one line each. The only output this process produces. */
+export function report(event, log) {
+    switch (event.kind) {
+        case 'link':
+            return log('link', `${event.transition.from} -> ${event.transition.to} (${event.transition.cause})`, event.transition.detail);
+        case 'refusal':
+            return log('refused', `${event.sessionKey ?? 'link'}: ${event.refusal.reason}`, event.refusal.detail);
+        case 'gap':
+            return log('gap', `${event.sessionKey} expected ${event.expected}, received ${event.received}`, null);
+        case 'session-opened':
+            return log('session', `${event.sessionKey} opened in ${event.cwd}`, null);
+        case 'session-closed':
+            return log('session', `${event.sessionKey} closed`, null);
+        // The held-prompt queue's own trace. Without these the queue would work and nothing would say
+        // so, and the gap between this pair is the measurement that a provisioning window was survived.
+        case 'prompt-held':
+            return log('held', `${event.sessionKey} a turn waits for the session to open`, `${event.held} held`);
+        case 'prompt-delivered':
+            return log('held', `${event.sessionKey} held turns delivered`, `${event.delivered} delivered`);
+        case 'prompt-withdrawn':
+            return log('held', `${event.sessionKey} the controller cancelled before the session opened`, `${event.withdrawn} withdrawn`);
+        case 'transition':
+            return log('state', `${event.sessionKey} ${event.transition.from} -> ${event.transition.to} ` +
+                `(${event.transition.cause.kind}/${event.transition.cause.event})`, event.transition.cause.detail);
+        case 'degrade':
+            // The named conditions that change what is true of a session without ending it: an
+            // untrusted workspace, an id collision. The detail is the operator's instruction and it
+            // travels whole: the collision's detail is the only place "resume with fork" is ever said.
+            return log('degrade', `${event.sessionKey} ${event.degrade.kind}`, event.degrade.detail);
+        default:
+            return;
+    }
+}
+//# sourceMappingURL=serve.js.map

package/dist/bin/status.d.ts

@@ -0,0 +1,11 @@
+import type { ServeViews } from './serve.js';
+export interface StatusOutcome {
+    readonly ok: boolean;
+    readonly lines: readonly string[];
+}
+export interface StatusDeps {
+    readonly nowMs: () => number;
+    readonly pidAlive: (pid: number) => boolean;
+}
+export declare function runStatus(views: ServeViews, deps?: StatusDeps): StatusOutcome;
+//# sourceMappingURL=status.d.ts.map

package/dist/bin/status.js

@@ -0,0 +1,49 @@
+/**
+ * `periscope status`: what this host is, read from what `serve` reads and from the link record
+ * `serve` keeps, never from a socket. A host that cannot dial is exactly when the question is asked.
+ */
+import { readConfigFile } from '../host/config-file.js';
+import { readLinkState } from '../host/link-state-file.js';
+import { tokenCachePath } from '../host/paths.js';
+import { FileTokenCache } from '../host/token-cache.js';
+import { readMachineFacts } from '../host/machine.js';
+import { describePosture, renderPosture } from './posture.js';
+import { packageVersion } from '../host/package-facts.js';
+import { readCredential } from './serve.js';
+function processPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const REAL = { nowMs: () => Date.now(), pidAlive: processPidAlive };
+export function runStatus(views, deps = REAL) {
+    if (typeof views.merged === 'string')
+        return { ok: false, lines: [views.merged] };
+    const raw = views.raw;
+    const file = readConfigFile(raw);
+    const credential = readCredential(raw, () => undefined);
+    let tokenExpiresAtMs = null;
+    const cache = tokenCachePath(raw);
+    if (cache !== null) {
+        const cached = new FileTokenCache(cache).read();
+        if (cached.ok)
+            tokenExpiresAtMs = cached.value.tokens.expiresAt;
+    }
+    const posture = describePosture({
+        raw,
+        merged: views.merged,
+        fileValues: file.problem === null ? file.values : {},
+        credential,
+        tokenExpiresAtMs,
+        nowMs: deps.nowMs(),
+        link: readLinkState(raw),
+        pidAlive: deps.pidAlive,
+        hostname: readMachineFacts().hostname,
+    });
+    return { ok: true, lines: [`periscope ${packageVersion()}`, ...renderPosture(posture)] };
+}
+//# sourceMappingURL=status.js.map

package/dist/bin/workspaces.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Which workspace provider a real process gets.
+ *
+ * Split out of the composition root (`main.ts` and `serve.ts`) rather than exported from it, for
+ * the reason that file's own header gives: everything below the composition root takes its
+ * configuration as arguments, which is what makes the rest of the package testable without a
+ * process. The selector is pure and lives where it can be called on its own.
+ */
+import type { HostConfiguration } from '../control/frames.js';
+import type { WorkspaceProvider } from '../workspace/provider.js';
+/** The environment answers the selector reads. A subset of the binary's `Config`, by structure. */
+export interface WorkspaceConfig {
+    /** When set, every session gets a directory beneath it instead of the one the controller named. */
+    readonly workspaceRoot: string | null;
+    /** When set alongside the root, sessions get a linked git worktree on their own branch. */
+    readonly repositoryRoot: string | null;
+    /**
+     * The branch template a worktree's branch is rendered from: `{key}` and `{repo}` are the
+     * two placeholders, e.g. `periscope/{repo}/{key}`. Null means the provider's own fallback
+     * (`periscope/{sessionId}`).
+     */
+    readonly branchScheme: string | null;
+}
+/** Render a branch scheme. Pure; exported so the rule is testable without a provider. */
+export declare function renderBranch(scheme: string, key: string, repo: string): string;
+/**
+ * The first way this rendered branch name is illegal, or null.
+ *
+ * A legal key can render an illegal refname: a `{repo}` carrying a dot-prefixed segment, a
+ * scheme with a trailing slash, a literal ending `.lock`. Validating the key and then building an
+ * unvalidated branch from it would let a branch die inside git on every open, so the result is
+ * screened: per slash-separated component, against the same union rule the key already passed
+ * (`refnameOrPathIllegality`, the single source of that class).
+ */
+export declare function branchNameProblem(branch: string): string | null;
+/**
+ * What is wrong with this workspace posture, at startup, or null when it is usable.
+ *
+ * Screened when the process boots, not at the first session. A machine that will refuse every
+ * session (an unusable default key, a scheme with a typo'd placeholder) must say so when it starts,
+ * where the one person who can fix it is looking, not days later when someone finally opens a
+ * session. Pure, and exported precisely so it is testable without starting a host.
+ *
+ * Three families of refusal, each by name:
+ *   - a setting that depends on another that is absent (a key with no provider, a scheme with no
+ *     repository); silently ignoring either is a misconfiguration nobody finds;
+ *   - a default workspace key that fails the same union screen a wire-supplied key must pass;
+ *   - a branch scheme with an unknown placeholder or an unmatched brace (never rendered literally;
+ *     `{repoo}` or a trailing `{repo` in a branch name is a silent wrong answer), or whose literal
+ *     text already renders illegally.
+ */
+export declare function workspacePostureProblem(posture: {
+    readonly workspaceRoot: string | null;
+    readonly repositoryRoot: string | null;
+    readonly branchScheme: string | null;
+    readonly workspaceKey: string | null;
+}): string | null;
+/**
+ * The branch scheme a git-worktree host renders when none is configured: the repository's name,
+ * then the key. With keys named after the platform's own identities (`session-150`,
+ * `run-34`) this puts every session on `repo/session-150`, the name an operator reads in
+ * the session's own URL. Explicitly configured schemes override it; the `workspace:branch-scheme`
+ * marker means "explicitly configured", never "this default".
+ */
+export declare const DEFAULT_BRANCH_SCHEME = "{repo}/{key}";
+/**
+ * The `branchFor` a scheme produces, extracted so the render-and-screen rule is testable without
+ * a provider, a repository, or a real git (the same reason this whole file exists).
+ *
+ * A render the screen refuses throws, and the throw is the contract: the provider calls this
+ * inside its own try, so the message lands in a named `workspace-provision-failed` refusal rather
+ * than dying inside git. This is the runtime half of the screen, for the violations only a
+ * particular key or repo name produces (the startup screen already caught the scheme's literal
+ * text).
+ */
+export declare function branchRenderer(scheme: string, repositoryRoot: string): (sessionId: string) => string;
+export declare function workspacesFor(config: WorkspaceConfig): WorkspaceProvider | null;
+/**
+ * The mode, as capability markers for the hello: the read half of what `periscope config` writes.
+ * A host that can be configured but cannot report how it is configured gives a controller nothing
+ * to verify.
+ *
+ * A pure twin of `workspacesFor`, kept beside it so the two cannot drift: the marker is derived
+ * from the same predicates that choose the provider, never from a second reading of the
+ * environment. Exactly one `workspace:*` mode marker is always present; absence of all three in a
+ * hello therefore means "this build does not report", which is what lets a controller render
+ * "not reported" instead of a default.
+ *
+ * Markers, not values. Which repository root, which scheme text: those would be payload members
+ * and a protocol-version change, deliberately not smuggled into marker strings.
+ */
+export declare function workspaceCapabilitiesOf(config: WorkspaceConfig): readonly string[];
+/** The values the hello reports that the workspace config does not hold. */
+export interface HostConfigurationExtras {
+    readonly transcriptsRoot: string | null;
+    readonly controllerUrl: string | null;
+    readonly decisionUrl: string | null;
+    readonly agentHome: string | null;
+}
+/**
+ * The values behind the markers: what the hello reports as `configuration`.
+ *
+ * The other pure twin of `workspacesFor`. Read from the same `WorkspaceConfig` the selector and
+ * the markers consume, so a root the selector treats as unset (null or empty) is reported as
+ * null here, never as an empty string a controller would render as a path. A value present here
+ * and a `workspace:none` marker cannot both be true of one config, and the test pins that.
+ */
+export declare function hostConfigurationOf(config: WorkspaceConfig, extras: HostConfigurationExtras): HostConfiguration;
+//# sourceMappingURL=workspaces.d.ts.map