@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/continuation/packet-writer.d.ts

@@ -0,0 +1,86 @@
+import type { AppSyncClient } from '../appsync/appsync-client';
+import type { AuthorityScope } from '../local-executor/authority';
+import type { ContinuationPacket, PacketWriteInput, PacketWriteResult, RepoState } from './types';
+import { type DirtyStateCollector } from './dirty-state-collector';
+export interface ContinuationPacketWriterDeps {
+    /** Direct mutation invocation per LOCK #C6-A-10.4.10.2 — NOT routed via emitShellEvent. */
+    appsync: AppSyncClient;
+    /** Authority scope for dirty-state clamp per LOCK #C6-A-7. */
+    authority: AuthorityScope;
+    /**
+     * Optional INFORMATIONAL Class A timeline mirror. Failure is swallowed;
+     * the AUTHORITATIVE audit row is what `recordContinuationPacketWritten`
+     * produced.
+     */
+    shellEmit?: (event: {
+        type: string;
+        taskId: string;
+        packetHash: string;
+    }) => Promise<void>;
+    /** Test seam — override the dirty-state collector. */
+    dirtyStateCollector?: DirtyStateCollector;
+    /** Test seam — override the home directory. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Test seam — clock injection. */
+    clock?: () => number;
+    /** Test seam — random tmp-suffix injection. */
+    randomHex?: () => string;
+}
+export interface ContinuationPacketWriter {
+    write(input: PacketWriteInput): Promise<PacketWriteResult>;
+    /** Test-only — exposes the per-task mutex map size for assertions. */
+    readonly mutexMapSizeForTests: number;
+}
+/**
+ * §8.1 AUTO-SENTINEL placeholders — the values `buildContinuationPacket` writes
+ * for `completedWork` / `remainingWork` / `verification` when the source
+ * implementor did NOT enumerate its progress (e.g. a HARD quota cap where the
+ * agent never produced a structured continuation output — the realistic case
+ * the quota fork covers). Exported so the resume path
+ * (`QuorumLoop.buildResumeBrief`) can DETECT the sentinel-only case and frame
+ * the task summary as the full actionable work, instead of echoing "unknown"
+ * back to the resumed agent (which reads it as "nothing to do" and no-ops).
+ */
+export declare const WORK_NOT_ENUMERATED_SENTINEL = "unknown \u2014 implementor did not enumerate";
+export declare const VERIFICATION_NOT_RECORDED_SENTINEL = "not_checked \u2014 no verification recorded by source implementor";
+/**
+ * Build the canonical 17-field `ContinuationPacket` from the caller-
+ * supplied `PacketWriteInput`. Applies the §8.1 sentinel taxonomy:
+ *   - 8 STRICT-REQUIRED fields → throw `PacketFidelityError` on
+ *     undefined.
+ *   - 1 CALLER-OR-COLLECTOR field (`repoStates`) → fall through to
+ *     `repoStatesFromCollector` (which the caller pre-resolved).
+ *   - 7 AUTO-SENTINEL fields → default per §8.1 table.
+ *   - 1 WRITER-CONSTANT field (`packetVersion`) → always `1`.
+ */
+export declare function buildContinuationPacket(input: PacketWriteInput, repoStatesFromCollector: RepoState[]): ContinuationPacket;
+/**
+ * §4.2 LOCK #C6-A-2 — compute the JCS-canonical-JSON SHA-256 hash of
+ * the typed packet struct. Library pin: `json-freeze@^1.x` (RFC 8785
+ * conformant). The TS-side hash MUST match the Rust `serde_jcs` hash
+ * byte-for-byte (P1 parity test).
+ */
+export declare function computePacketHash(packet: ContinuationPacket): string;
+/**
+ * §4.2 LOCK #C6-A-2 — render the YAML frontmatter + prose-body
+ * markdown body. The YAML frontmatter is the human-readable
+ * serialization; the JCS-canonical-JSON is the cross-impl hash input.
+ * Both are derived from the same parsed struct.
+ */
+export declare function renderPacketMarkdown(packet: ContinuationPacket): string;
+/**
+ * §4.3 LOCK #C6-A-3 — resolve the absolute path to a task's directory.
+ * Exported for use by the reader + status CLI.
+ */
+export declare function getTaskDirectoryPath(taskId: string, homeDir?: string): string;
+/**
+ * §4.3 LOCK #C6-A-3 — resolve the absolute path to a task's
+ * CONTINUATION.md.
+ */
+export declare function getPacketFilePath(taskId: string, homeDir?: string): string;
+/**
+ * Factory for the CP-6 packet writer. Per-task `Mutex` map is owned by
+ * the returned instance (one map per writer instance — production
+ * code wires a single writer per LE process).
+ */
+export declare function createContinuationPacketWriter(deps: ContinuationPacketWriterDeps): ContinuationPacketWriter;

package/dist/continuation/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * CP-6 LOCK #C6-A-1 AgentKind union — 4 values per AGY-2.0-SUPPORT-DESIGN.md.
+ * As of Phase C, ANTIGRAVITY is a fully-valid continuation SOURCE and TARGET
+ * end-to-end (TS `VALID_TARGET_AGENTS` + the Rust
+ * `recordContinuationPacketWritten` / `apply_user_decision` validators all
+ * accept it; the Codex M2 §4.10.4 rejection was inverted in Phase C).
+ */
+export type AgentKind = 'CLAUDE' | 'CODEX' | 'GEMINI' | 'ANTIGRAVITY';
+/**
+ * CP-6 LOCK #C6-A-1 — 4-value `HandoffReason` union. Implementor-
+ * continuation triggers only (master §8:932-937 reserves
+ * `reviewer_unavailable` / `reviewer_conflict` / `unsafe_action` for
+ * CP-3.h / CP-2.h / CP-9 min escalation — NOT CP-6 continuation
+ * packet-write paths).
+ *
+ * The 4 §7 trigger rows map onto §6:827 wire spellings 1:1:
+ *   - §7 "Quota exhausted" → `quota_exhausted`
+ *   - §7 "Auth failed"     → `auth_failed`
+ *   - §7 "Agent timeout"   → `timeout`
+ *   - §7 "User request"    → `user_requested`
+ *
+ * §6:827 also defines `explicit_escalation` + `reviewer_conflict`;
+ * the CP-6 reader accepts them but the writer never emits them.
+ */
+export type HandoffReason = 'quota_exhausted' | 'auth_failed' | 'timeout' | 'user_requested';
+/**
+ * Gate-state snapshot embedded in every continuation packet. Captures
+ * the prior implementor's verification + reviewer-quorum + final-
+ * approval pose so the next implementor can read but not bypass.
+ */
+export interface GateState {
+    verification: 'not_started' | 'pass' | 'fail';
+    reviewerQuorum: 'not_started' | 'pass' | 'revise' | 'block';
+    finalApproval: boolean;
+}
+/**
+ * Per-repo state captured at packet-write time by LOCK #C6-A-7
+ * dirty-state collector. `headSha` / `branch` fall through to the
+ * literal `"unknown"` sentinel when git is unavailable or
+ * `git rev-parse` times out.
+ */
+export interface RepoState {
+    /** repo basename (e.g., `codevibe-backend`). */
+    repo: string;
+    /** absolute filesystem path (clamped to authority writeScopes/readScopes). */
+    path: string;
+    /** git branch — literal `"unknown"` when git rev-parse fails. */
+    branch: string;
+    /** 40-hex git sha — literal `"unknown"` when git rev-parse fails. */
+    headSha: string;
+    dirty: boolean;
+    /** git status --porcelain output, relative to repo root. */
+    changedFiles: string[];
+}
+/**
+ * CP-6 LOCK #C6-A-1 — 17-field continuation packet structural type.
+ * Mirrors master §6:820-852 byte-for-byte.
+ *
+ * Sentinel taxonomy per §8.1:
+ *   - WRITER-CONSTANT (1):       packetVersion (always 1)
+ *   - STRICT-REQUIRED (8):       taskId, sessionId, sourceAgent,
+ *                                targetAgent, handoffReason, role,
+ *                                taskSummary, expiresAt
+ *   - CALLER-OR-COLLECTOR (1):   repoStates (falls through to
+ *                                dirty-state collector when caller
+ *                                passes undefined)
+ *   - AUTO-SENTINEL (7):         completedWork, remainingWork,
+ *                                verification, activeRules, gateState,
+ *                                safetyConstraints, reviewHistoryRefs
+ */
+export interface ContinuationPacket {
+    packetVersion: 1;
+    taskId: string;
+    sessionId: string;
+    sourceAgent: AgentKind;
+    targetAgent: AgentKind;
+    handoffReason: HandoffReason;
+    /** CP-6 always emits `"implementor"`; reviewer-role packets deferred. */
+    role: 'implementor';
+    repoStates: RepoState[];
+    /** Master §6:839 — "what the implementor is trying to complete". */
+    taskSummary: string;
+    /** Master §6:840 — facts already done. */
+    completedWork: string[];
+    /** Master §6:841 — next actions. */
+    remainingWork: string[];
+    /** Master §6:842 — tests run AND tests intentionally not run. */
+    verification: string[];
+    /** Master §6:843 — gate plan + commit/push rules + safety constraints. */
+    activeRules: string[];
+    gateState: GateState;
+    /** Master §6:849. */
+    safetyConstraints: string[];
+    /** Master §6:850 — file paths or AppSync row IDs. */
+    reviewHistoryRefs: string[];
+    /** ISO-8601 RFC 3339 timestamp. */
+    expiresAt: string;
+}
+export declare class PacketFidelityError extends Error {
+    readonly missingFields: string[];
+    constructor(missingFields: string[], message?: string);
+}
+export declare class PacketIoError extends Error {
+    readonly cause?: NodeJS.ErrnoException;
+    constructor(message: string, cause?: NodeJS.ErrnoException);
+}
+export declare class PacketHashMismatch extends Error {
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(expectedHash: string, actualHash: string);
+}
+export declare class PacketAuditEmitError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class PacketNotFound extends Error {
+    readonly packetPath: string;
+    constructor(packetPath: string);
+}
+export declare class PacketUnverified extends Error {
+    readonly packetPath: string;
+    readonly taskId: string;
+    readonly packetHash: string;
+    constructor(packetPath: string, taskId: string, packetHash: string);
+}
+export declare class FrontmatterMalformed extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+export declare class SchemaInvalid extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+export declare class PacketPermissionsLoose extends Error {
+    readonly path: string;
+    readonly actualMode: number;
+    constructor(filePath: string, actualMode: number);
+}
+/**
+ * Caller-supplied fields for `writer.write()`. All 8 STRICT-REQUIRED
+ * fields (per §8.1 sentinel taxonomy) are required at the type level;
+ * AUTO-SENTINEL fields are optional and default to the §8.1 sentinel
+ * when omitted. `repoStates` is optional — when undefined, the writer
+ * dispatches to the dirty-state collector.
+ *
+ * `offerId` is not part of the packet body itself (it lives on the
+ * backend audit row per LOCK #C6-A-10); the writer forwards it to
+ * `AppSyncClient.recordContinuationPacketWritten`. Use `null` for
+ * LE-initiated writes that have no prior Class B offer.
+ */
+export interface PacketWriteInput {
+    taskId: string;
+    sessionId: string;
+    sourceAgent: AgentKind;
+    targetAgent: AgentKind;
+    handoffReason: HandoffReason;
+    /**
+     * STRICT-REQUIRED per §8.1 sentinel taxonomy (Stage 2 R1 M-2 fix —
+     * was previously optional with a silent `?? 'implementor'` default,
+     * a contract deviation from the locked design). Callers MUST pass
+     * `'implementor'` explicitly; the writer throws `PacketFidelityError`
+     * with `missingFields: ['role', ...]` when undefined.
+     */
+    role: 'implementor';
+    taskSummary: string;
+    expiresAt: string;
+    repoStates?: RepoState[];
+    completedWork?: string[];
+    remainingWork?: string[];
+    verification?: string[];
+    activeRules?: string[];
+    gateState?: GateState;
+    safetyConstraints?: string[];
+    reviewHistoryRefs?: string[];
+    offerId?: string | null;
+    blockedReason?: HandoffReason;
+    /**
+     * PHASE-CP-10-MIN (#585) — the round's gate the desktop is handing off from
+     * (H-A). Forwarded to `recordContinuationPacketWritten` (the additive
+     * `gateId: ID` input) so the handler `fetch_row`s it, cross-checks
+     * `gate_row.task_id == input.task_id`, and uses it as the #C10M-14
+     * mutual-exclusion stamp target + the emitted prompt's `EmitContext.gate_id`.
+     * NOT embedded in the packet body. Required at the handler for #585's two
+     * triggers; optional at the type level so legacy/LE-initiated writes that
+     * predate CP-10 still type-check.
+     */
+    gateId?: string;
+}
+export interface PacketWriteResult {
+    /** 64-char lowercase hex SHA-256 of JCS-canonical-JSON(packet). */
+    packetHash: string;
+    /** Absolute path of the written CONTINUATION.md. */
+    path: string;
+}
+export interface PacketListEntry {
+    taskId: string;
+    packetExists: boolean;
+    lastModified: Date | null;
+    packetHash?: string;
+}
+/**
+ * Discriminated union returned by `reader.read()` when used in
+ * fail-soft mode. Throwing variants live on the reader directly; the
+ * union is exported for callers that prefer typed-return semantics.
+ */
+export type ContinuationPacketReadResult = {
+    kind: 'ok';
+    packet: ContinuationPacket;
+    packetHash: string;
+} | {
+    kind: 'not_found';
+    path: string;
+} | {
+    kind: 'unverified';
+    path: string;
+    taskId: string;
+    packetHash: string;
+} | {
+    kind: 'permissions_loose';
+    path: string;
+    actualMode: number;
+} | {
+    kind: 'frontmatter_malformed';
+    path: string;
+    message: string;
+} | {
+    kind: 'schema_invalid';
+    path: string;
+    errors: string[];
+} | {
+    kind: 'hash_mismatch';
+    path: string;
+    expectedHash: string;
+    actualHash: string;
+} | {
+    kind: 'io_error';
+    path: string;
+    message: string;
+};

package/dist/credential-broker/__tests__/broker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credential-broker/__tests__/canonical.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credential-broker/__tests__/scrubber.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credential-broker/__tests__/upstream-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credential-broker/__tests__/vendor-key-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credential-broker/audit-sink.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The five CP-7 audit kinds (§3.5), in their snake_case wire form — the
+ * exact strings the `AuditEventKind` enum serializes as and the
+ * `audit-keys` discriminator constants use. Defined here (not imported
+ * from a Rust-mirrored module) because W1 only needs the broker-side
+ * wire kinds; W3 wires these to the real `AuditEventKind` enum + NAPI
+ * `parse_audit_kind`.
+ *
+ * Note: only `model_call`, `model_call_result`, `model_context_scrubbed`,
+ * and `broker_credential_loaded` are broker-emitted. `egress_denied` is
+ * emitted by the substrate's egress proxy (§3.5, W2/W3) — it is included
+ * in the union for completeness of the CP-7 audit taxonomy but the broker
+ * never emits it.
+ */
+export type AuditKindCp7 = "model_call" | "model_call_result" | "egress_denied" | "model_context_scrubbed" | "broker_credential_loaded";
+/**
+ * The strict audit sink the broker emits through (§3.5).
+ *
+ * Per §3.5: the sender transmits `{kind, payload}` and BLOCKS for the
+ * LE's durable ACK. A resolved `{ ack }` means the row is durably on
+ * disk (the gated effect — the upstream forward — may proceed for a
+ * pre-forward row). A resolved `{ nack }` means the durable write failed
+ * (the broker fails closed: 503, no forward). A rejected/timed-out promise
+ * is treated by the broker exactly like a NACK (fail closed on a
+ * pre-forward row).
+ */
+export interface StrictAuditSink {
+    emit(kind: AuditKindCp7, payload: Record<string, unknown>): Promise<{
+        ack: string;
+    } | {
+        nack: string;
+    }>;
+}
+/**
+ * A recorded emit, surfaced by {@link StubStrictAuditSink} for test
+ * assertions (the real LE emitter exposes nothing comparable — this is a
+ * test seam only).
+ */
+export interface RecordedAuditEmit {
+    kind: AuditKindCp7;
+    payload: Record<string, unknown>;
+}
+/**
+ * In-memory deterministic `StrictAuditSink` for unit tests + the injected
+ * default until W3. Every `emit` ACKs with a deterministic
+ * `stub-ack-<n>` id and records the `{kind, payload}` for assertions.
+ *
+ * Two test hooks (both default off so the happy path is deterministic):
+ * - `nackKinds`: any kind in this set NACKs instead of ACKing — exercises
+ *   the audit-before-effect 503 path.
+ * - `failKinds`: any kind in this set REJECTS the promise — exercises the
+ *   "IPC error / timeout treated as fail-closed" path.
+ */
+export declare class StubStrictAuditSink implements StrictAuditSink {
+    private readonly opts;
+    readonly emitted: RecordedAuditEmit[];
+    private counter;
+    constructor(opts?: {
+        nackKinds?: ReadonlyArray<AuditKindCp7>;
+        failKinds?: ReadonlyArray<AuditKindCp7>;
+    });
+    emit(kind: AuditKindCp7, payload: Record<string, unknown>): Promise<{
+        ack: string;
+    } | {
+        nack: string;
+    }>;
+    /** All emitted rows of a given kind (test helper). */
+    ofKind(kind: AuditKindCp7): RecordedAuditEmit[];
+}

package/dist/credential-broker/broker-config.d.ts

@@ -0,0 +1,39 @@
+import type { VendorProvider } from "./types";
+/**
+ * Per-provider wire facts the broker synthesizes on the upstream call.
+ */
+export interface ProviderConfig {
+    /** Upstream origin (scheme + host) the broker forwards to. */
+    readonly upstreamBaseUrl: string;
+    /** The canonical upstream path for this provider's model route. */
+    readonly upstreamPath: "/v1/messages" | "/v1/responses";
+    /**
+     * Headers the broker synthesizes on EVERY upstream call — overriding
+     * whatever the agent supplied. `content-type` is always normalized to
+     * `application/json` (the only carried-through content type, §3.4).
+     */
+    readonly synthesizedHeaders: Readonly<Record<string, string>>;
+    /**
+     * The EXACT allowlist of `anthropic-beta` (or provider equivalent)
+     * tokens the broker will pass through. A request carrying a beta token
+     * outside this set is rejected (400) — header VALUES are agent-
+     * controlled and can carry data (Codex R2). Empty for OpenAI (no beta
+     * header is forwarded).
+     */
+    readonly betaTokenAllowlist: ReadonlySet<string>;
+    /**
+     * The name of the agent-supplied beta header this provider honors
+     * (lowercased), or `null` if the provider has none. Used by the
+     * canonical constructor to find the agent's beta tokens to validate.
+     */
+    readonly betaHeaderName: string | null;
+}
+/**
+ * Resolve the locked wire facts for a provider. Pure data — no I/O.
+ */
+export declare function getProviderConfig(provider: VendorProvider): ProviderConfig;
+/**
+ * Map an inbound broker route path to the vendor provider it gateways.
+ * `/v1/messages` → Anthropic, `/v1/responses` → OpenAI.
+ */
+export declare function providerForPath(path: string): VendorProvider | null;

package/dist/credential-broker/broker-token.d.ts

@@ -0,0 +1,123 @@
+import type { BrokerToken } from "./types";
+/**
+ * Mints + holds the current per-session broker token, and authenticates
+ * inbound agent→broker tokens against it. A new token replaces the prior
+ * one (single active token per session); `authenticate` accepts ONLY the
+ * current, unexpired value — every other value (including a just-rotated
+ * old token) is rejected, which the broker maps to the only 401 it emits.
+ */
+/**
+ * A grace-rotation handle (Finding 3). `rotateWithGrace` returns this; the LE
+ * passes it back to {@link BrokerTokenMinter.commitRotation} /
+ * {@link BrokerTokenMinter.rollbackRotation}. The `generation` GENERATION-BINDS
+ * the commit/rollback to the SPECIFIC rotation that produced it: a stale handle
+ * (from a rotation already superseded by a newer one) is rejected, so a slow
+ * commit/rollback cannot clobber a newer in-flight rotation's token.
+ */
+export interface RotationHandle {
+    readonly token: BrokerToken;
+    readonly generation: number;
+}
+export declare class BrokerTokenMinter {
+    private readonly ttlMs;
+    private current;
+    /**
+     * During a rotation the PRIOR token stays acceptable until the LE confirms
+     * the apiKeyHelper file holds the NEW token (`commitRotation`). This closes
+     * the 401-loop window the contract forbids (Stage-2 M-3): if we invalidated
+     * the prior token BEFORE the file refresh landed, the agent's file would hold
+     * a now-rejected token until the next refresh. With the grace token, BOTH the
+     * new and the prior token authenticate until the write is confirmed.
+     */
+    private graceToken;
+    /**
+     * Finding 3 — generation counter, bumped on every successful grace rotation.
+     * Commit/rollback are bound to the generation of the rotation they belong to;
+     * a stale (superseded) commit/rollback is a no-op. The generation also gates
+     * OVERLAPPING rotations: `rotateWithGrace` REJECTS (returns null) while a grace
+     * is still pending, so two near-concurrent rotations can never chain
+     * grace→grace and strand the file token.
+     */
+    private generation;
+    constructor(ttlMs?: number);
+    /** Mint (or rotate) the session's broker token; returns the new token. */
+    mint(now?: number): BrokerToken;
+    /**
+     * M-3 — SAFE rotation. Mint a NEW current token but KEEP the prior token
+     * valid (as a grace token) so there is no window where the agent's file (which
+     * still holds the prior token until the LE rewrites it) is rejected. The LE
+     * MUST call {@link commitRotation} AFTER it confirms the helper file now holds
+     * the new token (drops the grace token), or {@link rollbackRotation} if the
+     * file write FAILED (restores the prior token as current and discards the new
+     * one — the agent's file is still valid, fail-closed, no dead token).
+     *
+     * Finding 3 — OVERLAP REJECTION: returns null when a grace rotation is already
+     * pending (not yet committed/rolled back). Chaining grace→grace would make the
+     * SECOND rotation's grace token be the FIRST rotation's new token (not the
+     * file-resident prior token); if the first refresh then writes its token and
+     * commits, the file token could be left unauthenticated. By refusing to start a
+     * second rotation until the first settles, BOTH tokens that ever authenticate
+     * are {file-resident prior, new} — the file token is never stranded.
+     *
+     * Returns the {@link RotationHandle} for the new token, or null if the broker
+     * has no current token yet (nothing to rotate) OR a rotation is in-flight.
+     */
+    rotateWithGrace(now?: number): RotationHandle | null;
+    /**
+     * Confirm the helper file now holds the new token — drop the grace token so
+     * the prior token stops authenticating (single-active-token restored).
+     *
+     * Finding 3 — generation-bound: a commit whose `generation` does not match the
+     * current generation is STALE (a newer rotation/mint superseded it) and is a
+     * NO-OP, so it cannot drop a newer rotation's grace token.
+     */
+    commitRotation(handle?: RotationHandle): void;
+    /**
+     * The file refresh FAILED — roll back: restore the prior (grace) token as
+     * current and discard the just-minted new token. The agent's file still holds
+     * the prior token, which is once again the sole active token → no dead-token
+     * window. No-op if there is no pending grace rotation.
+     *
+     * Finding 3 — generation-bound: a rollback whose `generation` does not match
+     * the current generation is STALE and a NO-OP, so a late rollback from a
+     * superseded rotation cannot revert a newer rotation's token.
+     */
+    rollbackRotation(handle?: RotationHandle): void;
+    /** Whether a rotation is mid-flight (grace token still accepted). Test seam. */
+    hasPendingGrace(): boolean;
+    /** The current token, or null if none minted yet. */
+    get(): BrokerToken | null;
+    /**
+     * EVERY broker-token value that `authenticate()` would currently accept — the
+     * CURRENT token plus, during a mid-flight grace rotation, the PRIOR (grace)
+     * token. Used by the broker's self-credential guard so it scrubs ALL tokens a
+     * model-bound field could be carrying, not just `get()` (Stage-2 MEDIUM): the
+     * prior token still authenticates during the grace window AND is still resident
+     * in the agent's helper file, so a model-bound field echoing it is a live-token
+     * leak the guard must redact. Values are returned only (the actual scrub +
+     * commit/rollback gate is the caller's); a stale/expired grace token is NOT
+     * included (it can no longer authenticate, so it is not a live secret).
+     *
+     * NOTE: this does NOT filter on `expiresAtMs` — `authenticate()` rejects an
+     * expired token, but an expired-yet-still-resident token in the helper file is
+     * still a secret-shaped value the guard should keep out of model-bound content;
+     * we err toward scrubbing both held values whenever they are non-null. (An
+     * expired token cannot be USED, but redacting it is strictly safer and never
+     * wrong — the guard only ever removes a value, never adds one.)
+     */
+    acceptedValues(): string[];
+    /**
+     * Authenticate an inbound agent→broker token. True for the current, unexpired
+     * token value OR (during a mid-flight rotation) the unexpired grace token —
+     * the latter keeps the agent's pre-refresh file valid until the LE confirms
+     * the file rewrite (M-3 no-rejection-window contract). A missing / stale /
+     * expired / mismatched token → false (the broker returns 401 — the ONLY 401
+     * it emits, §3.2).
+     *
+     * Constant-time-ish compare is unnecessary for a loopback-only local
+     * token, but we still avoid leaking via early-return on length.
+     */
+    authenticate(token: string | undefined, now?: number): boolean;
+    /** Zeroize the held token (broker teardown). */
+    clear(): void;
+}