@naswerks/periscope 1.0.0

package/dist/state/reporter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What this host can say about the sessions it is holding.
+ *
+ * This is not a roster, and the distinction is not pedantry. A roster spans every session
+ * everywhere — and sessions run on different hosts, because an agent runs where its host runs. No
+ * single host can produce one; it can only produce its own row. A controller aggregates these into
+ * the thing people actually want.
+ *
+ * So this offers enumeration and nothing else: no filtering, no search, no notion of which sessions
+ * are interesting, no "who is stuck". Every one of those is a judgement, and a host that makes
+ * judgements is a host that has to be rebuilt for the next product. If this file grows a predicate,
+ * the line has been crossed.
+ *
+ * What it does owe: the open-entry age. A session that has been in one tool call for forty
+ * minutes is the single most useful thing this layer can report, and the age is what says so.
+ */
+import type { AgedEntry, SessionSnapshot } from './model.js';
+import type { SessionStateMachine } from './machine.js';
+export declare class SessionStateReporter {
+    #private;
+    /** Start reporting a session. Idempotent. */
+    add(machine: SessionStateMachine): void;
+    /**
+     * Stop reporting a session.
+     *
+     * A caller that removes an ended session loses its open-entry evidence from this view. That is
+     * the caller's decision to make and it is not made here: nothing self-evicts, because a session
+     * that ended holding work is exactly the one somebody will want to look at.
+     */
+    remove(machine: SessionStateMachine): void;
+    get count(): number;
+    /** Every session this host holds. Raw material — see this file's header. */
+    list(): SessionSnapshot[];
+    /**
+     * Every entry that has not exited, across this host's sessions, with its age and its session.
+     *
+     * Reported, never reconciled: an unpaired entry is surfaced with how long it has been open and
+     * whether it was marked abandoned, and nothing here closes one. Cleanup may mark; it may not
+     * erase, because erasing destroys the only evidence that the thing happened at all.
+     */
+    openEntries(): (AgedEntry & {
+        readonly sessionId: string | null;
+    })[];
+}
+//# sourceMappingURL=reporter.d.ts.map

package/dist/state/reporter.js

@@ -0,0 +1,35 @@
+export class SessionStateReporter {
+    #machines = new Set();
+    /** Start reporting a session. Idempotent. */
+    add(machine) {
+        this.#machines.add(machine);
+    }
+    /**
+     * Stop reporting a session.
+     *
+     * A caller that removes an ended session loses its open-entry evidence from this view. That is
+     * the caller's decision to make and it is not made here: nothing self-evicts, because a session
+     * that ended holding work is exactly the one somebody will want to look at.
+     */
+    remove(machine) {
+        this.#machines.delete(machine);
+    }
+    get count() {
+        return this.#machines.size;
+    }
+    /** Every session this host holds. Raw material — see this file's header. */
+    list() {
+        return [...this.#machines].map((machine) => machine.snapshot());
+    }
+    /**
+     * Every entry that has not exited, across this host's sessions, with its age and its session.
+     *
+     * Reported, never reconciled: an unpaired entry is surfaced with how long it has been open and
+     * whether it was marked abandoned, and nothing here closes one. Cleanup may mark; it may not
+     * erase, because erasing destroys the only evidence that the thing happened at all.
+     */
+    openEntries() {
+        return [...this.#machines].flatMap((machine) => machine.openEntries().map((entry) => ({ ...entry, sessionId: machine.sessionId })));
+    }
+}
+//# sourceMappingURL=reporter.js.map

package/dist/state/store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where recorded transitions are kept, and where anyone asking "what happened?" reads from.
+ *
+ * Separate from the machine on purpose. A machine that both emitted and answered questions about
+ * itself would let a test prove emission by asking the thing that emitted — the assertion and the
+ * subject would be the same object. This subscribes, so "no transition without a cause" is checked
+ * against what was actually retained rather than against what a call site claims it passed.
+ *
+ * Bounded, in memory, and not durable. It holds a window per session so a long-running host does
+ * not grow without limit; durability of the transition log belongs to the persistence layer, and
+ * this deliberately does not pretend to be it. `dropped` counts what fell out of the window rather
+ * than letting a full ring look like a quiet one.
+ */
+import type { SessionTransition } from './model.js';
+import type { RejectedTransition, SessionStateMachine, Unsubscribe } from './machine.js';
+export interface TransitionStoreOptions {
+    readonly windowPerSession?: number;
+}
+export declare class TransitionStore {
+    #private;
+    constructor(options?: TransitionStoreOptions);
+    /**
+     * Retain everything one machine records, and everything it refuses.
+     *
+     * Both halves matter: a store that kept only the successes would answer "were all transitions
+     * caused?" with a yes it earned by discarding the counter-examples.
+     */
+    attach(machine: SessionStateMachine): Unsubscribe;
+    /**
+     * One session's transitions, oldest first.
+     *
+     * Transitions recorded before the agent named itself are re-keyed when it does. They were
+     * genuinely recorded without an id — that window is real — but leaving them in a separate bucket
+     * would mean the trace of a session's own start could not be read by that session's id, which is
+     * the one thing a reader has.
+     */
+    forSession(sessionId: string): readonly SessionTransition[];
+    /** Transitions recorded while no session had reported itself yet, across every machine. */
+    unidentified(): readonly SessionTransition[];
+    /** Everything retained, across every session. The subject of the store-level assertions. */
+    all(): SessionTransition[];
+    sessionIds(): string[];
+    /** Every refused transition still held, with why. Never summarised into a count alone. */
+    rejected(): readonly RejectedTransition[];
+    /** How many transitions fell out of a window. A full ring must not read as a quiet one. */
+    get droppedCount(): number;
+    /**
+     * How many rejections fell out of their window.
+     *
+     * Counted separately from `droppedCount` because the two mean opposite things: transitions
+     * falling out is an ordinary busy session, rejections falling out means something is refusing
+     * faster than anyone is reading, and collapsing them into one number would hide that.
+     */
+    get droppedRejectionCount(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/state/store.js

@@ -0,0 +1,120 @@
+/** Per session. A session that outruns this loses its oldest transitions, and says how many. */
+const DEFAULT_WINDOW = 500;
+/** Keyed while a session has no id yet — see SessionTransition.sessionId. */
+const UNIDENTIFIED = '(unidentified)';
+export class TransitionStore {
+    #window;
+    #bySession = new Map();
+    #rejected = [];
+    #dropped = 0;
+    #droppedRejections = 0;
+    constructor(options = {}) {
+        this.#window = options.windowPerSession ?? DEFAULT_WINDOW;
+    }
+    /**
+     * Retain everything one machine records, and everything it refuses.
+     *
+     * Both halves matter: a store that kept only the successes would answer "were all transitions
+     * caused?" with a yes it earned by discarding the counter-examples.
+     */
+    attach(machine) {
+        const dropTransitions = machine.onTransition((transition) => this.#retain(transition));
+        const dropRejections = machine.onRejected((rejected) => {
+            // Bounded on the same terms as the transitions, and for the same reason: a rejection arrives
+            // from whatever drives the machine, and once that is a wire path the rate is a stranger's to
+            // set. An uncapped array beside a capped ring would make the counter-examples the thing that
+            // grows without limit — the one collection nobody thinks to watch.
+            this.#rejected.push(rejected);
+            while (this.#rejected.length > this.#window) {
+                this.#rejected.shift();
+                this.#droppedRejections += 1;
+            }
+        });
+        return () => {
+            dropTransitions();
+            dropRejections();
+        };
+    }
+    /**
+     * One session's transitions, oldest first.
+     *
+     * Transitions recorded before the agent named itself are re-keyed when it does. They were
+     * genuinely recorded without an id — that window is real — but leaving them in a separate bucket
+     * would mean the trace of a session's own start could not be read by that session's id, which is
+     * the one thing a reader has.
+     */
+    forSession(sessionId) {
+        return this.#bySession.get(sessionId) ?? [];
+    }
+    /** Transitions recorded while no session had reported itself yet, across every machine. */
+    unidentified() {
+        return this.#bySession.get(UNIDENTIFIED) ?? [];
+    }
+    /** Everything retained, across every session. The subject of the store-level assertions. */
+    all() {
+        return [...this.#bySession.values()].flat();
+    }
+    sessionIds() {
+        return [...this.#bySession.keys()].filter((key) => key !== UNIDENTIFIED);
+    }
+    /** Every refused transition still held, with why. Never summarised into a count alone. */
+    rejected() {
+        return this.#rejected;
+    }
+    /** How many transitions fell out of a window. A full ring must not read as a quiet one. */
+    get droppedCount() {
+        return this.#dropped;
+    }
+    /**
+     * How many rejections fell out of their window.
+     *
+     * Counted separately from `droppedCount` because the two mean opposite things: transitions
+     * falling out is an ordinary busy session, rejections falling out means something is refusing
+     * faster than anyone is reading, and collapsing them into one number would hide that.
+     */
+    get droppedRejectionCount() {
+        return this.#droppedRejections;
+    }
+    #retain(transition) {
+        const key = transition.sessionId ?? UNIDENTIFIED;
+        this.#adopt(transition);
+        const kept = this.#bySession.get(key) ?? [];
+        kept.push(transition);
+        while (kept.length > this.#window) {
+            kept.shift();
+            this.#dropped += 1;
+        }
+        this.#bySession.set(key, kept);
+    }
+    /** Move this machine's earlier, id-less transitions under the id it has just reported. */
+    #adopt(transition) {
+        const id = transition.sessionId;
+        if (id === null)
+            return;
+        const orphans = this.#bySession.get(UNIDENTIFIED);
+        if (orphans === undefined)
+            return;
+        // Only this machine's own: an id-less transition belongs to whichever machine produced the
+        // seq series it sits in, and a machine's seq is dense from 1. Anything at or above this
+        // transition's own seq cannot be its predecessor.
+        const mine = orphans.filter((orphan) => orphan.seq < transition.seq && sameOrigin(orphan, transition));
+        if (mine.length === 0)
+            return;
+        this.#bySession.set(UNIDENTIFIED, orphans.filter((orphan) => !mine.includes(orphan)));
+        const kept = this.#bySession.get(id) ?? [];
+        this.#bySession.set(id, [...mine, ...kept]);
+    }
+}
+/**
+ * Whether two transitions came from the same machine, without either carrying a machine id.
+ *
+ * `where` is per-machine and fixed for its lifetime, and `correlationId` is whatever the controller
+ * supplied for that one session — so together they distinguish two concurrent id-less starts unless
+ * a controller starts two sessions in the same directory with no correlation id, in which case
+ * their early transitions are genuinely indistinguishable and both are adopted. That is a truthful
+ * outcome rather than a wrong one: nothing is lost, and nothing is invented to prevent it.
+ */
+function sameOrigin(left, right) {
+    return left.correlationId === right.correlationId && left.where.cwd === right.where.cwd;
+}
+//# sourceMappingURL=store.js.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Usage, cost and rate-limit facts — consumed from what the agent reports, never recomputed.
+ *
+ * There is no price table in this package and there must not be one. The agent reports a cost per
+ * model, with the provider and the id it priced against, so a mixed-model turn is correct without
+ * this host knowing any rate. A table would be wrong twice over and silently: stale the moment a
+ * price moves, and blind to a turn that used more than one model.
+ */
+export type { ModelSpend, RateLimitStanding, SpendTotal, TurnSpend } from './usage.js';
+export { NO_SPEND, foldSpend, spendReconciles } from './usage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -0,0 +1,2 @@
+export { NO_SPEND, foldSpend, spendReconciles } from './usage.js';
+//# sourceMappingURL=index.js.map

package/dist/telemetry/usage.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What a turn cost — consumed from what the agent reports, never computed from a price table.
+ *
+ * The whole point is that nothing here multiplies tokens by a rate. A host that keeps a per-model
+ * price table and does the arithmetic itself has two failure modes, and both are silent: a price
+ * changes and every historical figure is quietly wrong, and a mixed-model turn is costed at one
+ * model's rate because the table is keyed by "the session's model". The agent already reports a
+ * per-model cost, with the provider and the canonical id it priced against. So this reads.
+ *
+ * How that is actually proven, because "it only reads" is easy to claim and easy to regress: the
+ * tests feed a cost no price table could ever produce and assert it comes out unchanged. A
+ * reimplementation that started computing would have to reproduce an arbitrary number to stay green.
+ *
+ * No SDK types here. This is the model the layer above works in; `host/telemetry.ts` lifts it off
+ * the agent's own result message, the same way `readInitFacts` lifts the version receipt.
+ */
+/** What one model cost within a turn. Every number is reported, none derived. */
+export interface ModelSpend {
+    /** The model string the agent was keyed by — provider-specific ids and aliases included. */
+    readonly model: string;
+    readonly costUsd: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadInputTokens: number;
+    readonly cacheCreationInputTokens: number;
+    /** The window this model was serving with. Absent is null, never zero. */
+    readonly contextWindow: number | null;
+    /** The id the agent priced against, when it differs from `model`. */
+    readonly canonicalModel: string | null;
+    /** Which API served it, when reported. */
+    readonly provider: string | null;
+}
+/** One turn's spend. */
+export interface TurnSpend {
+    /** The agent's own total. Not the sum of `byModel` — see `spendReconciles`. */
+    readonly totalCostUsd: number;
+    readonly byModel: readonly ModelSpend[];
+}
+/** Spend accumulated across turns. */
+export interface SpendTotal {
+    readonly totalCostUsd: number;
+    readonly turnCount: number;
+    /** Per model, summed across every turn folded in. */
+    readonly byModel: readonly ModelSpend[];
+}
+export declare const NO_SPEND: SpendTotal;
+/**
+ * Add one turn to a running total.
+ *
+ * Models are merged by their reported key, not by the canonical id. Two entries keyed differently
+ * that price against one canonical model are genuinely two things the agent distinguished — an alias
+ * and a provider-specific id can bill differently — and collapsing them here would throw away the
+ * distinction the report was making.
+ */
+export declare function foldSpend(prev: SpendTotal, turn: TurnSpend): SpendTotal;
+/**
+ * Whether a turn's per-model costs add up to the total the agent reported.
+ *
+ * It is an observation, not a validation, and must not become one. Both numbers come from the
+ * agent; a mismatch means the agent counted something the per-model breakdown does not itemise, and
+ * that is the agent's business rather than a defect this host should refuse over. The reason to
+ * expose it is that a caller charging money wants to know which of the two it is quoting, and
+ * whether they agree.
+ *
+ * @param toleranceUsd absolute, because these are floats and an exact comparison would fail on
+ *                     arithmetic that is otherwise perfectly correct.
+ */
+export declare function spendReconciles(turn: TurnSpend, toleranceUsd?: number): boolean;
+/** How a rate limit currently stands, as the agent reports it. */
+export interface RateLimitStanding {
+    readonly status: 'allowed' | 'allowed_warning' | 'rejected';
+    /** Epoch seconds, as reported. Null when the agent did not say. */
+    readonly resetsAt: number | null;
+    readonly limitType: string | null;
+    /** 0–1 where reported, else null. Never defaulted to 0 — that would read as "plenty left". */
+    readonly utilization: number | null;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/telemetry/usage.js

@@ -0,0 +1,69 @@
+/**
+ * What a turn cost — consumed from what the agent reports, never computed from a price table.
+ *
+ * The whole point is that nothing here multiplies tokens by a rate. A host that keeps a per-model
+ * price table and does the arithmetic itself has two failure modes, and both are silent: a price
+ * changes and every historical figure is quietly wrong, and a mixed-model turn is costed at one
+ * model's rate because the table is keyed by "the session's model". The agent already reports a
+ * per-model cost, with the provider and the canonical id it priced against. So this reads.
+ *
+ * How that is actually proven, because "it only reads" is easy to claim and easy to regress: the
+ * tests feed a cost no price table could ever produce and assert it comes out unchanged. A
+ * reimplementation that started computing would have to reproduce an arbitrary number to stay green.
+ *
+ * No SDK types here. This is the model the layer above works in; `host/telemetry.ts` lifts it off
+ * the agent's own result message, the same way `readInitFacts` lifts the version receipt.
+ */
+export const NO_SPEND = { totalCostUsd: 0, turnCount: 0, byModel: [] };
+/**
+ * Add one turn to a running total.
+ *
+ * Models are merged by their reported key, not by the canonical id. Two entries keyed differently
+ * that price against one canonical model are genuinely two things the agent distinguished — an alias
+ * and a provider-specific id can bill differently — and collapsing them here would throw away the
+ * distinction the report was making.
+ */
+export function foldSpend(prev, turn) {
+    const byModel = new Map();
+    for (const spend of prev.byModel)
+        byModel.set(spend.model, spend);
+    for (const spend of turn.byModel) {
+        const existing = byModel.get(spend.model);
+        byModel.set(spend.model, existing === undefined
+            ? spend
+            : {
+                ...existing,
+                costUsd: existing.costUsd + spend.costUsd,
+                inputTokens: existing.inputTokens + spend.inputTokens,
+                outputTokens: existing.outputTokens + spend.outputTokens,
+                cacheReadInputTokens: existing.cacheReadInputTokens + spend.cacheReadInputTokens,
+                cacheCreationInputTokens: existing.cacheCreationInputTokens + spend.cacheCreationInputTokens,
+                // Last report wins: these describe the model, not the usage, and the newest is truest.
+                contextWindow: spend.contextWindow ?? existing.contextWindow,
+                canonicalModel: spend.canonicalModel ?? existing.canonicalModel,
+                provider: spend.provider ?? existing.provider,
+            });
+    }
+    return {
+        totalCostUsd: prev.totalCostUsd + turn.totalCostUsd,
+        turnCount: prev.turnCount + 1,
+        byModel: [...byModel.values()],
+    };
+}
+/**
+ * Whether a turn's per-model costs add up to the total the agent reported.
+ *
+ * It is an observation, not a validation, and must not become one. Both numbers come from the
+ * agent; a mismatch means the agent counted something the per-model breakdown does not itemise, and
+ * that is the agent's business rather than a defect this host should refuse over. The reason to
+ * expose it is that a caller charging money wants to know which of the two it is quoting, and
+ * whether they agree.
+ *
+ * @param toleranceUsd absolute, because these are floats and an exact comparison would fail on
+ *                     arithmetic that is otherwise perfectly correct.
+ */
+export function spendReconciles(turn, toleranceUsd = 1e-9) {
+    const summed = turn.byModel.reduce((total, spend) => total + spend.costUsd, 0);
+    return Math.abs(summed - turn.totalCostUsd) <= toleranceUsd;
+}
+//# sourceMappingURL=usage.js.map

package/dist/workspace/git-worktree.d.ts

@@ -0,0 +1,150 @@
+/**
+ * A linked git worktree per session.
+ *
+ * The one rule here has destroyed committed work before: never `git worktree add -B` over a branch
+ * that already exists. `-B` is create-or-reset — it hard-resets the branch to the base ref — so
+ * re-provisioning a directory that was lost (a cleanup ran, a volume remounted) silently discards
+ * every commit made in it. The directory comes back looking correct and the work is gone. Nothing
+ * errors, nothing warns, and the loss is only visible to someone who knew what the branch used to
+ * point at.
+ *
+ * The rule: if the branch exists, attach to it and let it keep its own tip. Only a branch being
+ * created for the first time takes the `-B` form.
+ *
+ * That rule is a pure function here, and that is the point of the file's shape. `worktreeAddArgs`
+ * takes four values and returns an argv; the invariant is a unit test with no git, no disk and no
+ * repository. The alternative is a rule that only a destroyed branch could ever have proven.
+ *
+ * No key formula lives here. A branch naming convention is the controller's own convention, and
+ * one baked in here would be this package deciding what a session means. The caller supplies the
+ * branch name and the base ref.
+ */
+import type { Result } from '../core/result.js';
+import { MAX_WORKSPACE_ID_LENGTH } from '../core/workspace-id.js';
+import type { CommandEffects, ReleaseOptions, ReleaseReceipt, Workspace, WorkspaceEffects, WorkspaceInventory, WorkspaceProvider } from './provider.js';
+/**
+ * The exact `git worktree add` argv, and the one decision that matters.
+ *
+ * `branchExists` decides between two different commands, not between two spellings of one.
+ *   exists  gives `worktree add <path> <branch>`               attach: the branch keeps its own tip.
+ *   new     gives `worktree add -B <branch> <path> <baseRef>`  create, off the base ref.
+ * Passing `-B` in the first case hard-resets the branch and discards its commits. See this file's
+ * header — that is not a hypothetical.
+ *
+ * Pure and total: no filesystem, no git, no I/O. Exported so the rule is testable directly rather
+ * than only through a provider that would need a repository to exercise.
+ */
+export declare function worktreeAddArgs(path: string, branch: string, baseRef: string, branchExists: boolean): readonly string[];
+export interface GitWorktreeProviderOptions {
+    /** The repository the worktrees are linked to. Absolute. */
+    readonly repositoryRoot: string;
+    /** Where worktree directories are created. Absolute. */
+    readonly workspaceRoot: string;
+    /**
+     * The branch a session's worktree sits on, derived from its id.
+     *
+     * Supplied, not derived here. A branch naming convention is the caller's own; see the file
+     * header. Defaults to `periscope/{sessionId}` only so the provider is usable without one.
+     */
+    readonly branchFor?: (sessionId: string) => string;
+    /** What a new branch is created from. Defaults to `HEAD`. */
+    readonly baseRef?: string;
+    readonly effects: WorkspaceEffects;
+    readonly commands: CommandEffects;
+}
+export declare class GitWorktreeProvider implements WorkspaceProvider {
+    #private;
+    /** The checkout this provider clones from — see `WorkspaceProvider.repositoryRoot`. */
+    get repositoryRoot(): string;
+    constructor(options: GitWorktreeProviderOptions);
+    /** Where this session's worktree is, whether or not it exists yet. */
+    pathFor(sessionId: string): string;
+    provision(sessionId: string): Promise<Result<Workspace>>;
+    /**
+     * Release the worktree.
+     *
+     * The branch is never deleted unless the caller names it in the ask. Removing a directory is
+     * reversible — the commits are still on the branch. Deleting a branch is not, so branch deletion
+     * is opt-in per call (`deleteBranch`), refused for an unmerged branch unless forced, and the
+     * merged check runs before anything is removed: a refusal never leaves a half-cleaned key. A
+     * deletion that fails after the directory went is a partial, stated on the receipt.
+     *
+     * The branch is the one the worktree is on (from `worktree list`), which may differ from the
+     * scheme's render if an agent checked out elsewhere; only when the directory is already gone is
+     * the scheme's render the name.
+     */
+    release(sessionId: string, options?: ReleaseOptions): Promise<Result<ReleaseReceipt | undefined>>;
+    /** The key of the directory at `path` when it sits directly under the workspace root, else null. */
+    keyForPath(path: string): string | null;
+    /**
+     * Every worktree under the workspace root, from disk, with what git knows about its branch.
+     *
+     * Three commands for the whole list, plus one `rev-list --count` per branch entry: `worktree list --porcelain` for the worktrees, `for-each-ref`
+     * for every branch tip's date, and `branch --merged <default>` for the merged set. Only worktrees
+     * CONTAINED BY the workspace root are reported: the repository itself and any checkout the
+     * operator keeps elsewhere are not this provider's to list, so no cleanup composed from this
+     * answer can name them. `merged` is null when the repository names no default branch.
+     */
+    inventory(): Promise<Result<WorkspaceInventory>>;
+}
+/**
+ * A session id that cannot safely become a path segment or a branch-name component.
+ *
+ * Refused rather than sanitized. Rewriting an id to make it safe means the directory no longer
+ * corresponds to the id the caller used, so two different sessions can collapse onto one workspace —
+ * which is the exact isolation property the plain-directory tests check, broken quietly by a
+ * helpful-looking fix.
+ *
+ * The screen is the union of two rule sets. The id becomes both a directory segment (win32/POSIX)
+ * and a git branch-name component (`periscope/{id}` by default); an id containing a character that
+ * only git refuses would pass a separators-only screen and fail inside git as an unnamed
+ * `workspace-provision-failed`. So the guard screens every character either rule set refuses — the
+ * `git check-ref-format` component rules together with the win32 segment rules — and the refusal
+ * names the offending character and its rule. Deliberately not screened: win32 reserved device
+ * names (CON, NUL, …) — a name-list, not a character class; those still die loudly at provision
+ * under the named refusal below.
+ */
+declare function rejectUnusableId<T>(sessionId: string): Result<T> | null;
+/**
+ * The refname/path-segment class check: the first way this id would be refused by
+ * `git check-ref-format` (as the component of a branch name) or by win32 (as a path segment), as a
+ * human sentence — or null for an id both rule sets accept. Pure and total, exported so the class
+ * is testable without a provider.
+ */
+export declare function refnameOrPathIllegality(sessionId: string): string | null;
+export { rejectUnusableId };
+/**
+ * The same screen as `rejectUnusableId`, as a sentence a caller can attach to its own noun.
+ *
+ * The host validates `session_new.workspaceKey` before any workspace is claimed, and its refusal
+ * must name the field — "the session id …" would send a controller author to the wrong key. The
+ * union class itself stays single-sourced in `refnameOrPathIllegality`; the two structural checks
+ * are restated here because their sentences are the caller's to phrase. Keep the three checks in
+ * step with `rejectUnusableId` above — a key this accepts and that refuses (or the reverse) would
+ * mean the host's guard and the provider's disagree about the same id.
+ */
+export declare function unusableKeyProblem(key: string): string | null;
+/** The bound on a workspace id; declared in `core/` so the wire codec can enforce it too. */
+export { MAX_WORKSPACE_ID_LENGTH };
+/**
+ * A key safe to echo into a refusal detail: verbatim when short, truncated with its length named
+ * when not. Every screen above bounds accepted ids, but the refusal for an over-length id still
+ * has to describe the very string that broke the bound — this is the one place an unbounded input
+ * reaches a detail, so it is bounded here rather than at each caller's discretion.
+ */
+export declare function keyPreview(id: string): string;
+/** Newest tip first; entries with no tip date (detached, unknown) after every dated one; ties by key. */
+export declare function byNewestTip(a: {
+    readonly key: string;
+    readonly lastCommitAt: string | null;
+}, b: {
+    readonly key: string;
+    readonly lastCommitAt: string | null;
+}): number;
+/**
+ * The key of `path` when it is an absolute path to a directory DIRECTLY under `root` (normalised),
+ * else null: the root itself, a nested path, a relative path and anything elsewhere are all null,
+ * so a release addressed by path can only ever name what a provision could have made.
+ */
+export declare function keyDirectlyUnder(path: string, root: string): string | null;
+//# sourceMappingURL=git-worktree.d.ts.map