gennady 0.8.3 → 0.8.4-draft.2

package/dist/services/agent-inbox/modules/inbox-chat/mutation-runtime.d.ts

@@ -0,0 +1,91 @@
+import type { JournalPort } from '../inbox-core/event-journal.js';
+import { Executor } from '../inbox-queue/executor.js';
+import type { TaskQueuePort } from '../inbox-queue/task-queue.js';
+import { TaskRegistry } from '../inbox-queue/task-registry.js';
+import type { SessionRouterPort } from '../inbox-queue/session-router.js';
+import type { MutationProposal } from './types.js';
+import { MutationApplier, type ApplyResult } from './mutation-applier.js';
+/** @purpose Result produced only after the queue executor owns the complete mutation lifecycle. */
+export type MutationRuntimeResult = {
+    /** @purpose Queue task that was materialized from the HTTP proposal. */
+    taskId: string;
+    /** @purpose CAS application outcome. */
+    result: ApplyResult;
+};
+/**
+ * @purpose Consume `mutate_artifact` through the same durable Executor and producer-session
+ * routing used by the live runtime.
+ * @invariant HTTP can submit a proposal but never transitions/apply-writes a mutation itself.
+ */
+export declare class MutationRuntime {
+    /** @purpose Sole CAS writer and durable snapshot owner for review artifacts. */
+    protected _applier: MutationApplier;
+    /** @purpose Shared MR queue observed by the executor and API projections. */
+    protected _queue: TaskQueuePort;
+    /** @purpose Durable task lifecycle journal. */
+    protected _journal: JournalPort;
+    /** @purpose Immutable task definition registry used by each MR executor. */
+    protected _registry: TaskRegistry;
+    /** @purpose Optional producer-session routing seam for live serve. */
+    protected _sessionRouter?: SessionRouterPort;
+    /** @purpose Durable executor instances keyed by canonical MR reference. */
+    protected _executors: Map<string, Executor>;
+    /**
+     * @purpose Construct one executor-backed mutation consumer.
+     * @param deps Shared queue, journal, CAS writer, proposal flow and optional producer router.
+     */
+    constructor(deps: {
+        applier: MutationApplier;
+        queue: TaskQueuePort;
+        journal: JournalPort;
+        registry?: TaskRegistry;
+        sessionRouter?: SessionRouterPort;
+    });
+    /**
+     * @purpose Materialize and consume one operator proposal through queue → SessionRouter →
+     * MutationApplier. The durable Executor owns task status and its journal events.
+     * @param mr Canonical MR reference owning the proposal.
+     * @param proposal Explicit operator-approved artifact mutation.
+     * @param revision Caller-observed CAS revision.
+     * @returns Queue identity and the completed CAS outcome.
+     */
+    submit(mr: string, proposal: MutationProposal, revision: number): Promise<MutationRuntimeResult>;
+    /**
+     * @purpose Rebuild one MR queue from durable `task_created`/`task_status` events and consume
+     * incomplete mutation work after a process restart.
+     * @param mr Canonical MR reference whose executor is being recovered.
+     * @returns Outcomes for every mutation that was resumed in this pass.
+     */
+    recover(mr: string): Promise<MutationRuntimeResult[]>;
+    /**
+     * @purpose Resume every MR that has ever journaled a durable mutation task before the production
+     * HTTP surface accepts more work.
+     * @invariant Recovery discovers MR ownership solely from the shared append-only journal; callers
+     *   never need a manual per-MR recovery seam after a process restart.
+     * @returns Outcomes for all mutation tasks resumed during boot.
+     */
+    recoverAll(): Promise<MutationRuntimeResult[]>;
+    /**
+     * @purpose Route and apply a mutation only after the Executor has durably marked it running.
+     * @param mr Canonical MR reference.
+     * @param executor Durable task lifecycle owner.
+     * @param taskId Started mutation task identity.
+     * @param proposal Persisted operator-approved mutation proposal.
+     * @param revision Persisted CAS revision.
+     * @returns Completed task identity and CAS result.
+     */
+    protected _consume(mr: string, executor: Executor, taskId: string, proposal: MutationProposal, revision: number): Promise<MutationRuntimeResult>;
+    /**
+     * @purpose Restore an applied mutation using MutationApplier's durable per-MR snapshot.
+     * @param mr Canonical MR reference owning the snapshot.
+     * @param snapshotId Durable snapshot selected by the operator.
+     * @returns The persisted undo outcome.
+     */
+    undo(mr: string, snapshotId: string): Promise<Awaited<ReturnType<MutationApplier['undo']>>>;
+    /**
+     * @purpose Return the single durable executor bound to an MR.
+     * @param mr Canonical MR reference.
+     * @returns Existing or newly constructed MR executor.
+     */
+    protected _executorFor(mr: string): Executor;
+}

package/dist/services/agent-inbox/modules/inbox-chat/operator-session.d.ts

@@ -0,0 +1,102 @@
+import type { JournalPort } from '../inbox-core/event-journal.js';
+import type { Anchor } from './anchor.js';
+/** @purpose One durable operator message persisted as a `chat_turn` journal event. */
+export type OperatorTurn = {
+    /** @purpose Durable turn identifier. */
+    turnId: string;
+    /** @purpose Author role in the operator conversation. */
+    role: 'operator' | 'assistant';
+    /** @purpose Visible text for this durable turn. */
+    text: string;
+    /** @purpose Optional artifact context preserved with the turn. */
+    anchor?: Anchor;
+};
+/** @purpose Read-only operator conversation surface; write and VCS-write tools are deliberately absent. */
+export interface ChatPort {
+    /**
+     * @purpose Append a question and its answer to durable MR history.
+     * @param mr MR key.
+     * @param text Operator question.
+     * @param [anchor] Optional artifact anchor.
+     * @returns Assistant turn.
+     */
+    ask(mr: string, text: string, anchor?: Anchor): Promise<OperatorTurn>;
+    /**
+     * @purpose Stop any currently in-flight MR question.
+     * @param mr MR key.
+     * @returns Completion after cancellation.
+     */
+    stop(mr: string): Promise<void>;
+    /**
+     * @purpose Project ordered durable journal turns for one MR.
+     * @param mr MR key.
+     * @returns Turns oldest first.
+     */
+    history(mr: string): OperatorTurn[];
+}
+/**
+ * @purpose Persist operator turns in the authoritative MR event journal and restart an overflowed context transparently.
+ * @implements {ChatPort} in ./operator-session.ts
+ */
+export declare class OperatorSession implements ChatPort {
+    /** @purpose MR journal backing restart-safe history. */
+    protected _journal: JournalPort;
+    /** @purpose Optional read-only answer source; no mutation capability is accepted by this seam. */
+    protected _answer: (text: string, anchor?: Anchor, digest?: string) => Promise<string>;
+    /** @purpose In-flight questions reissued after context overflow. */
+    protected _inflight: Map<string, {
+        mr: string;
+        text: string;
+        anchor?: Anchor;
+        generation: number;
+        cancelled: boolean;
+        replacement?: OperatorTurn;
+    }>;
+    /**
+     * @purpose Create a journal-backed read-only operator conversation.
+     * @param deps Durable journal and optional read-only answer seam.
+     */
+    constructor(deps: {
+        journal: JournalPort;
+        answer?: (text: string, anchor?: Anchor, digest?: string) => Promise<string>;
+    });
+    /** @see {ChatPort#ask} in ./operator-session.ts */
+    ask(mr: string, text: string, anchor?: Anchor): Promise<OperatorTurn>;
+    /** @see {ChatPort#stop} in ./operator-session.ts */
+    stop(mr: string): Promise<void>;
+    /** @see {ChatPort#history} in ./operator-session.ts */
+    history(mr: string): OperatorTurn[];
+    /**
+     * @purpose Reissue an in-flight question after an ephemeral OpenCode context overflow using a durable thread digest.
+     * @param mr MR owning the conversation.
+     * @param turnId Original operator turn to reissue.
+     * @returns Assistant answer in the same journal-backed history.
+     */
+    restartWithDigest(mr: string, turnId: string): Promise<OperatorTurn>;
+    /**
+     * @purpose Persist a turn produced by the live HTTP/OpenCode bridge without issuing a second prompt.
+     * @param mr MR owning the durable turn.
+     * @param turn Already-resolved operator or assistant turn.
+     * @returns Completion after the authoritative journal append.
+     */
+    record(mr: string, turn: OperatorTurn): Promise<void>;
+    /**
+     * @purpose Register a persisted HTTP operator turn for durable overflow restart; the bridge owns
+     * the initial prompt and this projection owns its handoff.
+     * @param mr Canonical MR reference.
+     * @param turn Persisted operator turn to make restartable.
+     */
+    begin(mr: string, turn: OperatorTurn): void;
+    /**
+     * @purpose Remove a successfully settled HTTP turn from the overflow handoff registry.
+     * @param turnId Operator turn identity previously passed to `begin()`.
+     */
+    settle(turnId: string): void;
+    /**
+     * @purpose Append one explicitly shaped chat turn to the journal.
+     * @param mr MR owning the turn.
+     * @param turn Durable turn payload.
+     * @returns Completion after fsync.
+     */
+    protected _append(mr: string, turn: OperatorTurn): Promise<void>;
+}

package/dist/services/agent-inbox/modules/inbox-chat/origin.d.ts

@@ -0,0 +1,20 @@
+import type { ContextChipOrigin } from './types.js';
+/**
+ * @purpose Map a selected quote to its real 1-based line range in an artifact's raw source (D-115)
+ *   — replaces absent DOM `data-line` markers.
+ * @invariant Degrades to `{ startLine: 1, endLine: 1 }` only when `quote` is nowhere in `rawText`
+ *   — otherwise it always returns the real line span.
+ * @param artifact Artifact name/identifier the fragment came from.
+ * @param rawText Full raw source text of `artifact`.
+ * @param quote Selected fragment (already trimmed by the caller, but re-trimmed here defensively).
+ * @returns Concrete origin — real line range when `quote` resolves, `{1,1}` sentinel otherwise.
+ */
+export declare function resolveOrigin(artifact: string, rawText: string, quote: string): ContextChipOrigin;
+/**
+ * @purpose Whole-artifact origin for a `mention`-kind chip (D-115) — coarse by design: fragment is
+ *   the whole file, so range spans line 1 to last line.
+ * @param artifact Artifact name/identifier.
+ * @param rawText Full raw source text of `artifact`.
+ * @returns Origin spanning the entire artifact.
+ */
+export declare function resolveWholeArtifactOrigin(artifact: string, rawText: string): ContextChipOrigin;

package/dist/services/agent-inbox/modules/inbox-chat/types.d.ts

@@ -0,0 +1,76 @@
+/** @purpose Kind of context fragment attached to a chat turn — closed enum, rejects other values at compile time. */
+export type ContextChipKind = 'selection' | 'mention' | 'candidate';
+/** @purpose Structural anchor to where a chip's fragment came from — file:line, not bare text (D-115, Cursor `@path#L76-82` / Copilot `#file:FILE:RANGE` format). */
+export type ContextChipOrigin = {
+    /** @purpose Artifact the fragment came from — `README.md` | `PLAN.md` | `<track>.task.md` | `review.json` | code file path */
+    artifact: string;
+    /** @purpose 1-based first line of the fragment inside `artifact` */
+    startLine: number;
+    /** @purpose 1-based last line of the fragment inside `artifact` */
+    endLine: number;
+};
+/** @purpose One prompt-attached fragment of context — selection highlight, @-mention, or inline candidate ask (CH-01/CH-04/CH-07). */
+export type ContextChip = {
+    /** @purpose Chip origin — selection highlight, @-mention, or candidate ask */
+    kind: ContextChipKind;
+    /** @purpose Quoted text shown on the chip pill */
+    quote: string;
+    /** @purpose Reference resolved by the chip — `review.json#<candidateId>`, a file path, or a diagram id */
+    source: string;
+    /** @purpose Structural file:line anchor reaching the model (D-115) | @invariant Required — never omitted, never erased by staleness (orthogonal to `source`) */
+    origin: ContextChipOrigin;
+    /** @purpose Set by `ContextAssembler#reresolveChips` when `source` no longer resolves against the current `review.json` | @invariant Marks staleness, never silently drops the chip (D-101) */
+    stale?: boolean;
+};
+/** @purpose Provenance tag surfaced on a mutation whose input came from MR-authored text (D-98) — human-gate visibility before Apply. */
+export type MutationProvenance = {
+    /** @purpose Always true — presence of the field is itself the signal */
+    groundedInMrText: true;
+    /** @purpose Exact MR-text quote that grounded the proposed mutation */
+    quote: string;
+};
+/** @purpose One assistant-proposed structural change to `review.json` — v1 ops only (D-90); `add`/`set-verdict` deferred. */
+export type MutationProposal = {
+    /** @purpose Mutation kind */
+    op: 'edit' | 'remove' | 'set-severity';
+    /** @purpose Candidate id in `review.json` the mutation targets */
+    target: string;
+    /** @purpose Field value(s) before the mutation */
+    before: unknown;
+    /** @purpose Field value(s) after the mutation */
+    after: unknown;
+    /** @purpose Present only for a downgrade/remove sourced from MR text (D-98) */
+    provenance?: MutationProvenance;
+};
+/** @purpose One turn of the review chat — question, attached context, full answer, proposed mutations, revision at ask-time. */
+export type ChatTurn = {
+    /** @purpose Unique turn identifier */
+    id: string;
+    /** @purpose ISO timestamp the turn completed (or was stopped) */
+    ts: string;
+    /** @purpose Operator's question text for this turn */
+    question: string;
+    /** @purpose Context chips attached to this turn */
+    chips: ContextChip[];
+    /** @purpose Assistant's answer — full text, or streamed-so-far text when stopped */
+    answer: string;
+    /** @purpose Structural mutations proposed by the assistant, if any (D-90) */
+    mutations?: MutationProposal[];
+    /** @purpose `review.json` revision at the moment of this turn — CAS input for `MutationApplier` (D-99) */
+    reviewRevision: number;
+    /** @purpose True when the operator invoked `stop()` before the turn completed (D-95/CH-11) */
+    stopped?: boolean;
+};
+/** @purpose Snapshot of `review.json` immediately before a mutation is applied — undo material (D-94). */
+export type ReviewSnapshot = {
+    /** @purpose Unique snapshot identifier */
+    id: string;
+    /** @purpose MR reference (`project!iid`) the snapshot belongs to */
+    mrRef: string;
+    /** @purpose ISO timestamp the snapshot was taken */
+    ts: string;
+    /** @purpose `review.json` revision captured by this snapshot */
+    revision: number;
+    /** @purpose Absolute path to the snapshot file under `reports/<mr>/snapshots/` */
+    path: string;
+};

package/dist/services/agent-inbox/modules/inbox-core/adapters/controlled-clock.d.ts

@@ -0,0 +1,45 @@
+import type { ClockPort } from '../ports/clock.port.js';
+type ScheduledCallback = {
+    at: number;
+    order: number;
+    cancelled: boolean;
+    callback: () => void;
+};
+/**
+ * @purpose Execute timer policy deterministically without sleeps or global fake timers.
+ * @implements {ClockPort} in ../ports/clock.port.ts
+ * @invariant Due callbacks execute by instant then registration order.
+ */
+export declare class ControlledClock implements ClockPort {
+    /** @see {ClockPort#identity} in ../ports/clock.port.ts */
+    readonly identity = "controlled-clock";
+    /** @see {ClockPort#health} in ../ports/clock.port.ts */
+    health(): {
+        status: 'healthy';
+    };
+    /** @purpose Current controlled epoch milliseconds. */
+    protected _now: number;
+    /** @purpose Registration sequence preserving stable same-time callback order. */
+    protected _order: number;
+    /** @purpose Pending callbacks not yet cancelled or executed. */
+    protected _scheduled: ScheduledCallback[];
+    /**
+     * @purpose Start a controlled clock at an explicit ISO instant.
+     * @param initialNow Initial current time.
+     * @throws {Error} When the initial instant is invalid.
+     */
+    constructor(initialNow: string);
+    /** @see {ClockPort#now} in ../ports/clock.port.ts */
+    now(): string;
+    /** @see {ClockPort#schedule} in ../ports/clock.port.ts */
+    schedule(at: string, callback: () => void): {
+        cancel(): void;
+    };
+    /**
+     * @purpose Advance to an absolute instant and run every newly due callback deterministically.
+     * @param at New current instant, never earlier than current time.
+     * @throws {Error} On invalid time or clock regression.
+     */
+    advanceTo(at: string): void;
+}
+export {};

package/dist/services/agent-inbox/modules/inbox-core/adapters/in-memory-artifact-store.d.ts

@@ -0,0 +1,27 @@
+import type { ArtifactStorePort } from '../ports/artifact-store.port.js';
+/**
+ * @purpose Retain exact artifact bytes in isolated deterministic test memory.
+ * @implements {ArtifactStorePort} in ../ports/artifact-store.port.ts
+ */
+export declare class InMemoryArtifactStore implements ArtifactStorePort {
+    /** @see {ArtifactStorePort#identity} in ../ports/artifact-store.port.ts */
+    readonly identity = "in-memory-artifact-store";
+    /** @see {ArtifactStorePort#health} in ../ports/artifact-store.port.ts */
+    health(): {
+        status: 'healthy';
+    };
+    /** @purpose Isolated MR-and-id keyed artifact byte copies. */
+    protected _artifacts: Map<string, Uint8Array<ArrayBufferLike>>;
+    /** @see {ArtifactStorePort#put} in ../ports/artifact-store.port.ts */
+    put(address: {
+        mr: string;
+        id: string;
+    }, content: Uint8Array): Promise<void>;
+    /** @see {ArtifactStorePort#read} in ../ports/artifact-store.port.ts */
+    read(address: {
+        mr: string;
+        id: string;
+    }): Promise<Uint8Array>;
+    /** @see {ArtifactStorePort#list} in ../ports/artifact-store.port.ts */
+    list(mr: string): Promise<string[]>;
+}

package/dist/services/agent-inbox/modules/inbox-core/adapters/in-memory-journal.d.ts

@@ -0,0 +1,29 @@
+import type { JournalEntry, JournalPort, SinceResult } from '../event-journal.js';
+import { ReviewEvent } from '../types/review-event.type.js';
+/**
+ * @purpose Preserve journal append/replay behavior in isolated deterministic memory.
+ * @implements {JournalPort} in ../event-journal.ts
+ * @invariant Returned entries/events are copies and cannot mutate acknowledged journal state.
+ */
+export declare class InMemoryJournal implements JournalPort {
+    /** @see {JournalPort#identity} in ../event-journal.ts */
+    readonly identity = "in-memory-journal";
+    /** @see {JournalPort#health} in ../event-journal.ts */
+    health(): {
+        status: 'healthy';
+    };
+    /** @purpose Legacy journal entries retained for compatibility consumers. */
+    protected _entries: JournalEntry[];
+    /** @purpose Canonical validated review events retained for deterministic replay. */
+    protected _reviewEvents: ReviewEvent[];
+    /** @see {JournalPort#append} in ../event-journal.ts */
+    append(entry: Omit<JournalEntry, 'seq'>): Promise<number>;
+    /** @see {JournalPort#read} in ../event-journal.ts */
+    read(): JournalEntry[];
+    /** @see {JournalPort#since} in ../event-journal.ts */
+    since(cursor: number): SinceResult;
+    /** @see {JournalPort#appendReviewEvent} in ../event-journal.ts */
+    appendReviewEvent(event: ReviewEvent): Promise<number>;
+    /** @see {JournalPort#replayReviewEvents} in ../event-journal.ts */
+    replayReviewEvents(): ReviewEvent[];
+}

package/dist/services/agent-inbox/modules/inbox-core/adapters/local-artifact-store.d.ts

@@ -0,0 +1,36 @@
+import type { ArtifactStorePort } from '../ports/artifact-store.port.js';
+/**
+ * @purpose Store review artifact bytes atomically under a validated runtime state root.
+ * @implements {ArtifactStorePort} in ../ports/artifact-store.port.ts
+ * @invariant Failed write/fsync/rename is logged and never acknowledged.
+ */
+export declare class LocalArtifactStore implements ArtifactStorePort {
+    /** @see {ArtifactStorePort#identity} in ../ports/artifact-store.port.ts */
+    readonly identity = "local-artifact-store";
+    /** @purpose Profile-owned artifact root beneath the validated state namespace. */
+    protected readonly _root: string;
+    /** @purpose Latest adapter failure exposed through the health surface. */
+    protected _healthFailure: string | null;
+    /** @see {ArtifactStorePort#health} in ../ports/artifact-store.port.ts */
+    health(): {
+        status: 'healthy' | 'failed';
+        detail?: string;
+    };
+    /**
+     * @purpose Bind artifacts to the already validated StateStore runtime root.
+     * @param stateRoot Validated StateStore runtime root.
+     */
+    constructor(stateRoot: string);
+    /** @see {ArtifactStorePort#put} in ../ports/artifact-store.port.ts */
+    put(address: {
+        mr: string;
+        id: string;
+    }, content: Uint8Array): Promise<void>;
+    /** @see {ArtifactStorePort#read} in ../ports/artifact-store.port.ts */
+    read(address: {
+        mr: string;
+        id: string;
+    }): Promise<Uint8Array>;
+    /** @see {ArtifactStorePort#list} in ../ports/artifact-store.port.ts */
+    list(mr: string): Promise<string[]>;
+}

package/dist/services/agent-inbox/modules/inbox-core/adapters/system-clock.d.ts

@@ -0,0 +1,22 @@
+import type { ClockPort } from '../ports/clock.port.js';
+/**
+ * @purpose Bind canonical review timers to the Node.js wall clock.
+ * @implements {ClockPort} in ../ports/clock.port.ts
+ */
+export declare class SystemClock implements ClockPort {
+    /** @see {ClockPort#identity} in ../ports/clock.port.ts */
+    readonly identity = "system-clock";
+    /** @purpose Latest invalid scheduling request exposed to runtime diagnostics. */
+    protected _healthFailure: string | null;
+    /** @see {ClockPort#health} in ../ports/clock.port.ts */
+    health(): {
+        status: 'healthy' | 'failed';
+        detail?: string;
+    };
+    /** @see {ClockPort#now} in ../ports/clock.port.ts */
+    now(): string;
+    /** @see {ClockPort#schedule} in ../ports/clock.port.ts */
+    schedule(at: string, callback: () => void): {
+        cancel(): void;
+    };
+}

package/dist/services/agent-inbox/modules/inbox-core/audit-log.d.ts

@@ -0,0 +1,64 @@
+/** @purpose Single audit event entry written to audit.jsonl. */
+export type AuditEntry = {
+    /** @purpose ISO timestamp of the event */
+    ts: string;
+    /** @purpose MR web URL this event relates to */
+    mr: string;
+    /** @purpose Role active at the time of the event */
+    role: string;
+    /** @purpose Event name (e.g. 'classified', 'posted', 'approved', 'escalated') */
+    event: string;
+    /** @purpose Free-form detail (e.g. stage transition, permission change) */
+    detail?: string;
+};
+/**
+ * @purpose Append-only JSON Lines audit log for serve-mode events.
+ * @invariant Append-only: existing entries are never modified or deleted.
+ * @invariant Rotation: when audit.jsonl exceeds 10 MB, it is renamed to audit.<N>.jsonl.
+ * @invariant Rotation strategy: find lowest unused N starting from 1.
+ */
+export declare class AuditLog {
+    /** @purpose Root state directory path. */
+    protected _stateDir: string;
+    /** @purpose Base path for audit log files. */
+    protected _basePath: string;
+    /** @purpose Lock to serialize append operations. */
+    protected _lock: Promise<void>;
+    /**
+     * @purpose Create an AuditLog instance bound to a state directory.
+     * @param [stateDir] Root state directory (defaults to ~/.gennady).
+     */
+    constructor(stateDir?: string);
+    /**
+     * @purpose Path to the current active audit log file.
+     * @returns Full path to audit.jsonl.
+     */
+    get logPath(): string;
+    /**
+     * @purpose Append a single event as a JSON line to the audit log.
+     * @invariant Rotation is checked before each append; if the file exceeds 10 MB, it is rotated first.
+     * @param entry Event to append (ts, mr, role, event, detail).
+     * @returns Promise that resolves when the entry is written.
+     * @sideEffect Writes one JSON line to the audit log file; may trigger rotation.
+     */
+    append(entry: AuditEntry): Promise<void>;
+    /**
+     * @purpose Query all audit events for a specific MR.
+     * @param mr MR web URL to filter by.
+     * @returns Array of audit entries for the given MR, oldest first.
+     * @sideEffect Reads the current audit log file and all rotated files.
+     */
+    query(mr: string): Promise<AuditEntry[]>;
+    /**
+     * @purpose Rotate the audit log: rename audit.jsonl to audit.<N>.jsonl where N is the lowest unused number.
+     * @returns Promise that resolves when rotation is complete.
+     * @sideEffect File rename on disk.
+     */
+    rotate(): Promise<void>;
+    /**
+     * @purpose Check if the current log file exceeds the rotation threshold and rotate if so.
+     * @returns Promise that resolves when the check completes.
+     * @sideEffect May trigger file rename.
+     */
+    rotateIfNeeded(): Promise<void>;
+}

package/dist/services/agent-inbox/modules/inbox-core/boot-readiness.d.ts

@@ -0,0 +1,106 @@
+/** @purpose Ordered boot phases — the server progresses through these in sequence (D-305). */
+export type BootPhase = 'connect' | 'poll' | 'reconcile' | 'restore' | 'ready' | 'failed';
+/** @purpose Progress descriptor for the current boot phase. */
+export type BootProgress = {
+    /** @purpose Completed phases count */
+    done: number;
+    /** @purpose Total phases in the sequence */
+    total: number;
+    /** @purpose Human-readable label for the current phase */
+    label: string;
+};
+/** @purpose Observable lazy preparation state for one MR content worktree. */
+export type WorktreePreparationState = 'deferred' | 'preparing' | 'ready' | 'failed';
+/** @purpose Full boot state snapshot exposed via /api/boot (D-305). */
+export type BootState = {
+    /** @purpose Current phase identifier */
+    phase: BootPhase;
+    /** @purpose Monotonic progress descriptor */
+    progress: BootProgress;
+    /** @purpose Whether the boot sequence completed successfully */
+    ready: boolean;
+    /** @purpose Failure reason when phase='failed' */
+    error?: string;
+    /** @purpose Whether config was loaded successfully */
+    configured: boolean;
+    /** @purpose Missing config keys when configured=false */
+    missing: string[];
+    /** @purpose Per-content-key lazy worktree state; absent keys remain deferred and uncreated. */
+    worktrees: Record<string, WorktreePreparationState>;
+};
+/** @purpose Callback invoked on every boot state transition — registered before connect. */
+export type BootTransitionListener = (state: BootState) => void;
+/**
+ * @purpose Boot-phase state machine: observable phase progression with /api/boot contract.
+ * @invariant Phase transitions are monotonic — never regress.
+ * @invariant Snapshot available immediately — listeners fire on every transition.
+ * @invariant Config status settable independently via setConfigStatus.
+ */
+export declare class BootReadiness {
+    /** @purpose Current boot phase. */
+    protected _phase: BootPhase;
+    /** @purpose Progress descriptor. */
+    protected _progress: BootProgress;
+    /** @purpose Whether boot completed. */
+    protected _ready: boolean;
+    /** @purpose Failure reason when failed. */
+    protected _error: string | undefined;
+    /** @purpose Config load status. */
+    protected _configured: boolean;
+    /** @purpose Missing config keys. */
+    protected _missing: string[];
+    /** @purpose Registered transition listeners. */
+    protected _listeners: BootTransitionListener[];
+    /** @purpose Observable states only for content worktrees that crossed the lazy barrier. */
+    protected _worktrees: Map<string, WorktreePreparationState>;
+    /** @purpose Single-flight preparation promises keyed by content identity. */
+    protected _worktreePreparations: Map<string, Promise<unknown>>;
+    /**
+     * @purpose Create a BootReadiness instance — snapshot available immediately, before connect.
+     */
+    constructor();
+    /**
+     * @purpose Take a snapshot of the current boot state — available before any phase begins.
+     * @returns Immutable-style copy of the current boot state.
+     */
+    snapshot(): BootState;
+    /**
+     * @purpose Run the first content worktree preparation only after boot reaches read-ready state.
+     * @invariant No worktree is created by boot phases; concurrent/repeated calls for one key share one preparation.
+     * @param key Stable MR/content identity shown in the observable worktree state map.
+     * @param prepare Actual content task that materializes or reuses the worktree.
+     * @throws {Error} Before ready or when preparation fails.
+     * @returns The first successful preparation result for this key.
+     * @sideEffect Runs caller-supplied filesystem/network preparation at most once after ready.
+     */
+    prepareWorktreeOnce<T>(key: string, prepare: () => Promise<T>): Promise<T>;
+    /**
+     * @purpose Transition to a new boot phase, advancing progress monotonically.
+     * @param phase Target phase — must be next in sequence or 'failed'/'ready'.
+     * @param [progressOverride] Optional partial progress override for the new phase.
+     * @throws {Error} When phase regression is attempted.
+     * @sideEffect Fires all registered listeners with the new state.
+     */
+    transition(phase: BootPhase, progressOverride?: Partial<BootProgress>): void;
+    /**
+     * @purpose Record a boot failure with reason — transitions to 'failed' phase.
+     * @param error Human-readable failure reason.
+     * @sideEffect Fires all registered listeners with the failed state.
+     */
+    fail(error: string): void;
+    /**
+     * @purpose Update config load status independently of phase transitions.
+     * @param configured Whether config loaded successfully.
+     * @param [missing] Missing config keys when configured=false.
+     */
+    setConfigStatus(configured: boolean, missing?: string[]): void;
+    /**
+     * @purpose Register a transition listener — callable before any phase begins.
+     * @param listener Callback invoked on every state transition.
+     */
+    onTransition(listener: BootTransitionListener): void;
+    /**
+     * @purpose Notify all registered listeners of the current state.
+     */
+    protected _notifyListeners(): void;
+}

package/dist/services/agent-inbox/modules/inbox-core/capability-modes.d.ts

@@ -0,0 +1,33 @@
+import { type AcceptRate, type Capability } from './decision-journal.js';
+/** @purpose Granularity mode — proposal (operator decides) or auto (machine acts) (D-302). */
+export type CapabilityMode = 'proposal' | 'auto';
+/** @purpose Per-capability mode registry — keyed by capability name. */
+export type CapabilityRegistry = Record<Capability, CapabilityMode>;
+/** @purpose Configuration for the capability graduation threshold (D-302 / §2.1). */
+export type GraduationConfig = {
+    /** @purpose Minimum accept rate to flip to auto | @invariant 0..1 */
+    threshold: number;
+    /** @purpose Minimum sample size before graduation is permitted */
+    minSampleSize: number;
+};
+/**
+ * @purpose Stateless graduation engine: evaluates accept-rate metrics and produces a CapabilityRegistry.
+ * @invariant Graduation is table-driven — thresholds in GraduationConfig, not hardcoded.
+ * @invariant n < minSampleSize → always 'proposal' regardless of rate.
+ */
+export declare class CapabilityModes {
+    /**
+     * @purpose Determine the mode for a single capability given its accept-rate metrics.
+     * @param acceptRate Computed accept-rate for the capability.
+     * @param [config] Graduation configuration (defaults to 90%/20).
+     * @returns 'auto' when the capability meets the graduation threshold; 'proposal' otherwise.
+     */
+    static evaluateGraduation(acceptRate: AcceptRate, config?: GraduationConfig): CapabilityMode;
+    /**
+     * @purpose Build a full capability registry from a set of accept-rate metrics.
+     * @param rates Accept-rate entries (one per capability).
+     * @param [config] Graduation configuration.
+     * @returns Registry mapping each capability to its computed mode.
+     */
+    static computeRegistry(rates: AcceptRate[], config?: GraduationConfig): CapabilityRegistry;
+}