@quantiya/codevibe-core 2.0.6 → 2.0.7

package/dist/orchestration-shell/types.d.ts

@@ -330,6 +330,8 @@ export type ConversationEntry = {
     final: true;
     source: 'planner' | 'shell';
     text: string;
+    localOnly?: true;
+    handoffExcluded?: true;
 } | {
     kind: 'gate-prompt';
     id: string;
@@ -409,6 +411,54 @@ export interface PendingClarification {
      */
     attachmentPaths?: string[];
 }
+/**
+ * A1a #3/#4 — one numbered choice in a `PendingPlannerOffer`. Contract-ready
+ * shape (mirrors `GatePromptOption`) so an F4 mobile renderer (Wave 3, after the
+ * contract freeze) can consume it verbatim; `id` is a stable option key,
+ * `label`/`description` are the shell-authored (never model-authored) render copy.
+ */
+export interface PlannerOfferOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+}
+/**
+ * A1a #3/#4 (design §7 R3 / §8.3) — a lightweight interactive offer the shell
+ * presents instead of a silent spawn. Modeled on `pendingClarification` (NOT the
+ * server-coupled gate-prompt path): the offer + its numbered options are held in
+ * the local store, and the numbered reply resolves it locally. F4 mirrors a
+ * separate encrypted INTERACTIVE_PROMPT for mobile rendering; the local menu text
+ * stays out of workflow handoff context.
+ *
+ *  - `team_decomposition` (#4): the planner routed `team_decompose`; rather than
+ *    silent-launching a team, offer Accept-team / Reject→single / Talk-it-through.
+ *  - `build_transition` (#3): a mid-active-design "let's build it"; rather than
+ *    silent-spawning an implementor, offer Build-now / Keep-discussing.
+ *
+ * The stashed context lets each kind resolve WITHOUT re-classifying: the
+ * team-decomposition briefs the accept path feeds to `routeTeamDecompose` /
+ * `dispatchSynthesizedSingleStartTask`, and the build request the transition
+ * proceeds with.
+ */
+export interface PendingPlannerOffer {
+    kind: 'team_decomposition' | 'build_transition';
+    /** Contract-ready shape (mirror GatePromptOption). Shell-authored copy. */
+    options: ReadonlyArray<PlannerOfferOption>;
+    /** The `advisory` conversation entry that rendered the numbered options. */
+    conversationEntryId: string;
+    /** The planner's short reason (why this offer) — surfaced in the render. */
+    rationale: string;
+    /** team_decomposition: the decomposer input brief for `routeTeamDecompose`. */
+    decomposerBrief?: string;
+    /** team_decomposition / build fallback: the brief for reject → single agent. */
+    singleFallbackBrief?: string;
+    /** build_transition: the build request to proceed with on accept (no re-classify). */
+    originalUserPrompt?: string;
+    /** IMAGE-ATTACHMENT-DESIGN.md §5/§7.5 — team attachments, armed on the launch. */
+    attachments?: ImageAttachment[];
+    /** §13 Option-2 — ordered-with-dups carried paths for the number-based chip rewrite. */
+    attachmentPaths?: string[];
+}
 /**
  * [ADDITIVE WIDENING — CP-12 W3, per PHASE-CP-12-DESIGN.md §3.5 "minimal
  * multi-track status node; rich UX is #469"]. Per-track lifecycle state as the
@@ -445,7 +495,7 @@ export interface TeamTrackEntry {
 }
 /**
  * [ADDITIVE WIDENING — CP-12 W3] Minimal team state. `null` for
- * single-track/Companion/stub sessions (no team → no status node). Populated
+ * single-track/Companion sessions (no team → no status node). Populated
  * when `/team` accepts a task group + per-track W2.b shell events arrive.
  */
 export interface TeamState {
@@ -536,6 +586,16 @@ export interface OrchestrationState {
     activeReviewerSeats: Map<string, ReviewerSeatState>;
     currentGate: GateState | null;
     pendingClarification: PendingClarification | null;
+    /**
+     * `[ADDITIVE WIDENING — A1a #3/#4]` The active lightweight local interactive
+     * offer (team-decomposition / build-transition), or `null` when none is in
+     * flight (the default). Set by `PLANNER_OFFER_PRESENTED`; a single in-range
+     * numeric reply resolves it locally (see `handleShellUserInput`), and any
+     * non-offer resolution clears it (`CLEAR_PENDING_PLANNER_OFFER`). F4 mirrors an
+     * encrypted INTERACTIVE_PROMPT for mobile, but this store node remains the local
+     * source of truth.
+     */
+    pendingPlannerOffer: PendingPlannerOffer | null;
     inputHistory: string[];
     /**
      * `[ADDITIVE WIDENING — CP-1.d]` per `PHASE-CP-1-D-DESIGN.md` §4.8
@@ -552,7 +612,7 @@ export interface OrchestrationState {
     structuralSummaryError: string | null;
     /**
      * `[ADDITIVE WIDENING — CP-12 W3]` per PHASE-CP-12-DESIGN.md §3.5. `null`
-     * for single-track/Companion/stub sessions (the status node is hidden).
+     * for single-track/Companion sessions (the status node is hidden).
      * Populated by `/team` (createTaskGroup accepted) + the W2.b per-track shell
      * events. Rich per-track timeline + MergeGate result card are
      * [DEFERRED → CP-8 #469].
@@ -563,7 +623,7 @@ export interface OrchestrationState {
      * live status line (spinner). `null` when idle / waiting on the user. Updated
      * in place by `TASK_PROGRESS` spinner phases; cleared by `waiting_user` and by
      * the terminal milestone phases (`promoted` / `discarded`). Non-loop /
-     * Companion / stub sessions never dispatch `TASK_PROGRESS`, so this stays null.
+     * Companion sessions never dispatch `TASK_PROGRESS`, so this stays null.
      */
     progress: LiveProgress | null;
     /**
@@ -585,7 +645,7 @@ export interface OrchestrationState {
  * props with no in-component network I/O:
  *   - `tier` decides the seat budget (Pro = 2 seats, Max = 3).
  *   - `installedAgents` is the host-detected agent set — the wizard offers ONLY
- *     these as reviewer choices (mirrors the `codevibe orchestration configure`
+ *     these as reviewer choices (mirrors the `/reviewer-setup`
  *     CLI), so a user can never pick an uninstalled agent.
  *   - `currentSeats` is shown as a CONTEXT line at the top of the wizard (the
  *     user's existing panel) — display only; the wizard starts fresh at the
@@ -675,6 +735,11 @@ export type OrchestrationAction = {
     task: RunningTaskState;
 } | {
     type: 'CLEAR_PENDING_CLARIFICATION';
+} | {
+    type: 'PLANNER_OFFER_PRESENTED';
+    offer: PendingPlannerOffer;
+} | {
+    type: 'CLEAR_PENDING_PLANNER_OFFER';
 } | {
     type: 'STRUCTURAL_SUMMARY_GENERATED';
     summary: StructuralSummary;
@@ -711,6 +776,8 @@ export type OrchestrationAction = {
     type: 'SHELL_ADVISORY';
     text: string;
     source: 'shell';
+    localOnly?: true;
+    handoffExcluded?: true;
 } | {
     type: 'GATE_PROMPT_NOTES_CANCELLED';
     promptEntryId: string;

package/dist/planner/index.d.ts

@@ -3,5 +3,5 @@ export * from './adapter';
 export { PlannerCacheLayer } from './cache';
 export { PlannerHealthMachine } from './health-state';
 export { BackendPlannerClient, PlannerBudgetExceededError, PlannerTierGateRejectedError, type PlannerAppSyncTransport, type PlannerCryptoBridge, type SessionKeyResolver, type ShellEventEmit, type EmitShellEventFn, } from './client';
-export { LocalGemmaPlannerAdapter, parseLocalGemmaPlannerDecision, renderLocalGemmaPlannerPrompt, type LocalGemmaPlannerRunner, } from './local-gemma';
+export { LocalGemmaPlannerAdapter, parseLocalGemmaPlannerDecision, PlannerOutputUnparseableError, renderLocalGemmaPlannerPrompt, type LocalGemmaPlannerRunner, } from './local-gemma';
 export { parseLocalGemmaAdvisorySummary, renderLocalGemmaFamiliarizePrompt, type LocalGemmaAdvisoryRunner, } from './local-advisory';

package/dist/planner/local-advisory.d.ts

@@ -1,6 +1,17 @@
 import type { StructuralSummary } from '../structural-summary/types';
 export interface LocalGemmaAdvisoryRunner {
     generateAdvisory(promptText: string, options?: LocalGemmaAdvisoryOptions): Promise<string>;
+    /**
+     * Dogfood #618 — optional fire-and-forget model pre-warm (load + keep_alive).
+     * Never throws; resolves false on failure. Called once at shell startup.
+     */
+    warm?(): Promise<boolean>;
+    /**
+     * #618 Stage-2 — optional fire-and-forget model release (keep_alive: 0).
+     * Never throws; resolves false on failure. Called once at shell teardown so
+     * the model's memory isn't held for the keep_alive window after quit.
+     */
+    unload?(): Promise<boolean>;
     runtimeLabel: string;
 }
 export type LocalGemmaAdvisoryResponseFormat = 'json' | 'text';
@@ -46,6 +57,7 @@ export declare function renderLocalGemmaBrowsePrompt(args: {
     };
     content: string;
 }): string;
+export declare function boundedPriorBrainstormTurns(turns: string[] | undefined): string[];
 /**
  * WEB-BROWSING (search-route): turn the user's request + recent conversation into a
  * concise web-search QUERY. The local model resolves acronyms/pronouns from context

package/dist/planner/local-gemma.d.ts

@@ -5,8 +5,35 @@ export interface LocalGemmaPlannerRunner {
     classify(promptText: string): Promise<string>;
     generateAdvisory?: LocalGemmaAdvisoryRunner['generateAdvisory'];
     probe?(): Promise<PlannerProbeResult>;
+    /**
+     * Dogfood #618 — optional fire-and-forget model pre-warm (load into memory +
+     * arm keep_alive). Never throws; resolves false on failure. The shell calls
+     * this once at startup so the session's first classify/advisory doesn't pay
+     * the runtime's cold load.
+     */
+    warm?(): Promise<boolean>;
+    /**
+     * #618 Stage-2 — optional fire-and-forget model release (keep_alive: 0),
+     * called once at shell teardown. Never throws; resolves false on failure.
+     */
+    unload?(): Promise<boolean>;
     runtimeLabel: string;
 }
+/**
+ * A1a P0 (R3 — design §7 "the conductor must NEVER hard-fail"): thrown when the
+ * local Gemma model RESPONDED but its output could not be parsed into a valid
+ * route (out-of-domain prose, truncated JSON, unsupported action/keys, etc.).
+ *
+ * This is deliberately DISTINCT from an infrastructure failure (Ollama
+ * unreachable / timeout / budget / tier-gate — those reject out of the runner,
+ * never reach the parser). The orchestration shell catches THIS class and
+ * degrades to a safe "general question / not a build request" advisory route
+ * instead of surfacing a `planner-error`; a genuine infra failure still surfaces
+ * "Planner unavailable" because retrying would not help.
+ */
+export declare class PlannerOutputUnparseableError extends Error {
+    constructor(message: string);
+}
 /**
  * Text-only route classifier prompt. It intentionally excludes repository
  * paths, summaries, source snippets, file bodies, and the raw structural digest.

package/dist/planner/types.d.ts

@@ -63,6 +63,13 @@ export interface PlannerInput {
     clarifications: Clarification[];
     sessionContext: SessionContext;
     budgetHint: BudgetHint;
+    /**
+     * Local-planner-only, role-filtered rendering of the canonical ContextItems
+     * session history. The hosted planner client deliberately ignores this field;
+     * it exists so local Gemma can resolve ordinary multi-turn references without
+     * relying on shell text heuristics or a model-private conversation cache.
+     */
+    canonicalConversationContext?: string;
 }
 export interface PlannerDecision {
     action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse' | 'team_decompose' | 'familiarize' | 'brainstorm' | 'browse';

package/dist/reviewer/index.d.ts

@@ -7,8 +7,6 @@ export type { RunReviewerOptions, SubprocessError, SubprocessOutcome, } from './
 export { runReviewer, SubprocessErrorClass } from './subprocess.js';
 export type { ClaudeReviewerProviderOptions } from './providers/claude.js';
 export { ClaudeReviewerProvider } from './providers/claude.js';
-export type { GeminiEnvelope, GeminiModelStats, GeminiReviewerProviderOptions, GeminiStats, } from './providers/gemini.js';
-export { GeminiReviewerProvider } from './providers/gemini.js';
 export type { CodexReviewerProviderOptions } from './providers/codex.js';
 export { CodexReviewerProvider } from './providers/codex.js';
 export type { AntigravityReviewerProviderOptions } from './providers/antigravity.js';

package/dist/reviewer/provider.d.ts

@@ -37,8 +37,10 @@ export interface ReviewerEvaluateOptions {
      * the workdir on BOTH backends — A5 `cwd: workdir`; Docker `docker exec -w
      * /workspace`) and reads it back from `<workdir>/<name>` on the host (the same
      * inode, even when A5 canonicalizes the workdir — the host read follows the
-     * symlink). The Claude / Gemini providers do not use a file output, so they
-     * ignore this field. ABSENT (legacy path / non-substrate) → the provider uses
+     * symlink). The Claude provider uses no file output and ignores this field;
+     * the Antigravity provider writes no verdict file either but DOES consume
+     * `workdir` (`--add-dir <workdir>` — agy is workspace-centric). ABSENT
+     * (legacy path / non-substrate) → the provider uses
      * its byte-identical legacy `os.tmpdir()` location.
      *
      * # Why this is NOT derivable from `substrate`
@@ -105,10 +107,11 @@ export interface ReviewerSpec {
      * is agent-agnostic here; each provider enforces the sandbox in its own
      * way:
      * - Claude: `--allowed-tools Read,Grep,Glob` CLI flag.
-     * - Gemini: `--approval-mode plan` (Gemini's first-class read-only mode).
-     *   The `tool_allowlist` is intentionally unused by the Gemini provider;
-     *   plan mode is the sandbox contract. 2.0.x task #62 tracks adding
-     *   `--policy <tempfile>` as defense-in-depth.
+     * - Antigravity: no native read-only flag AND no CP-7 substrate — agy is
+     *   reduced-trust (§6 Q4), so the loop pre-routes agy seats to the LEGACY
+     *   unsandboxed path with a reduced-trust badge. Agy 1.1.2 requires the
+     *   prompt as `--print <prompt>` and is granted the repo via
+     *   `--add-dir <workdir>`.
      * - Codex: `--sandbox read-only --skip-git-repo-check` flags + per-spawn
      *   ephemeral output file.
      */

package/dist/reviewer/providers/antigravity.d.ts

@@ -25,9 +25,8 @@ export declare class AntigravityReviewerProvider implements ReviewerProvider {
 /**
  * Construct the agy CLI invocation (design D4):
  *
- * - `--print ''` — non-interactive one-shot; the EMPTY value selects the
- *   STDIN prompt (fed by `runReviewer`), keeping multi-line markdown out of
- *   argv (same posture as gemini's `-p ''`).
+ * - `--print <prompt>` — non-interactive one-shot. Agy 1.1.2 requires the
+ *   prompt value in argv; stdin prompt mode was removed.
  * - `--model <hint>` — optional; omitted when `spec.model_hint` is `null`
  *   (agy default model).
  * - `--print-timeout <s>s` — agy's INTERNAL print-mode poll ceiling, derived

package/dist/reviewer/registry.d.ts

@@ -24,7 +24,6 @@ export declare class ReviewerRegistry implements ReviewerProvider {
      * ```ts
      * const registry = new ReviewerRegistry()
      *   .with('claude', new ClaudeReviewerProvider())
-     *   .with('gemini', new GeminiReviewerProvider())
      *   .with('codex',  new CodexReviewerProvider());
      * ```
      *
@@ -65,11 +64,18 @@ export declare class ReviewerRegistry implements ReviewerProvider {
     evaluate(spec: ReviewerSpec, gateId: string, opts?: ReviewerEvaluateOptions): Promise<ReviewerVerdict>;
 }
 /**
- * Production factory: build a registry pre-populated with all four
- * subprocess providers (Claude, Gemini, Codex, Antigravity) using the
+ * Production factory: build a registry pre-populated with the three
+ * supported subprocess providers (Claude, Codex, Antigravity) using the
  * standard binaries from PATH. Equivalent of Rust's
  * `withSubprocessProviders()` napi factory.
  *
+ * Gemini is SUNSET (2026-07): it is no longer registered here, so a policy
+ * that names a `gemini` reviewer fails closed via `evaluate`'s
+ * missing-provider path (throws `spawn_failed` → engine escalates to the
+ * user) rather than silently spawning `gemini`. The `'GEMINI'` AgentKind
+ * value is retained for backward-compatible deserialization of legacy
+ * records; it is simply not a routable reviewer.
+ *
  * Plugins call this once at startup and hand the registry to the
  * engine fan-out path. Inert registrations cost nothing — no
  * subprocess fires until the policy actually references that agent.
@@ -80,7 +86,6 @@ export declare class ReviewerRegistry implements ReviewerProvider {
  * ```ts
  * const registry = new ReviewerRegistry()
  *   .with('claude', new ClaudeReviewerProvider({ executable: '/opt/bin/claude' }))
- *   .with('gemini', new GeminiReviewerProvider({ executable: '/opt/bin/gemini' }))
  *   .with('codex',  new CodexReviewerProvider({  executable: '/opt/bin/codex' }));
  * ```
  */

package/dist/reviewer/token-usage.d.ts

@@ -9,6 +9,16 @@
  * never corrupts the accumulator.
  */
 export declare function finiteToken(n: unknown): number;
+/**
+ * Locate the FIRST balanced top-level `{...}` in `stdout` that parses to an object
+ * with `type === 'result'` — Claude may emit non-JSON warning / MCP lines before
+ * the terminal result envelope, so we scan candidate `{` positions rather than
+ * parsing the whole stdout blindly. Returns the parsed object, or null if none
+ * parses to a `result` envelope. Exported for the orchestration-shell advisory
+ * quota classifier ([#637] — the Claude usage-limit rides in this envelope's
+ * `result` field); never throws.
+ */
+export declare function firstResultEnvelope(stdout: string): Record<string, unknown> | null;
 /**
  * [P2-6] Unwrap a Claude Code `--output-format json` NON-interactive envelope into
  * `{ text, tokens }`. The ENTIRE body is `try/catch`-guarded — ANY throw (parse

package/dist/session/__tests__/device-registration-lease.test.d.ts

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

package/dist/session/__tests__/pending-session-create.test.d.ts

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

package/dist/session/__tests__/session-rekey-fingerprint.test.d.ts

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

package/dist/session/__tests__/session-resume-key-reconciliation.test.d.ts

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

package/dist/session/__tests__/session-resume-pending-first.test.d.ts

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

package/dist/session/device-key-watcher.d.ts

@@ -1,5 +1,6 @@
 import { AppSyncClient } from '../appsync/appsync-client';
 import { Logger } from '../logger';
+export declare function isOwnDeviceRegistration(ownDeviceId: string, registeredDeviceId: string): boolean;
 /**
  * Start the device-key registration watcher for the authenticated user.
  *

package/dist/session/index.d.ts

@@ -1,5 +1,7 @@
-export { resumeOrCreateSession, prepareSessionEncryption } from './session-resume';
-export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './session-resume';
+export { resumeOrCreateSession, prepareSessionEncryption, PlannerProxyServiceKeyMissingError, SessionEncryptionPreparationError, } from './session-resume';
+export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult, SessionEncryptionPreparationFailureKind, } from './session-resume';
+export { createSessionWithPendingLedger, replayPendingSessionCreateForIntent, } from './pending-session-create';
+export type { PendingSessionCreateIntent } from './pending-session-create';
 export { rekeySessionForNewDevices } from './session-rekey';
 export { startDeviceKeyWatcher } from './device-key-watcher';
 export { registerDeviceEncryptionKey } from './register-device-key';

package/dist/session/pending-session-create.d.ts

@@ -0,0 +1,61 @@
+import { type AppSyncClient } from '../appsync';
+import type { Logger } from '../logger';
+import type { CreateSessionInput, Session } from '../types';
+interface PendingSessionCreateRecord {
+    schema: 'codevibe.pending_session_create.v2';
+    sessionId: string;
+    creationRequestId: string;
+    intentFingerprint: string;
+    input: CreateSessionInput;
+    sessionKey: string | null;
+    createdAt: string;
+}
+export interface PendingSessionCreateIntent {
+    userId: string;
+    agentType: NonNullable<CreateSessionInput['agentType']>;
+    /** Plain local path. It is persisted only inside the sealed ledger. */
+    projectPath: string;
+}
+declare function ledgerPath(sessionId: string): string;
+declare function fingerprintIntent(intent: PendingSessionCreateIntent): string;
+declare function readPending(sessionId: string): Promise<PendingSessionCreateRecord | null>;
+declare function removePending(sessionId: string, record?: PendingSessionCreateRecord): Promise<void>;
+declare function findPendingForIntent(intent: PendingSessionCreateIntent, logger: Logger): Promise<PendingSessionCreateRecord | null>;
+/**
+ * Persist one exact create envelope before network I/O and replay it unchanged
+ * after an ambiguous transport failure or process restart.
+ */
+export declare function createSessionWithPendingLedger(args: {
+    input: CreateSessionInput;
+    sessionKey: string | null;
+    intent: PendingSessionCreateIntent;
+    appSyncClient: Pick<AppSyncClient, 'createSession'>;
+    logger: Logger;
+    /**
+     * Synchronous lifecycle handoff fired immediately after the backend response
+     * is proven to match the sealed request, before keychain or ledger cleanup.
+     */
+    onAdmitted?: (session: Session) => void;
+}): Promise<{
+    session: Session;
+    sessionKey: string | null;
+}>;
+/** Replay an interrupted create before minting a new id for the same intent. */
+export declare function replayPendingSessionCreateForIntent(args: {
+    intent: PendingSessionCreateIntent;
+    appSyncClient: Pick<AppSyncClient, 'createSession'>;
+    logger: Logger;
+    onAdmitted?: (session: Session) => void;
+}): Promise<{
+    session: Session;
+    sessionKey: string | null;
+} | null>;
+export declare const pendingSessionCreateTestSeams: {
+    ledgerPath: typeof ledgerPath;
+    readPending: typeof readPending;
+    removePending: typeof removePending;
+    findPendingForIntent: typeof findPendingForIntent;
+    fingerprintIntent: typeof fingerprintIntent;
+    setRemovalFault(fault: "after_tombstone" | null): void;
+};
+export {};

package/dist/session/register-device-key.d.ts

@@ -1,5 +1,15 @@
 import { AppSyncClient } from '../appsync/appsync-client';
 import { Logger } from '../logger';
+export declare function registrationLeaseIsFresh(lastUsedAt: string | undefined, nowMs?: number): boolean;
+export interface RegisterDeviceEncryptionKeyOptions {
+    /**
+     * Publish even when the normal registration lease is fresh. Recovery paths
+     * use this to emit the mutation that wakes peer device-key subscriptions.
+     */
+    force?: boolean;
+    /** Structured diagnostic explaining why a forced registration was needed. */
+    reason?: string;
+}
 /**
  * Register the current device's ECDH public key with the backend.
  *
@@ -10,4 +20,4 @@ import { Logger } from '../logger';
  * @param appSyncClient Authenticated AppSyncClient.
  * @param logger Plugin-specific logger so log lines are tagged correctly.
  */
-export declare function registerDeviceEncryptionKey(appSyncClient: AppSyncClient, logger: Logger): Promise<void>;
+export declare function registerDeviceEncryptionKey(appSyncClient: AppSyncClient, logger: Logger, options?: RegisterDeviceEncryptionKeyOptions): Promise<void>;

package/dist/session/session-rekey.d.ts

@@ -8,8 +8,8 @@ export interface RekeyOptions {
      * they already have an entry in `session.encryptedKeys`. Use this
      * when you know a specific device just re-registered — for example,
      * when handling an `onDeviceKeyRegistered` subscription event — so
-     * a rotated public key gets a fresh wrapped entry. The old entry
-     * is left intact; the new one is appended via `grantSessionKey`.
+     * a rotated public key gets a fresh wrapped entry. The backend replaces
+     * the recipient's prior entry atomically and collapses legacy duplicates.
      *
      * Default: empty. The bulk diff path (catch-up after disconnect,
      * catch-up at session resume) does not pass this and relies on the
@@ -23,9 +23,8 @@ export interface RekeyOptions {
  * key to any device that is missing an entry (or that the caller has
  * explicitly marked as needing a fresh wrap via `forceDeviceIds`).
  *
- * Safe to call repeatedly. No-op when every registered device already
- * has an entry and nothing is forced. Does not modify or remove existing
- * entries — only appends new ones via the grantSessionKey mutation.
+ * Safe to call repeatedly. No-op when every registered device has an envelope
+ * bound to its current public key and nothing is forced.
  *
  * @param sessionId  The session to re-key.
  * @param sessionKey The plaintext session key (base64). The caller must

package/dist/session/session-resume.d.ts

@@ -19,10 +19,24 @@ export interface ResumeOrCreateSessionInput {
     metadata?: Record<string, any>;
 }
 export interface ResumeOrCreateSessionResult {
+    /**
+     * The authoritative backend row ID. This can differ from the requested ID
+     * when a sealed, ambiguous create is replayed for the same launch intent.
+     * Callers MUST bind subscriptions, heartbeats, and events to this value.
+     */
+    sessionId: string;
     /** Whether an existing session was found and reactivated */
     resumed: boolean;
     /** The E2E session key (for encrypting/decrypting events), or null if no encryption */
     sessionKey: string | null;
+    /**
+     * The session-key generation of the AUTHORITATIVE row (§4.5 key-gen binding),
+     * or null when unencrypted / the backend echoed no generation. Callers stamp
+     * this onto `expectedSessionKeyGen` so a key rotation racing an event write is
+     * rejected by the backend ConditionCheck rather than committing an
+     * undecryptable row (tool-event consolidation #229/#230).
+     */
+    sessionKeyGen: string | null;
 }
 /**
  * CP-1.b IMPL r5 H-2 — Typed error thrown by `prepareSessionEncryption()`
@@ -45,7 +59,13 @@ export interface ResumeOrCreateSessionResult {
  * shell-side typed error closes the funnel at session-create time so
  * the user never reaches a session that can't be decrypted.
  */
-export declare class PlannerProxyServiceKeyMissingError extends Error {
+export type SessionEncryptionPreparationFailureKind = 'backend_unavailable' | 'local_key_unavailable';
+export declare class SessionEncryptionPreparationError extends Error {
+    readonly kind: SessionEncryptionPreparationFailureKind;
+    readonly cause?: unknown;
+    constructor(kind: SessionEncryptionPreparationFailureKind, message: string, cause?: unknown);
+}
+export declare class PlannerProxyServiceKeyMissingError extends SessionEncryptionPreparationError {
     constructor(msg: string);
 }
 /**

package/dist/substrate/docker.d.ts

@@ -48,6 +48,8 @@ export declare function buildContainerEntrypoint(sanitizedEnv: Readonly<Record<s
  *   - `-v <relayScript>:/codevibe/relay.js:ro` → the in-container relay (ro).
  *   - `-v <udsDir>:/codevibe/broker:rw`  → the bind-mounted broker UDS dir (rw,
  *     so the container's `connect()` works; the dir holds only the socket).
+ *   - `-v <bootstrap>:/codevibe/agent:ro` → broker helper + token file (ro).
+ *   - `-v <agentConfig>:/codevibe/agent-config:rw` → non-secret CLI config/runtime.
  *   - env via repeated `-e K=V` built EXACTLY from `spec.sanitizedEnv` (no host
  *     env passthrough; `docker run` does NOT inherit the host env). MED fix:
  *     the `-e` flags ADD to the image's baked env, so the AUTHORITATIVE wipe is
@@ -70,6 +72,11 @@ export declare function buildRunArgv(args: {
         hostDir: string;
         sandboxDir: string;
     };
+    /** CP-7 PART D — mutable CLI config/runtime mount (`hostDir`→`sandboxDir:rw`). */
+    agentConfig?: {
+        hostDir: string;
+        sandboxDir: string;
+    };
 }): string[];
 /**
  * `docker exec [-i] <name> env -i <sanitizedEnv> <argv...>` — run the agent

package/dist/substrate/sandbox-exec.d.ts

@@ -62,8 +62,8 @@ export interface SandboxExecDeps {
 export declare function buildSeatbeltProfile(workdir: string, execPath?: string, 
 /**
  * CP-7 PART D — extra READ-ONLY dirs to grant (the apiKeyHelper bootstrap dir
- * holding the helper script + broker-token file + agent config). Read-only:
- * the agent reads the current token; no write grant (the host owns rotation).
+ * holding the helper script + broker-token file). Read-only: the agent reads
+ * the current token; no write grant (the host owns rotation).
  * These are explicit, scoped subpaths — NOT $HOME / /Users (the MED-fix
  * invariant that host secrets stay unreadable still holds).
  */
@@ -102,7 +102,21 @@ homedir?: string,
  * Null/absent → no audit deny is emitted (e.g. a unit test without a real audit
  * tree); production always threads the resolved audit dir.
  */
-auditDir?: string | null): string;
+auditDir?: string | null, 
+/**
+ * Extra dirs that the agent may read/write. Used only for the mutable CLI
+ * config/runtime dir; the broker-token helper stays in `extraReadDirs`.
+ */
+extraWriteDirs?: readonly string[], 
+/**
+ * A1d (design §8.1 — the resolver sandbox lattice). Network posture:
+ * `'loopback'` (default — the CP-7 broker tier, byte-identical profile) or
+ * `'open'` (the resolver-confinement row for a broker-less reduced-trust
+ * agent: inbound stays denied, ALL outbound is allowed so the agent's own
+ * file-authed model call reaches its vendor directly). See
+ * {@link SubstrateSpec.networkPosture}.
+ */
+networkPosture?: 'loopback' | 'open'): string;
 /**
  * A5 macOS `sandbox-exec` substrate (`egressFidelity: 'coarse'`). See file
  * header. NOT the default — the LE selects it as the macOS Docker-fallback.

package/dist/substrate/types.d.ts

@@ -59,8 +59,7 @@ export interface SubstrateSpec {
     /**
      * CP-7 PART D (§3.3 agy-R3 bootstrap) — OPTIONAL, additive. The host
      * directory holding the agent's `apiKeyHelper` script + the broker-token
-     * file + the agent config (Claude `settings.json` / Codex `config.toml`),
-     * bind-mounted READ-ONLY into the sandbox at `sandboxDir` so the wiped,
+     * file, bind-mounted READ-ONLY into the sandbox at `sandboxDir` so the wiped,
      * `--network none` agent can read the CURRENT broker token from a file
      * WITHOUT a network/IPC fetch. The host LE REFRESHES the token file
      * out-of-band on rotation; the read-only mount lets the host rewrite the
@@ -71,11 +70,25 @@ export interface SubstrateSpec {
      * wire; every existing `SubstrateSpec` construction still compiles.
      */
     agentBootstrap?: {
-        /** Host dir holding the helper script + token file + agent config (0700). */
+        /** Host dir holding the helper script + token file (0700). */
         hostDir: string;
         /** Read-only mount point inside the sandbox (NOT under the workdir). */
         sandboxDir: string;
     };
+    /**
+     * CP-7 PART D follow-up — mutable CLI config/runtime dir. Real agent CLIs
+     * create small startup/cache files beside their config (`CODEX_HOME`,
+     * `CLAUDE_CONFIG_DIR`). The broker-token helper stays in
+     * {@link agentBootstrap} and remains read-only; this separate dir is writable
+     * and contains only non-secret config/runtime state. It also lives outside the
+     * workdir so it never appears in diffs. LOCAL-ONLY; never on any wire.
+     */
+    agentConfig?: {
+        /** Host dir holding settings/config/runtime files (0700). */
+        hostDir: string;
+        /** Writable mount/grant point inside the sandbox. */
+        sandboxDir: string;
+    };
     /**
      * CP-7 W3 — Stage-2 r1 HIGH (A5 audit-readability). OPTIONAL, additive. The
      * RESOLVED per-task audit DIR (the sibling `.codevibe/audit/<group>/<track>/`
@@ -88,6 +101,22 @@ export interface SubstrateSpec {
      * construction still compiles (absent → no audit deny is emitted).
      */
     auditDir?: string;
+    /**
+     * A1d (design §8.1 — the write-capable resolver sandbox lattice). OPTIONAL,
+     * additive; A5-only (A1 ignores it — the docker row is never launched with an
+     * open posture). Network posture the Seatbelt profile emits:
+     *   - `'loopback'` (default, absent) — deny all network, re-allow loopback
+     *     only: the CP-7 broker tier (the agent's ONLY model path is the broker).
+     *   - `'open'` — deny inbound, allow ALL outbound: the RESOLVER-CONFINEMENT
+     *     row for a broker-less reduced-trust agent (agy/gemini) whose model call
+     *     dials its vendor DIRECTLY with its own file-based auth. The confinement
+     *     objective on that row is FS-WRITE confinement (writes stay strictly
+     *     inside the disposable merge workspace), not egress pinning — the engage
+     *     result carries a reduced-trust badge for the open egress.
+     * A LOCAL-ONLY field — never on any wire; every existing `SubstrateSpec`
+     * construction still compiles (absent → loopback, byte-identical profile).
+     */
+    networkPosture?: "loopback" | "open";
 }
 /**
  * A structural `ChildProcess` subset. The LE widens its internal child