@quantiya/codevibe-codex-plugin 2.0.6 → 2.0.8

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/context-items.d.ts

@@ -0,0 +1,408 @@
+import { loadContextStore, resolveContextRef, probeWorkspaceGitHead } from './context-store';
+import type { StructuralSummaryGenerator, RepoSummary } from '../structural-summary/types';
+import type { Tier } from './types';
+/** AppSync's pinned blind-hold ciphertext ceiling (ASCII base64 characters). */
+export declare const CONTEXT_ITEM_WIRE_CIPHERTEXT_MAX_CHARS = 350000;
+/**
+ * The PINNED UUIDv5 namespace mapping a `session_id` to its session-root
+ * pseudo-task ID on the task-partitioned `AuditTable` (design §4.1 Finding 1).
+ *
+ * ⚠️ WIRE CONTRACT — DO NOT CHANGE. This literal is pinned in the design
+ * (SHARED-CONTEXT-ARCHITECTURE-DESIGN.md §4.1) and MUST stay byte-identical
+ * to the Rust side (`codevibe-audit::CONTEXT_SESSION_PSEUDO_TASK_NAMESPACE`,
+ * lib.rs) — the Rust audit writer and the TS deletion worker (tracker [D2])
+ * derive pseudo-task partition keys from it, and a divergence would make D2
+ * delete the WRONG partition and silently retain session-scoped audit rows.
+ * The Rust↔TS parity test (context-items.test.ts + codevibe-audit lib.rs
+ * tests) pins shared `session_id → pseudo_task_id` vectors on both sides.
+ *
+ * Importable by D2's deletion worker as the single TS source of truth.
+ */
+export declare const CONTEXT_SESSION_PSEUDO_TASK_NAMESPACE = "cefd405a-b1ac-4e63-8e9e-d328f3d95182";
+/**
+ * §4.1 Finding 1 — the deterministic UUIDv5 session-root pseudo-task ID for
+ * session-scoped ContextItems (`Uuid::new_v5(&NAMESPACE, session_id.as_bytes())`
+ * on the Rust side). NEVER a `session_<id>` string — the Rust audit crate
+ * types `task_id` as a plain `Uuid` (`codevibe-audit/src/lib.rs`) and a
+ * non-UUID string would fail serde deserialization on any engine read.
+ */
+export declare function deriveSessionPseudoTaskId(sessionId: string): string;
+/**
+ * The AuditTable partition a ContextItem's blind-held row lands in (the
+ * "strict superset of ROWS + KINDS" co-location, design §4.1/§4.2): a task-
+ * scoped item partitions under its real `task_id`; a session-scoped item
+ * partitions under the deterministic session pseudo-task ID.
+ */
+export declare function auditPartitionTaskIdFor(item: Pick<ContextItem, 'session_id' | 'task_id'>): string;
+/** The full §4 kind set (the one-time corpus-ready vocabulary, §4.1). */
+export type ContextItemKind = 'turn' | 'decision' | 'task_spec' | 'verdict' | 'artifact_ref' | 'open_question' | 'rationale' | 'repo_state';
+export type ContextItemAuthorRole = 'human' | 'agent' | 'conductor' | 'engine';
+/** §4 `author` — emitter-assigned attribution (drives the group-conversation UX). */
+export interface ContextItemAuthor {
+    role: ContextItemAuthorRole;
+    /** e.g. 'claude' | 'codex' | 'gemini' | 'agy' — set when role='agent'. */
+    agent_id?: string;
+}
+/** §4 — an ORDERED floor (public < user < secret). Emitter-assigned. */
+export type ContextItemSensitivity = 'public' | 'user' | 'secret';
+/**
+ * §4 `visible_to` — the distinct projection-consumer roles. 'planner' = the
+ * local 12B conductor; 'brainstorm' = the frontier brainstorm panel (§8.2).
+ * The hosted 'engine' is NOT a role (it owns the authoritative log).
+ */
+export type ContextItemProjectionRole = 'implementor' | 'reviewer' | 'resolver' | 'planner' | 'brainstorm';
+/** §4.3 — validity/staleness dimensions. */
+export interface ContextItemValidity {
+    supersededBy?: string;
+    invalidatedByMerge?: string;
+}
+/**
+ * §4 — one typed, addressable fact in the canonical store. `session_id`/`seq`
+ * are the (hosted) storage keys; everything else is content that rides INSIDE
+ * the encrypted envelope on the wire (§4.2 plaintext boundary).
+ */
+export interface ContextItem {
+    session_id: string;
+    /** Monotonic per-session ULID — append order + the prev_hash chain (§4.1a). */
+    seq: string;
+    /** Content-addressed hash — dedup + the target of refs[] (NOT the sort key). */
+    id: string;
+    /** Set on task- AND track-scoped items (§4 hierarchy). */
+    task_id?: string;
+    /** Set ONLY on track-scoped items (⟹ task_id is also set). */
+    track_id?: string;
+    kind: ContextItemKind;
+    author: ContextItemAuthor;
+    sensitivity: ContextItemSensitivity;
+    visible_to: ContextItemProjectionRole[];
+    validity: ContextItemValidity;
+    refs: string[];
+    /** Hex SHA-256 of the serialized previous item. `null` for the first item. */
+    prev_hash: string | null;
+    /** Typed payload per kind. */
+    body: unknown;
+    /** ISO timestamp the item was authored (corpus-ready, §4.1). */
+    authored_at: string;
+}
+/** What a deterministic emitter passes to `appendContextItem`. */
+export interface ContextItemDraft {
+    kind: ContextItemKind;
+    author: ContextItemAuthor;
+    sensitivity: ContextItemSensitivity;
+    visible_to: ContextItemProjectionRole[];
+    body: unknown;
+    task_id?: string;
+    track_id?: string;
+    refs?: string[];
+    validity?: ContextItemValidity;
+}
+export interface ContextItemOccurrence {
+    seq: string;
+    itemId: string;
+    serializedItemSha256: string;
+}
+export type ContextDurabilityReceipt = {
+    durable: true;
+    coveredOccurrences: ContextItemOccurrence[];
+    durableTailHash: string;
+} | {
+    durable: false;
+    reason: 'wedged' | 'stage_failed' | 'commit_failed' | 'rollback_failed' | 'readback_failed' | 'item_missing' | 'content_mismatch';
+};
+export type CanonicalAgentTurnDraft = ContextItemDraft & {
+    kind: 'turn';
+    author: ContextItemAuthor & {
+        role: 'agent';
+        agent_id: string;
+    };
+};
+export declare function contextItemOccurrence(item: ContextItem): ContextItemOccurrence;
+/**
+ * §4.1a / tracker [A1e] — the writer-populated, session-synced TTL for the
+ * hosted `ContextItemsTable` rows (the SAME 7-day epoch the events table
+ * already exposes; the bounded non-semantic `expiresAt` exception, §4.2).
+ */
+export declare const CONTEXT_ITEM_TTL_SECONDS: number;
+/**
+ * Create one ContextItems session directory durably. `mkdir -p` alone can
+ * leave a visible-but-not-crash-durable directory chain; fsync each parent
+ * entry from `~/.codevibe` through the per-session directory. Repeating this
+ * after a failed parent sync repairs the visible chain before hosted upload.
+ */
+export declare function ensureContextItemsSessionDirectoryDurable(sessionId: string, beforeParentFsync?: (parent: string, child: string) => Promise<void>): Promise<void>;
+/** Exported for the A1f retention sweep (`gcContextItemLogs`). */
+export declare function contextItemsRootDir(): string;
+/** Exported for tests + diagnostics. */
+export declare function contextItemsLogPath(sessionId: string): string;
+/**
+ * §4.1 Finding 2 — transient = high-frequency intermediate `turn`/`rationale`
+ * items authored by an agent/conductor/engine. Human turns (user prompts),
+ * decisions, task_specs, verdicts, artifact_refs, open_questions, and
+ * repo_state are DURABLE (synchronous fsync-per-write).
+ */
+export declare function isTransientContextItem(kind: ContextItemKind, author: ContextItemAuthor): boolean;
+/**
+ * Post-fsync notification used by the hosted upload coordinator. The hook is
+ * deliberately synchronous + best-effort: the local authenticated log remains
+ * the write authority, while the hook only wakes a separate durable-outbox
+ * drain after bytes are safely on disk.
+ */
+type ContextItemsPersistedHook = (items: readonly ContextItem[]) => void;
+export declare function setContextItemsPersistedHook(sessionId: string, hook: ContextItemsPersistedHook | null): void;
+/** Vitest-gated setter for {@link testFaultInjection}; `null` disarms. */
+export declare function setContextItemsFaultInjectionForTests(faults: {
+    failWrite?: boolean;
+    failTruncate?: boolean;
+    beforeFsync?: () => Promise<void>;
+    failRollbackSync?: boolean;
+    corruptAgentTurnReadback?: boolean;
+    crashAfterAgentTurnAppend?: boolean;
+    crashAfterAgentTurnCommit?: boolean;
+    failAgentTurnJournalCleanup?: boolean;
+    failAgentTurnCleanupDirectoryOpen?: boolean;
+    failAgentTurnCleanupDirectorySync?: boolean;
+    failAgentTurnCleanupDirectorySyncAtCall?: number;
+    failCanonicalLogDirectorySync?: boolean;
+} | null): void;
+export declare function getContextItemLog(sessionId: string): {
+    append: (draft: ContextItemDraft) => Promise<ContextItem | null>;
+    flush: () => Promise<void>;
+    readDurableSnapshot: () => Promise<string | null>;
+    commitAndVerifyAgentTurnBatch: (humanOccurrence: ContextItemOccurrence, drafts: CanonicalAgentTurnDraft[]) => Promise<ContextDurabilityReceipt>;
+};
+/**
+ * Append one typed item to the session's canonical log (the deterministic-
+ * emitter write path). Convenience over `getContextItemLog`.
+ */
+export declare function appendContextItem(sessionId: string, draft: ContextItemDraft): Promise<ContextItem | null>;
+/** Finding 2 — flush a session's transient buffer at a natural boundary. */
+export declare function flushContextItems(sessionId: string): Promise<void>;
+export declare function commitAndVerifyAgentTurnBatch(sessionId: string, humanOccurrence: ContextItemOccurrence, successfulDrafts: CanonicalAgentTurnDraft[]): Promise<ContextDurabilityReceipt>;
+/**
+ * Test seam — clear the per-process writer registry (vitest-gated, the
+ * CODEVIBE_HOME_OVERRIDE pattern).
+ */
+export declare function resetContextItemsProcessStateForTests(): void;
+export interface ReadContextItemsResult {
+    items: ContextItem[];
+    /** True when every on-disk line unsealed + parsed as a sealed envelope. */
+    complete: boolean;
+}
+/**
+ * Read a session's items (tolerant: an unreadable line is skipped and
+ * `complete:false` reported — reads never throw). Stage-2 R1 F3: ONLY sealed
+ * (`csEnc`) envelope lines are accepted — there is NO legacy plaintext
+ * ContextItem format, so a plaintext line (which any local process WITHOUT
+ * the device key could craft) is an integrity failure, never parsed into
+ * items. For strict integrity use `verifyContextItemChain` /
+ * `readVerifiedContextItems`.
+ */
+export declare function readContextItems(sessionId: string): Promise<ReadContextItemsResult>;
+export interface ChainVerificationResult {
+    ok: boolean;
+    length: number;
+    /** 0-based index of the first broken line (when !ok). */
+    brokenAt?: number;
+    reason?: 'read-error' | 'unreadable-line' | 'plaintext-line' | 'malformed-item' | 'prev-hash-mismatch' | 'seq-not-monotonic' | 'session-id-mismatch' | 'content-address-mismatch';
+}
+/** `ChainVerificationResult` + the parsed items when (and only when) `ok`. */
+export interface VerifiedContextItemsResult extends ChainVerificationResult {
+    /** The full parsed chain — EMPTY unless `ok === true` (fail-closed). */
+    items: ContextItem[];
+}
+export declare function readVerifiedContextItems(sessionId: string): Promise<VerifiedContextItemsResult>;
+/**
+ * §4.2 chain authority (a) — the ON-DEVICE `verify_chain` over decrypted
+ * content. Thin wrapper over `readVerifiedContextItems` (one verification
+ * source of truth); see it for the enforced contract.
+ */
+export declare function verifyContextItemChain(sessionId: string): Promise<ChainVerificationResult>;
+/**
+ * The EXACT hosted `ContextItemsTable` row shape (design §4.1a/§4.2 + tracker
+ * [A1e]): plaintext = the opaque routing keys (`session_id` PK, `seq` SK,
+ * `task_id?`/`track_id?`) + the bounded non-semantic `expiresAt` TTL —
+ * NOTHING else. The full item (incl. `id`/`prev_hash`/`refs`/`kind`/labels/
+ * `body`) rides inside `ciphertext`, E2E-encrypted with the SESSION key
+ * (engine-opaque, exactly as briefs are today). Do NOT add attributes here:
+ * any new plaintext attribute fails the §4.2 boundary by default.
+ */
+export interface ContextItemWireRow {
+    session_id: string;
+    seq: string;
+    task_id?: string;
+    track_id?: string;
+    /**
+     * Epoch seconds copied from the authoritative Session row by AppSync. It is
+     * absent while the session has no retention deadline (normally ACTIVE) and
+     * set/updated when the session becomes INACTIVE. The desktop never chooses
+     * this value.
+     */
+    expiresAt?: number;
+    /** Base64 AES-256-GCM (nonce+ct+tag) over the full serialized item. */
+    ciphertext: string;
+}
+/**
+ * Build the client-authored portion of one blind-held hosted row. AppSync adds
+ * the session-synchronized `expiresAt` from its strongly-read Session row;
+ * accepting a desktop-provided deadline would let a stale/offline client
+ * extend retention. The upload mutation consumes the remaining fields
+ * verbatim and stores no additional semantic plaintext.
+ */
+export declare function buildContextItemWireRow(item: ContextItem, sessionKeyBase64: string): ContextItemWireRow;
+/** Decrypt a blind-held row back to the typed item (desktop-side only). */
+export declare function decryptContextItemWireRow(row: Pick<ContextItemWireRow, 'ciphertext'>, sessionKeyBase64: string): ContextItem;
+/**
+ * A1f Stage-1 R1 HIGH — the SINGLE floor predicate over emitter-assigned
+ * labels, shared by the hot-item filter (`projectItemsForRole`) AND the
+ * distilled-fact filter (context-compaction.ts) so the two halves of a
+ * rehydrated view can NEVER drift: a role R at clearance C may see a label
+ * iff `R ∈ visible_to` AND `sensitivity ≤ C`. FAIL-CLOSED on an unknown
+ * sensitivity value (the exhaustive-allowlist discipline).
+ */
+export declare function labelPermitsRole(label: {
+    sensitivity: ContextItemSensitivity;
+    visible_to: readonly ContextItemProjectionRole[];
+}, role: ContextItemProjectionRole, clearance: ContextItemSensitivity): boolean;
+/**
+ * §5 stage-1 static classification — the FLOOR. A projection for role R may
+ * only include items where `R ∈ visible_to` AND `sensitivity ≤ clearance`,
+ * excluding superseded/merge-invalidated items (§4.3). FAIL-CLOSED: an item
+ * with an unknown sensitivity value (a future schema widening this build
+ * does not know) is EXCLUDED — the exhaustive-allowlist discipline.
+ *
+ * This helper only SELECTS among already-labeled items; labels are assigned
+ * by the deterministic emitter at write time (§4.2) — never here, never by
+ * the conductor.
+ */
+export declare function projectItemsForRole(items: readonly ContextItem[], role: ContextItemProjectionRole, clearance: ContextItemSensitivity): ContextItem[];
+/** The typed body of a `repo_state` ContextItem (one canonical schema, §4.3). */
+export interface RepoStateBody {
+    workspaceId: string;
+    /** The frontier agent's codebase overview (sanitized upstream). */
+    summary: string;
+    /** The workspace git HEAD recorded AT READ TIME (§8.3 freshness). */
+    gitHead?: string;
+    producedAt: string;
+}
+export type RepoStateProjection = {
+    status: 'fresh';
+    summary: string;
+    author: ContextItemAuthor | {
+        role: 'agent';
+        agent_id: string;
+    };
+    producedAt: string;
+} | {
+    status: 'stale' | 'missing';
+};
+/**
+ * Stage-2 R1 F5 — for a NON-git workspace (`probeWorkspaceGitHead` →
+ * `{kind:'non-git'}`, a DETERMINISTIC classification per Stage-2 R2 G3) a
+ * head-less record can never be head-proven fresh; without this bound the
+ * overview would never project AND every dispatch would fire a pointless
+ * re-delegation forever. Instead: fresh while the record is younger than
+ * this generous bound (24h); beyond it → stale (project nothing) — but
+ * re-delegation is NEVER fired for a non-git workspace (there is no HEAD
+ * signal a re-read could improve on). G3: this allowance applies ONLY to
+ * the deterministic `non-git` bucket — a `probe-failed` (transient git
+ * error, unborn HEAD) never borrows it.
+ */
+export declare const NON_GIT_REPO_STATE_MAX_AGE_MS: number;
+/**
+ * §8.3 / A1e Finding 5 — project the workspace's `repo_state` for a dispatch.
+ *
+ *  - Stage-2 R1 F4 — the typed log is consumed through the VERIFIED read
+ *    path: on ANY chain-integrity failure this projects NOTHING (`missing`,
+ *    once-warn, NO legacy fallback and NO re-delegation) — a forked /
+ *    tampered / wrong-session log never supplies prompt content.
+ *  - Latest live (non-superseded) `repo_state` item for this workspace from
+ *    the verified log; falls back to the legacy A1a `repo-state.json`
+ *    record only when the (verified) typed log has none (migration path).
+ *  - The workspace git HEAD is probed NOW (Stage-2 R2 G3 — a DISCRIMINATED
+ *    probe): with a resolvable HEAD (`kind:'head'`), a record whose
+ *    `gitHead` is missing OR differs is STALE: `onStaleRedelegate` is fired
+ *    (background re-delegation — fire-and-forget) and the stale summary is
+ *    NEVER returned.
+ *  - Stage-2 R1 F5 — in a DETERMINISTICALLY non-git workspace
+ *    (`kind:'non-git'`) a head-less record is FRESH within
+ *    `NON_GIT_REPO_STATE_MAX_AGE_MS` (there is no HEAD to prove staleness
+ *    against), stale beyond it, and re-delegation NEVER fires. Stage-1 R3
+ *    LOW-2 — the age gate fails CLOSED: an unparseable or future-dated
+ *    `producedAt` is STALE, never fresh-forever. A git repo whose record
+ *    lacks `gitHead` (legacy) stays STALE as before.
+ *  - Stage-2 R2 G3 — a PROBE FAILURE (`kind:'probe-failed'`: transient git
+ *    error, git missing, unborn HEAD) proves nothing and borrows NOTHING:
+ *    never fresh (no F5 allowance) and NO re-delegation (a re-read under a
+ *    failing probe records no head → a permanent loop) — stale, no-fire.
+ */
+export declare function projectRepoStateForDispatch(deps: {
+    sessionId: string;
+    workspaceId: string;
+    workspaceRoot: string;
+    /** Fired (once) when a stale/unproven record is found — the background re-delegation hook. */
+    onStaleRedelegate?: () => void;
+    /** Test seam — defaults to the real git probe. */
+    probeGitHeadFn?: typeof probeWorkspaceGitHead;
+}): Promise<RepoStateProjection>;
+/**
+ * The deterministic-emitter write path for a freshly-delegated codebase
+ * overview: appends a DURABLE `repo_state` item (attributed per §4 `author`,
+ * broadly visible per the §5 projection table, `user` sensitivity).
+ */
+export declare function appendRepoStateItem(deps: {
+    sessionId: string;
+    workspaceId: string;
+    summary: string;
+    /** The LE AgentKind that authored the read (e.g. 'CLAUDE'). */
+    agentId: string;
+    gitHead?: string;
+    producedAt?: string;
+}): Promise<ContextItem | null>;
+/**
+ * Byte budget for the composed dispatch-context block (fail-closed
+ * truncation) — matches the workflow-handoff total budget so one dispatch
+ * never carries an unbounded repo dump (§5 stage-2 bounded relevance).
+ * Stage-2 R1 F6 — this is a HARD cap on the TOTAL returned string, wrapper
+ * and truncation marker INCLUDED (both are reserved inside the budget).
+ */
+export declare const DISPATCH_CONTEXT_MAX_CHARS = 4800;
+/**
+ * Compose the bounded repository-context block appended to an implementor /
+ * decomposer prompt at dispatch (the A1e REMAP: `mintContextRef` →
+ * `resolveContextRef` → `sliceSummary` finally have a production caller, and
+ * the `repo_state` overview is projected FRESH-ONLY per §8.3).
+ *
+ * Returns `''` when nothing is projectable (missing store, stale repo_state,
+ * resolve failure) — callers append verbatim, so empty = no block. Never
+ * throws: a projection failure degrades to the un-augmented prompt (the
+ * pre-A1e behavior), never a blocked dispatch.
+ */
+export declare function composeDispatchContextBlock(deps: {
+    sessionId: string;
+    workspaceRoot: string;
+    tier: Tier;
+    userId: string;
+    generator: StructuralSummaryGenerator;
+    /** §8.3 — background re-delegation hook for a stale repo_state. */
+    onStaleRepoState?: () => void;
+    /**
+     * A1f (design §6 rehydration) — the OPTIONAL session-context section
+     * provider: the compacted-prefix distillations + the role-filtered hot
+     * tail, rendered bounded (`renderRehydratedSessionContext` in
+     * context-compaction.ts — injected by the shell to avoid an import cycle;
+     * compaction imports THIS module). `''`/absent/throw ⇒ no section — the
+     * dispatch never blocks on rehydration. The section is counted inside the
+     * F6 total budget like every other section.
+     */
+    renderSessionContextFn?: () => Promise<string>;
+    /** Test seams. */
+    loadContextStoreFn?: typeof loadContextStore;
+    resolveContextRefFn?: typeof resolveContextRef;
+    projectRepoStateFn?: typeof projectRepoStateForDispatch;
+}): Promise<string>;
+/**
+ * Compact, bounded rendering of the resolved slice: per repo one header line
+ * + a depth-≤2 directory listing, stopping at the char budget (fail-closed).
+ */
+export declare function renderRepoSliceCompact(repos: RepoSummary[], maxChars: number): string;
+export {};

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/context-store.d.ts

@@ -1,5 +1,18 @@
 import type { StructuralSummary, StructuralSummaryGenerator, RepoSummary } from '../structural-summary/types';
 import type { Tier } from './types';
+export declare function setStrictDirectorySyncFaultForTests(fault: {
+    phase: 'open' | 'sync';
+    pathSuffix?: string;
+} | null): void;
+/**
+ * Create a directory tree without leaving newly-created child entries only in
+ * the page cache. Each missing component is created individually and its
+ * parent is fsync'd before the next component is used as durability authority.
+ */
+export declare function ensureDirectoryDurable(directory: string, options?: {
+    requireParentSync?: boolean;
+    faultPath?: string;
+}): Promise<void>;
 /**
  * Legacy §4.2 staleness fingerprint of the last scan — persisted in
  * `metadata.json` by schema v1 builds. v2 keeps the same input-hash/content
@@ -59,6 +72,22 @@ export interface ContextStoreEntry {
     digest: string;
     metadata: ContextStoreMetadata;
 }
+/**
+ * A1a #5 — the frontier-authored `repo_state` record. A read-only frontier agent
+ * (never the 12B) produces the codebase overview during `familiarize`; this
+ * persists it so it is available for a later projection into implementor /
+ * decomposer briefs (that projection is [DEFERRED → P3/A1e] — A1a only persists).
+ */
+export interface RepoStateRecord {
+    /** The frontier agent's prose codebase overview. */
+    summary: string;
+    /** Which agent authored it (LE `AgentKind`, e.g. `CLAUDE`). */
+    author: string;
+    /** ISO timestamp the overview was produced. */
+    producedAt: string;
+    /** The git HEAD the overview was produced at, when captured cheaply. */
+    gitHead?: string;
+}
 /**
  * §5.4 — `slice_selector` is FORMALLY TYPED so the writer and the
  * prompt-composer reader never serialize/expect different shapes. One entry
@@ -149,6 +178,68 @@ export declare function deriveRepoId(relativePathFromWorkspaceRoot: string): str
 export declare function normalizeRepoRelativePath(relativePath: string): string;
 /** `~/.codevibe/context/<workspaceId>/` — entirely under the user's home. */
 export declare function contextStoreDir(workspaceId: string): string;
+/**
+ * Test seam — reset the module-level A1c process state (the cached at-rest
+ * key and the once-per-process GC flag). Honored ONLY under Vitest /
+ * NODE_ENV=test (the CODEVIBE_HOME_OVERRIDE gating pattern); a production
+ * caller cannot flip at-rest state mid-process.
+ */
+export declare function resetContextStoreProcessStateForTests(): void;
+/**
+ * A1e Stage-2 R1 F2 — is the A1c at-rest key resolvable RIGHT NOW? The typed
+ * ContextItem log's tail recovery must DISTINGUISH "key unavailable
+ * (transient keychain outage — leave the log byte-untouched, fail-soft)"
+ * from "key available but the tail does not decrypt (genuine corruption —
+ * rotate)". `unsealStoreFile` returns `null` for both, so this narrow probe
+ * disambiguates. Shares the per-process cached derivation (no extra
+ * keychain traffic).
+ */
+export declare function atRestKeyAvailable(): Promise<boolean>;
+/**
+ * Seal one store file: plaintext JSON → the `csEnc` envelope. Returns `null`
+ * when there is no at-rest key (keychain unavailable) — the caller must SKIP
+ * persistence rather than write plaintext (the at-rest invariant) or throw
+ * (the reconstructable-cache invariant).
+ *
+ * EXPORTED for the P3/A1e typed ContextItem log (`context-items.ts`), which
+ * builds ON the A1c at-rest discipline (same device-key HKDF, same envelope
+ * version) instead of duplicating it — the shared-context design §4.2
+ * at-rest requirement is A1c's, reused.
+ */
+export declare function sealStoreFile(plaintextJson: string): Promise<string | null>;
+export interface UnsealedStoreFile {
+    /** The plaintext JSON (decrypted, or the raw bytes for a legacy file). */
+    json: string;
+    /** True when the on-disk bytes were a `csEnc` envelope (vs legacy plaintext). */
+    wasEnvelope: boolean;
+}
+/**
+ * Unseal one store file. Three outcomes, all non-throwing:
+ *  - a `csEnc:1` envelope that decrypts → the inner plaintext JSON;
+ *  - anything that is NOT a `csEnc` envelope (legacy plaintext, or non-JSON
+ *    corruption) → the raw bytes unchanged, so the caller's own parse/shape
+ *    validation behaves EXACTLY as pre-A1c;
+ *  - `null` = CACHE MISS: an envelope we cannot decrypt (keychain unavailable,
+ *    regenerated device key, unknown version, corrupt payload). The caller
+ *    treats it as missing → recompute; a cache must never throw here.
+ *
+ * EXPORTED for the P3/A1e typed ContextItem log (see `sealStoreFile`).
+ */
+export declare function unsealStoreFile(raw: string, workspaceId: string, file: string): Promise<UnsealedStoreFile | null>;
+/**
+ * Atomic write of one store file: write to `<name>.tmp.<pid>.<rand>` → fsync →
+ * chmod 0600 → `fs.rename` over the live file (the #589 at-rest pattern,
+ * mirroring `continuation/packet-writer.ts:atomicWritePacket`). A crash
+ * mid-write never leaves a truncated `summary.json`/`metadata.json` that the
+ * resolver would fail to parse (agy r5 L1). NOT imported from local-executor
+ * (forbidden); the pattern is inlined here.
+ *
+ * EXPORTED for the A1f compaction cache (`context-compaction.ts`) — the same
+ * 0700/0600 + tmp→fsync→rename discipline, reused rather than duplicated.
+ */
+export declare function atomicWriteFile(finalPath: string, bytes: string, options?: {
+    requireDirectorySync?: boolean;
+}): Promise<void>;
 /**
  * Persist a fresh summary + digest + metadata to the store.
  *
@@ -177,6 +268,13 @@ export declare function contextStoreDir(workspaceId: string): string;
  * On any `summary_input_hash` change the caller passes `purgeFirst: true` so a
  * stale body-including summary cannot linger on disk (§4.2 conjunct (d) — the
  * PRIVACY fail-safe, Codex r7 H).
+ *
+ * A1c — both JSON files are SEALED (csEnc envelope) before the commit-marker
+ * unlink; `digest.txt` stays PLAINTEXT (non-sensitive bare sha256 hex, and the
+ * commit marker must stay readable without a key). No at-rest key (keychain
+ * unavailable) ⇒ persistence is SKIPPED entirely — the previously-committed
+ * set (if any) stays intact and the next run recomputes; a cache write never
+ * downgrades to plaintext and never crashes the shell.
  */
 export declare function writeContextStore(deps: {
     workspaceId: string;
@@ -190,6 +288,35 @@ export declare function writeContextStore(deps: {
  * recompute). Defensive: a partially-written / corrupt file never throws.
  */
 export declare function loadContextStore(workspaceId: string): Promise<ContextStoreEntry | null>;
+/**
+ * A1a #5 — persist the frontier-authored codebase overview as `repo-state.json`
+ * alongside the structural summary. Mirrors the atomic-write discipline of
+ * `writeContextStore` (tmp → fsync → chmod → rename via `atomicWriteFile`), but as
+ * a SINGLE additive file: it is NOT part of the §4.2 content-addressed commit set,
+ * so no digest commit-marker ordering is needed. A crash mid-write leaves either
+ * the old file or the new one — never a torn read (the reader JSON-parses; a
+ * partial file fails the parse and is treated as missing).
+ */
+export declare function writeRepoState(workspaceId: string, record: RepoStateRecord): Promise<void>;
+/**
+ * A1a #5 — load the frontier-authored `repo_state` for a workspace. Returns `null`
+ * when the file is missing / unparseable / shape-invalid (best-effort, never
+ * throws), mirroring `loadContextStore`'s tolerant read.
+ */
+export declare function loadRepoState(workspaceId: string): Promise<RepoStateRecord | null>;
+/**
+ * A1c — sweep the context-store ROOT (the parent of the per-workspace dirs):
+ *   1. TTL — delete workspace dirs whose newest file mtime is older than
+ *      `CONTEXT_STORE_TTL_MS`;
+ *   2. LRU cap — if more than `CONTEXT_STORE_MAX_DIRS` dirs remain (the
+ *      current workspace's dir counts toward the cap), delete oldest-by-mtime
+ *      beyond the cap.
+ * `currentWorkspaceId` is NEVER deleted — it is the store being written.
+ * Everything under the root is a reconstructable cache, so deletion is always
+ * safe and every per-dir failure is non-fatal (skip + continue). Only DIRECTORY
+ * entries are swept: the store owns nothing else at the root.
+ */
+export declare function gcContextStore(currentWorkspaceId?: string): Promise<void>;
 interface GitProbe {
     isGitRepo: boolean;
     gitTopLevel: string | null;
@@ -197,6 +324,41 @@ interface GitProbe {
     /** True only when `git status --porcelain --untracked-files=all` is EMPTY. */
     clean: boolean;
 }
+/**
+ * Stage-2 R2 G3 — the discriminated result of the `repo_state` freshness
+ * HEAD probe. Collapsing "non-git" and "the probe FAILED" into one null was
+ * the G3 hole: a transient git failure borrowed the non-git 24h freshness
+ * allowance. The three outcomes drive DIFFERENT projection policies
+ * (context-items.ts `projectRepoStateForDispatch`).
+ */
+export type WorkspaceGitHeadProbe = {
+    kind: 'head';
+    head: string;
+} | {
+    kind: 'non-git';
+} | {
+    kind: 'probe-failed';
+};
+/**
+ * A1e Finding 5 (design §8.3 freshness) — the narrow git-HEAD probe the
+ * `repo_state` freshness projection uses.
+ *
+ * Stage-2 R2 G3 — discriminated outcomes:
+ *  - `head` — a real git repo with a resolvable HEAD commit (the only
+ *    outcome a `repo_state` record may PIN a `gitHead` from);
+ *  - `non-git` — DETERMINISTICALLY not a repo (`git rev-parse
+ *    --is-inside-work-tree` fails with "not a git repository" — exit
+ *    semantics, not a guess): the only bucket eligible for the F5
+ *    age-bounded freshness allowance;
+ *  - `probe-failed` — everything else: git missing/broken, permission or
+ *    transient errors, AND the UNBORN-HEAD case (a `git init` repo with no
+ *    initial commit). Unborn-HEAD is bucketed here deliberately: it IS a
+ *    repo, but there is no commit to pin freshness to and a re-delegated
+ *    read could not produce a head-proven record either — so the
+ *    conservative probe-failed policy (stale, NO re-delegation loop) is
+ *    the sound handling, pinned by test.
+ */
+export declare function probeWorkspaceGitHead(workspaceRoot: string): Promise<WorkspaceGitHeadProbe>;
 /**
  * Hash the generation inputs (§4.2 conjunct (d)). A `StructuralSummary` is a
  * pure function of `tree content × generation inputs`; this hashes the

package/node_modules/@quantiya/codevibe-core/dist/orchestration-shell/declared-test-runner.d.ts

@@ -1,6 +1,8 @@
 import type { Dirent, Stats } from 'node:fs';
 import type { runShellCommand } from '../local-executor/verification-gates/shell-runner';
 import type { ShadowDiffFile } from '../local-executor/workspace-shadow';
+import type { ProcessCleanupOwner } from '../local-executor/process-tree';
+import { type WorkspaceRootAuthority } from '../local-executor/workspace-authority';
 /** Default per-file wall-clock budget for a declared-test `node` run. */
 export declare const DECLARED_TEST_TIMEOUT_MS = 300000;
 /**
@@ -20,6 +22,9 @@ export interface DeclaredTestResult {
     ranCount: number;
     /** Never-written declared file / empty-or-JS-less declared dir (§3.D, VISIBLE). */
     skipped: string[];
+    /** False means the caller must retain the test cwd. */
+    workspaceCleanupSafe?: false;
+    workspaceCleanupOwner?: ProcessCleanupOwner;
 }
 export interface RunDeclaredTestSurfacesArgs {
     /** cwd holding the agent's changes (the shadow root). */
@@ -37,8 +42,8 @@ export interface RunDeclaredTestSurfacesArgs {
     realpath: (p: string) => Promise<string>;
     /** Injected — file/dir discriminate on the resolved target. */
     stat: (p: string) => Promise<Stats>;
-    /** Injected — directory expansion. */
-    readdir: (p: string) => Promise<Dirent[]>;
+    /** @internal test-only directory expansion seam; production streams via opendir. */
+    readdir?: (p: string) => Promise<Dirent[]>;
     /**
      * Injected (#609) — read a file's UTF-8 contents (nearest-`package.json` framework detection).
      * A throw (ENOENT / EISDIR / unreadable) is TOTAL-handled by `detectFramework` (→ keep walking up,
@@ -47,6 +52,20 @@ export interface RunDeclaredTestSurfacesArgs {
     readFile: (p: string) => Promise<string>;
     /** Default `DECLARED_TEST_TIMEOUT_MS`. */
     timeoutMs?: number;
+    /** Cooperative session-shutdown cancellation for spawned test processes. */
+    signal?: AbortSignal;
+    /** Exact snapshot incarnation selected before declared-test discovery. */
+    shadowRootAuthority?: WorkspaceRootAuthority;
+    /** @internal deterministic root-replacement seam after initial validation. */
+    afterAuthorityCheck?: () => Promise<void> | void;
+    /** @internal deterministic A→B→A restoration before the final check. */
+    beforeAuthorityCompletion?: () => Promise<void> | void;
+    /** @internal deterministic root replacement immediately before framework discovery. */
+    beforeFrameworkDiscovery?: () => Promise<void> | void;
+    /** @internal helper-held missing-intermediate authority seam. */
+    beforeClassificationMissing?: () => Promise<void> | void;
+    /** @internal helper-held missing-leaf completion seam. */
+    beforeClassificationCompletion?: () => Promise<void> | void;
 }
 /**
  * Canonicalize a declared scope / diff path for comparison: collapse backslashes to