@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/session-shell/nav-guard.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Nav destinations, and the guard that proves every href the rail renders
+ * resolves to a route the product's router actually registered.
+ *
+ * A rail row's href is assembled from a base plus a relative path, and nothing
+ * downstream re-checks it: the sidebar renders a link, the click navigates, and
+ * the router answers 404. A unit test written against the nav builder alone
+ * cannot catch that — it asserts the href the builder produced, which is the
+ * same wrong string the user clicks.
+ *
+ * Two mechanisms, meant to be used together:
+ *
+ * 1. `NavDestination` makes the base a REQUIRED discriminant (`scope`). An
+ *    optional `absolute?: boolean`-style flag has the opposite property:
+ *    omitting it type-checks, and the destination silently resolves under the
+ *    workspace prefix instead of the app-level one. A required literal union
+ *    turns that omission into a compile error, and widening `TScope` demands a
+ *    base for the new scope rather than defaulting to a wrong one.
+ * 2. `assertNavHrefsRegistered` matches every resolved href against the route
+ *    table, so a destination the router never registered fails a test instead
+ *    of a user's click. It reads the product's real route table, so it cannot
+ *    agree with the builder's mistake the way a hand-maintained expected-href
+ *    list does.
+ */
+/** The bases a product routes rail rows under. `workspace` is the per-workspace
+ *  prefix (`/app/ws_123`); `app` is the account-level one (`/app`), where
+ *  singleton surfaces such as a shared terminal or billing live. */
+export type NavScope = 'workspace' | 'app';
+/** A base path per scope. Widening `TScope` widens this record, so a product
+ *  that adds a scope cannot compile until it supplies that scope's base. */
+export type NavScopeBases<TScope extends string = NavScope> = Readonly<Record<TScope, string>>;
+/** One rail destination as the product declares it, before a base is applied. */
+export interface NavDestination<TScope extends string = NavScope> {
+    id: string;
+    /** Path relative to the base named by `scope`. `''` is the base itself.
+     *  Must be empty or start with `/` — a bare `'vault'` would concatenate into
+     *  `/app/ws_123vault`, so it is rejected rather than silently repaired. */
+    path: string;
+    /** Which base `path` resolves against. Required on purpose. */
+    scope: TScope;
+}
+/** A destination with its base applied. */
+export interface ResolvedNavDestination<TScope extends string = NavScope> {
+    id: string;
+    href: string;
+    scope: TScope;
+}
+/** Apply a destination's scope base to its path.
+ *
+ *  Throws when the scope has no base configured — a product that assembles
+ *  `bases` dynamically can defeat the type-level guarantee, and a missing base
+ *  would otherwise produce `undefined/vault`. */
+export declare function resolveNavHref<TScope extends string>(destination: NavDestination<TScope>, bases: NavScopeBases<TScope>): string;
+/** Apply the bases to every destination, preserving declaration order. */
+export declare function resolveNavDestinations<TScope extends string>(destinations: readonly NavDestination<TScope>[], bases: NavScopeBases<TScope>): ResolvedNavDestination<TScope>[];
+export interface ResolveScopedActiveNavIdOptions<TScope extends string = NavScope> {
+    pathname: string;
+    destinations: readonly NavDestination<TScope>[];
+    bases: NavScopeBases<TScope>;
+    /** Extra ABSOLUTE prefixes that light an existing row, e.g.
+     *  `{ '/app/ws_1/agents': 'integrations' }`. Same longest-prefix contest. */
+    aliases?: Readonly<Record<string, string>>;
+    /** ABSOLUTE prefixes that deliberately highlight nothing, beating any shorter
+     *  match. */
+    claimsNothing?: readonly string[];
+}
+/**
+ * The rail row to highlight, across scopes.
+ *
+ * `resolveActiveNavId` resolves rows against ONE base, so an app-level row can
+ * only be highlighted by a second, hand-rolled scan — the same split that lets
+ * an app-level destination render under the workspace base. This resolves the
+ * hrefs first and runs a single longest-prefix contest over absolute paths, so
+ * declaration order cannot change the answer and no scope needs its own pass.
+ *
+ * Prefixes in `aliases` / `claimsNothing` are absolute here, unlike
+ * `resolveActiveNavId`'s base-relative ones, because the contest itself is
+ * absolute.
+ */
+export declare function resolveScopedActiveNavId<TScope extends string>({ pathname, destinations, bases, aliases, claimsNothing, }: ResolveScopedActiveNavIdOptions<TScope>): string | undefined;
+/**
+ * One entry of a registered route table. Structurally compatible with
+ * react-router's `RouteConfigEntry`, so a product passes its real `routes.ts`
+ * default export straight in — the point of the guard is that it reads the
+ * router's own truth rather than a second list that can agree with the bug.
+ */
+export interface RegisteredRoute {
+    /** Absent on a pathless layout route: its children inherit the parent path. */
+    path?: string;
+    index?: boolean;
+    children?: readonly RegisteredRoute[];
+}
+/** A route table entry is either a bare pattern string or a router config node. */
+export type NavRouteTable = readonly (string | RegisteredRoute)[];
+/**
+ * Every path pattern the table registers, rooted and de-duplicated.
+ *
+ * Parent nodes contribute their own cumulative path as well as their children's:
+ * a router matches a parent route with an index child at the parent path, and a
+ * parent without one still matches with an empty outlet, so treating parents as
+ * unregistered would flag working hrefs.
+ */
+export declare function flattenRouteTable(table: NavRouteTable): string[];
+/**
+ * A nav row as the guard needs to see it. Structurally satisfied by
+ * `SessionRailNavItem` / `SessionRailSubItem` and by sandbox-ui's
+ * `SidebarLayoutNavItem`, so the guard runs over the builder's real output
+ * rather than a re-declaration of it.
+ */
+export interface NavHrefItem {
+    id: string;
+    href: string;
+    subItems?: readonly NavHrefItem[];
+}
+export type NavHrefProblemReason = 
+/** No registered pattern matches the resolved href. */
+'unregistered'
+/** Empty, fragment-only, or not rooted at `/` — the row navigates nowhere
+ *  predictable regardless of the route table. */
+ | 'not-a-path'
+/** Leaves the router (scheme or protocol-relative) while `allowExternal` is
+ *  off. */
+ | 'external';
+export interface NavHrefProblem {
+    id: string;
+    href: string;
+    reason: NavHrefProblemReason;
+    /** Registered patterns ending in the same segment. A destination resolved
+     *  under the wrong base lands here as its correctly-based twin, which is what
+     *  names the missing scope in the failure message. */
+    nearest: string[];
+    message: string;
+}
+export interface NavHrefReport {
+    /** Hrefs examined, including nested sub-items. */
+    checked: number;
+    problems: NavHrefProblem[];
+    /** Off-router destinations accepted because `allowExternal` is on. */
+    external: string[];
+    /** The flattened route table the check ran against. */
+    patterns: string[];
+}
+export interface NavHrefCheckOptions {
+    /** Hrefs to skip, compared after query/fragment removal. For a destination
+     *  served outside this route table (a static asset, another worker). */
+    ignore?: readonly string[];
+    /** Absolute URLs / `mailto:` / `tel:` are reported under `external` instead
+     *  of failing. Default true. */
+    allowExternal?: boolean;
+    /** Compare literal segments case-sensitively. Default true — a router that
+     *  matches case-insensitively still renders a link the deploy's CDN or a
+     *  case-sensitive origin may not. */
+    caseSensitive?: boolean;
+}
+/**
+ * Check every nav href against the product's route table.
+ *
+ * Pure — returns the full report so a caller can assert on parts of it. Use
+ * {@link assertNavHrefsRegistered} in tests; it turns the report into a failure
+ * that names the offending row, its resolved href, and the near-miss pattern.
+ */
+export declare function checkNavHrefs(items: readonly NavHrefItem[], routes: NavRouteTable, options?: NavHrefCheckOptions): NavHrefReport;
+/**
+ * Fail unless every nav href resolves to a registered route.
+ *
+ * Throws on an empty item list or an empty route table as well: a guard that
+ * examined nothing reports safety it does not provide, and both are what a
+ * mis-wired import looks like.
+ */
+export declare function assertNavHrefsRegistered(items: readonly NavHrefItem[], routes: NavRouteTable, options?: NavHrefCheckOptions): void;

package/dist/session-shell/path.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Path normalisation shared by the shell's routing helpers. Segment-aligned
+ * comparison is the invariant: `/vault` must never claim `/vault-archive`, so
+ * every prefix test here works on whole segments rather than string prefixes.
+ */
+export declare function stripTrailingSlashes(value: string): string;
+/** Bare segment name, so a caller may pass `'/settings'` or `'settings'`. */
+export declare function stripSlashes(value: string): string;
+/** Path with query + fragment removed and trailing slashes trimmed. A caller
+ *  passing a full href instead of a pathname would otherwise match nothing. */
+export declare function normalizePath(pathname: string): string;
+/** True when `path` is `prefix` or a segment-aligned descendant of it, so
+ *  `/vault` never claims `/vault-archive`. */
+export declare function isUnderPrefix(path: string, prefix: string): boolean;
+/** Non-empty segments of a path or route pattern. Leading/trailing/duplicate
+ *  slashes collapse, so `/app//x/` and `app/x` compare equal. */
+export declare function toSegments(value: string): string[];
+/** Canonical display form: rooted, no trailing slash, no empty segments. */
+export declare function toRootedPath(value: string): string;

package/dist/signoff/cli.d.ts

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
-import { R as RunSignoffOptions } from '../run-D80hoLKh.js';
-import '../types-Bd6uW9vQ.js';
-
+import { type RunSignoffOptions } from './run';
 interface ParsedArgs extends RunSignoffOptions {
     readonly jsonPath?: string;
     readonly quiet?: boolean;
 }
-declare function parseArgs(argv: readonly string[]): ParsedArgs;
-declare function runSignoffCli(argv: readonly string[]): Promise<number>;
-
-export { parseArgs, runSignoffCli };
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function runSignoffCli(argv: readonly string[]): Promise<number>;
+export {};

package/dist/signoff/config.d.ts

@@ -0,0 +1,12 @@
+import type { LoadedSignoffConfig, SignoffConfig } from './types';
+export declare function parseSignoffConfig(value: unknown, where: string): SignoffConfig;
+export declare function deriveSignoffConfig(scripts: Readonly<Record<string, string>>): {
+    readonly config: SignoffConfig;
+    readonly used: readonly string[];
+};
+export interface LoadSignoffConfigOptions {
+    readonly repoRoot: string;
+    /** Explicit config path. Missing file is an error, never a silent fallback. */
+    readonly configPath?: string;
+}
+export declare function loadSignoffConfig(options: LoadSignoffConfigOptions): Promise<LoadedSignoffConfig>;

package/dist/signoff/exec.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The subprocess primitive every sign-off step runs through.
+ *
+ * Three properties the gate depends on, none of which `execSync` gives:
+ *
+ * 1. **Cancellable.** Under fail-fast, a build still running when typecheck
+ *    fails is killed rather than waited out — otherwise the "faster than CI"
+ *    claim is spent waiting for work whose verdict no longer matters.
+ * 2. **Process-group kill.** Steps run through `sh -c`, so killing the shell
+ *    leaves `vitest`'s forks and `tsup`'s dts worker orphaned and holding CPU.
+ *    The child is spawned as a group leader and the whole group is signalled.
+ * 3. **Bounded, non-silent capture.** Output is capped, and when the cap is hit
+ *    the elision is stated in the captured text. A gate that quietly drops the
+ *    middle of a failure log is a gate that hides the failure.
+ */
+export interface CommandResult {
+    readonly command: string;
+    readonly cwd: string;
+    readonly exitCode: number;
+    readonly signal: string | null;
+    readonly durationMs: number;
+    readonly output: string;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+}
+export interface RunCommandOptions {
+    readonly command: string;
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Retained bytes before elision. Default 2 MiB. */
+    readonly maxOutputBytes?: number;
+    /** Grace between SIGTERM and SIGKILL. Default 5 s. */
+    readonly killGraceMs?: number;
+    readonly onData?: (chunk: string) => void;
+}
+/**
+ * Run one shell command to completion and report what happened.
+ *
+ * Never throws on a non-zero exit — a failing step is data, not an exception.
+ * It throws only when the process could not be started at all.
+ */
+export declare function runCommand(options: RunCommandOptions): Promise<CommandResult>;

package/dist/signoff/index.d.ts

@@ -1,14 +1,56 @@
-export { R as RunSignoffOptions, r as runSignoff } from '../run-D80hoLKh.js';
-import { L as LoadedSignoffConfig, b as SignoffReport } from '../types-Bd6uW9vQ.js';
-export { c as SignoffAttempt, d as SignoffConfig, e as SignoffConfigOrigin, a as SignoffEvent, f as SignoffHostFacts, g as SignoffInstallResult, h as SignoffInstallSpec, i as SignoffRepoFacts, j as SignoffShuffleSpec, S as SignoffSource, k as SignoffStepResult, l as SignoffStepSpec, m as SignoffStepStatus } from '../types-Bd6uW9vQ.js';
-
-interface LoadSignoffConfigOptions {
-    readonly repoRoot: string;
-    /** Explicit config path. Missing file is an error, never a silent fallback. */
-    readonly configPath?: string;
-}
-declare function loadSignoffConfig(options: LoadSignoffConfigOptions): Promise<LoadedSignoffConfig>;
-
-declare function formatSignoffReport(report: SignoffReport): string;
-
-export { type LoadSignoffConfigOptions, LoadedSignoffConfig, SignoffReport, formatSignoffReport, loadSignoffConfig };
+/**
+ * `@tangle-network/agent-app/signoff` — the local sign-off gate.
+ *
+ * A node-only checker a PRODUCT runs against ITSELF, the shape `/peer-floors`
+ * and `/theme-contract` already established here. The difference is scope:
+ * those check one property, this runs the repo's whole verification in
+ * conditions that reproduce a clean CI environment, and then does what CI does
+ * not.
+ *
+ * **Why this exists.** CI is slow enough to stop being a merge gate, and two
+ * failures credited to CI in one day needed nothing CI has:
+ *
+ *  - Two legal-agent test files failed only in CI with "Cannot bundle Node.js
+ *    built-in node:sqlite". Local passed three separate ways — cleared Vite
+ *    cache, its own `node_modules`, even `--maxWorkers=1`. CI was not smarter;
+ *    it was a clean install with different file scheduling.
+ *  - legal-agent `main` went red because a sibling PR called a function an
+ *    older agent-app did not export — invisible to a clean install, a clean
+ *    typecheck and a green suite, and caught only by `/peer-floors` at the
+ *    wire call.
+ *
+ * Neither is a reason to keep CI as the gate. Both are reasons the local run
+ * must be hermetic. That is what this is:
+ *
+ * | | CI | this gate |
+ * |---|---|---|
+ * | dependency tree | clean, isolated store | clean `git worktree`, store keyed on the lockfile |
+ * | suite order | one arbitrary order | randomized file order, ≥2 seeds, every seed recorded |
+ * | step order | serial, as written in YAML | dependency graph, run as wide as the DECLARED edges allow |
+ * | failure output | one red line in a long log | named step, exit code, seed, captured output |
+ * | reproducibility | re-run the job and hope | one command, printed with the verdict |
+ *
+ * ```ts
+ * import { runSignoff, formatSignoffReport } from '@tangle-network/agent-app/signoff'
+ *
+ * const report = await runSignoff({ repoDir: process.cwd() })
+ * console.log(formatSignoffReport(report))
+ * process.exit(report.ok ? 0 : 1)
+ * ```
+ *
+ * The CLI form is the `agent-app-signoff` bin.
+ *
+ * **Surface is deliberately narrow.** The steps this runs — dependency-graph
+ * scheduling, seed planning, workflow-YAML pin scanning, the pnpm-store cache,
+ * the hermetic `git worktree`, the command runner — are this gate's OWN
+ * implementation, not things a consumer plausibly calls directly; the `agent-
+ * app-signoff` bin imports them from the sibling files (`./run`, `./report`),
+ * never through this barrel. What a consumer embeds is: run the gate, load its
+ * config, print the result. Everything else stays module-internal, where
+ * `knip` can see it unused rather than reading as committed public API with
+ * zero callers.
+ */
+export { runSignoff, type RunSignoffOptions } from './run';
+export { loadSignoffConfig, type LoadSignoffConfigOptions } from './config';
+export { formatSignoffReport } from './report';
+export type { LoadedSignoffConfig, SignoffAttempt, SignoffConfig, SignoffConfigOrigin, SignoffEvent, SignoffHostFacts, SignoffInstallResult, SignoffInstallSpec, SignoffRepoFacts, SignoffReport, SignoffShuffleSpec, SignoffSource, SignoffStepResult, SignoffStepSpec, SignoffStepStatus, } from './types';

package/dist/signoff/invoked-as-script.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Is this module the script the process was started with?
+ *
+ * The obvious spelling — `import.meta.url === pathToFileURL(process.argv[1]).href`
+ * — is wrong for every packaged bin, and wrong in the silent direction: the
+ * module decides it was imported rather than executed, so the CLI does nothing
+ * and exits 0.
+ *
+ * The two sides are not the same kind of path. `import.meta.url` is the module
+ * URL Node resolved, and Node resolves a module's realpath unless started with
+ * `--preserve-symlinks`. `process.argv[1]` is the path as SPELLED on the
+ * command line. A package manager's bin shim spells it through symlinked
+ * directories:
+ *
+ *   argv[1]          …/node_modules/.bin/../@scope/pkg/dist/cli.js
+ *   import.meta.url  …/node_modules/.pnpm/pkg@1.2.3/node_modules/@scope/pkg/dist/cli.js
+ *
+ * Same file, two strings, and a `===` between them is false.
+ *
+ * So the entry path is resolved the same way Node resolved the module before
+ * the comparison. A missing or unresolvable entry is not this function's
+ * business to explain — it is simply not this module, which is the honest
+ * answer and keeps an importer from executing a CLI.
+ */
+export declare function invokedAsScript(moduleUrl: string, entry: string | undefined): boolean;

package/dist/signoff/node-version.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Refuse to sign off on a runtime the product does not ship.
+ *
+ * CI pins its Node version (`actions/setup-node` with `node-version: 22` in all
+ * three fleet workflows). A developer's shell does not — this host runs 24. A
+ * local gate that inherits whatever is on `PATH` therefore verifies a runtime
+ * nobody deploys, and reports it as the runtime that ships. That is the same
+ * failure shape as a number measured in a narrower context than it is
+ * presented in, and it is not acceptable in the thing that replaces the merge
+ * gate.
+ *
+ * So the pin is read from the repo and enforced, or it is absent and the report
+ * says so. Three sources, in order:
+ *
+ *  - `signoff.config.mjs`'s `nodeVersion` — the explicit declaration.
+ *  - `.nvmrc` — the pin a repo already keeps for humans.
+ *  - the `pull_request` workflows' `node-version` (`./workflow-pin`) — the pin
+ *    CI itself runs on.
+ *
+ * **The third source was added because the first two were empty on the entire
+ * fleet, and that produced a false PASS.** legal-agent `4c0d688` failed CI on
+ * `Cannot bundle Node.js built-in "node:sqlite"` and this gate signed it off.
+ * Reproduced in one installed tree, same bytes: Node 22 fails both files, Node
+ * 24 passes both, every time. No `.nvmrc` exists in tax-agent, legal-agent or
+ * agent-app; all three pin `node-version: 22` in the workflow being replaced.
+ * A gate that replaces a workflow has to read the runtime that workflow pins.
+ *
+ * A `.nvmrc` and a workflow that disagree is not resolved by preference — it is
+ * a refusal, because it means the local gate and CI verify different runtimes,
+ * which is the exact defect this module exists to prevent.
+ *
+ * **`engines.node` is deliberately NOT read.** It is a floor (`">=18"`), not a
+ * pin, so treating it as one manufactures refusals on every version above the
+ * floor — and an unsatisfiable gate does not stop bad work, it gets waived.
+ */
+export interface NodeVersionRequirement {
+    /** The declared major, e.g. `22`. */
+    readonly major: number;
+    readonly declared: string;
+    /** Where it came from, for the proof. */
+    readonly source: string;
+}
+export declare function resolveNodeRequirement(repoRoot: string, configured?: string): NodeVersionRequirement | null;
+/**
+ * Throw when the running Node cannot stand in for the declared one.
+ *
+ * Major-only: a patch difference is not a different runtime, and demanding an
+ * exact patch would refuse every host that has not just re-installed.
+ */
+export declare function assertNodeVersion(requirement: NodeVersionRequirement | null, running?: string): void;

package/dist/signoff/proof-attach.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Attaching a proof to the commit it verified.
+ *
+ * ## Why `git notes`, and what the two rejected carriers cost
+ *
+ * **A commit-message trailer** cannot work for the field that matters. The
+ * trailer is part of the commit object, so writing it changes the SHA the proof
+ * claims to cover — the proof would have to be produced before the commit it
+ * names exists. Amending re-writes the SHA again, and GitHub's squash-merge
+ * rebuilds the message from the PR body, so the trailer does not survive the one
+ * transition it would need to.
+ *
+ * **A committed artifact directory** (`.signoff/<sha>.json`) changes the tree,
+ * so the tree hash inside the proof can never cover the file carrying it. It
+ * also lands in every diff, and it is exactly the "file someone can forget"
+ * shape the requirement rules out — deleting it is a normal-looking change.
+ *
+ * **`git notes` wins because it is the only carrier that is addressed BY the
+ * SHA without being part of it.** The note is written after the commit exists,
+ * it changes neither the SHA nor the tree, and `git notes show <sha>` is a
+ * definite yes/no for any commit anyone can name.
+ *
+ * ## The tradeoff `git notes` really carries, and how this module answers it
+ *
+ * Notes are attached to a commit id, and a rebase or a squash-merge produces a
+ * NEW commit id, so the note does not follow by itself. Two mechanisms close
+ * that gap, and both are needed:
+ *
+ *  1. `notes.rewriteRef` (see `SIGNOFF_NOTES_GIT_CONFIG`) makes local rebase and
+ *     amend copy the note forward automatically.
+ *  2. `resolveSignoffProof` falls back to a **tree scan**: it reads every proof
+ *     under the notes ref and matches on the TREE the commit carries. A rebase
+ *     or a squash of one branch onto an unchanged base preserves the tree, so
+ *     the content that was verified is still provably the content that merged,
+ *     even though the SHA changed. The verifier reports which binding it used —
+ *     `exact` or `tree-equivalent` — and never conflates them.
+ *
+ * Notes are neither pushed nor fetched by default; `SIGNOFF_NOTES_GIT_CONFIG`
+ * carries the refspecs that fix that, and a missing note is reported as
+ * `not-found`, never as a pass.
+ */
+import { type SignoffProof } from './proof-record';
+export declare const SIGNOFF_NOTES_REF = "refs/notes/signoff";
+/**
+ * The git configuration a repo needs for notes to travel. Emitted by the CLI
+ * when a proof cannot be found, because the usual cause is an unconfigured repo
+ * rather than an unsigned commit.
+ */
+export declare const SIGNOFF_NOTES_GIT_CONFIG: readonly string[];
+export interface AttachSignoffProofInput {
+    readonly repoDir: string;
+    readonly proof: SignoffProof;
+    /** Revision to annotate; defaults to the commit the proof names. */
+    readonly rev?: string;
+    /** Replace an existing note. Off by default so a second sign-off cannot quietly overwrite the first. */
+    readonly overwrite?: boolean;
+}
+export interface AttachedSignoffProof {
+    readonly commit: string;
+    readonly ref: string;
+}
+export declare function attachSignoffProof(input: AttachSignoffProofInput): AttachedSignoffProof;
+export type SignoffProofLookup = {
+    readonly found: true;
+    readonly proof: SignoffProof;
+    readonly commit: string;
+    readonly binding: 'exact' | 'tree-equivalent';
+} | {
+    readonly found: false;
+    readonly commit: string;
+};
+/** The note attached to exactly this commit, or `found: false`. Never searches. */
+export declare function readSignoffProofNote(repoDir: string, rev: string): SignoffProofLookup;
+/** Every proof stored under the notes ref, paired with the commit it annotates. */
+export declare function listSignoffProofs(repoDir: string): readonly {
+    readonly commit: string;
+    readonly proof: SignoffProof;
+}[];
+/**
+ * Answer "was this SHA signed off" for any commit, including one produced by a
+ * rebase or a squash-merge of the branch that was actually verified.
+ *
+ * Exact note first. Then the tree scan — a proof whose `commitTree` equals this
+ * commit's tree verified byte-identical content, which is the strongest claim
+ * available once the SHA has been rewritten. The binding is returned so a caller
+ * can tell the two apart; nothing here treats them as the same thing.
+ */
+export declare function resolveSignoffProof(repoDir: string, rev: string): SignoffProofLookup;

package/dist/signoff/proof-cli.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+export {};

package/dist/signoff/proof-fixture.d.ts

@@ -0,0 +1,13 @@
+import { type SignoffProofStep } from './proof-record';
+export interface TempRepo {
+    readonly dir: string;
+    write(relativePath: string, contents: string): void;
+    commit(message: string): string;
+    git(args: readonly string[]): string;
+    cleanup(): void;
+}
+export declare function createTempRepo(options?: {
+    readonly name?: string;
+}): TempRepo;
+/** Steps that all succeeded, one per id, with plausible timings. */
+export declare function passingSteps(ids: readonly string[]): SignoffProofStep[];

package/dist/signoff/proof-from-report.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The join between the runner and the proof: one sign-off run produces one
+ * report, and this turns that report into the signed, attachable record.
+ *
+ * Nothing here re-runs or re-judges anything. The runner owns what happened; the
+ * proof owns what is provable about it later. Keeping the two in one direction
+ * is what stops a second, drifting idea of "which steps ran" from appearing.
+ */
+import { type SignoffProof } from './proof-record';
+import type { SignoffReport } from './types';
+export interface ProofFromReportInput {
+    readonly report: SignoffReport;
+    /** Repo identity the verifier's required-step table is keyed on. */
+    readonly repo: string;
+    /** Source repository. Defaults to the root the run recorded. */
+    readonly repoDir?: string;
+    /** Step ids the run treated as required. Defaults to every step the report carries. */
+    readonly declaredRequired?: readonly string[];
+    readonly key?: Uint8Array;
+    readonly now?: Date;
+}
+export declare function proofFromSignoffReport(input: ProofFromReportInput): SignoffProof;

package/dist/signoff/proof-git.d.ts

@@ -0,0 +1,57 @@
+/** A git invocation that exited non-zero, carrying stderr so the caller can act. */
+export declare class SignoffGitError extends Error {
+    readonly args: readonly string[];
+    readonly status: number | null;
+    readonly stderr: string;
+    constructor(args: readonly string[], status: number | null, stderr: string);
+}
+export interface GitResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run git and hand back the raw result. `GIT_OPTIONAL_LOCKS=0` keeps a read
+ * from touching the index while another agent works the same worktree — this
+ * repo is shared by concurrent sessions.
+ */
+export declare function runGit(repoDir: string, args: readonly string[], options?: {
+    readonly input?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}): GitResult;
+/** Run git, or throw. Trailing newline is stripped — every caller wants the value, not the line. */
+export declare function gitText(repoDir: string, args: readonly string[], options?: {
+    readonly input?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}): string;
+/**
+ * Is `ancestor` reachable from `descendant`? A port rather than a direct call so
+ * the verifier stays a pure function over facts a caller supplies.
+ */
+export type IsAncestorFn = (ancestor: string, descendant: string) => boolean;
+export declare function gitIsAncestor(repoDir: string): IsAncestorFn;
+export interface CommitFacts {
+    /** 40-hex commit id. */
+    readonly commit: string;
+    /** 40-hex id of the tree the COMMIT points at. */
+    readonly commitTree: string;
+    readonly parents: readonly string[];
+    /** Committer date, UTC ISO-8601 with a `Z` suffix. */
+    readonly committedAt: string;
+}
+/** Resolve a revision to the commit it names, failing loud on an unknown rev. */
+export declare function resolveCommit(repoDir: string, rev: string): string;
+export declare function readCommitFacts(repoDir: string, rev: string): CommitFacts;
+/**
+ * Hash the tree the checks actually ran against, including uncommitted and
+ * untracked (non-ignored) files.
+ *
+ * This is the field that makes drift detectable. A sign-off that ran over an
+ * edited worktree produces a tree id no commit carries, so it cannot verify
+ * against the commit it claims — which is the intended outcome, not a bug.
+ *
+ * Written through a throwaway index (`GIT_INDEX_FILE`) so a concurrent agent's
+ * staged work in the real index is neither read nor disturbed. `git add -A`
+ * honours `.gitignore`, so `node_modules` / `dist` stay out.
+ */
+export declare function computeWorktreeTree(repoDir: string): string;