@quantiya/codevibe-core 1.0.23 → 2.0.1

package/dist/orchestration/setup-test-agents.d.ts

@@ -0,0 +1,108 @@
+import { WizardSeatPick, WizardStepFailureReason } from './setup-types.js';
+import type { ReviewerSpec, ReviewerVerdict } from '../reviewer/index.js';
+/**
+ * Canned proposal — byte-identical across all installations. Locked
+ * 2026-05-03 per PHASE-3-A-DESIGN.md §3. Do NOT edit without going
+ * through a re-review of the entire Test My Agents protocol; the
+ * prose is part of the wizard's contract test surface (the new-contract
+ * row at PHASE-3-A-DESIGN.md:495 asserts byte-identicality).
+ *
+ * The proposal is intentionally trivial + read-only. The wizard does
+ * NOT actually create /tmp/quorum_test_hello.py — APPROVE is the
+ * expected outcome from a working reviewer.
+ */
+export declare const CANNED_PROPOSAL = "## Problem\nAdd a one-line Python \"Hello, World\" script to a new file.\n\n## Proposal\nCreate a single Python file at /tmp/quorum_test_hello.py containing the\nsingle line: print(\"hello world\")\n\n## Implementation Plan\n1. Create the file at /tmp/quorum_test_hello.py\n2. Write print(\"hello world\") on line 1 followed by a trailing newline\n3. Make no other changes\n\n## Expected Outputs\n- /tmp/quorum_test_hello.py \u2014 exists, contains the single-line script\n";
+/**
+ * Per-seat timeout. PHASE-3-A-DESIGN.md §6 "Timeout (60s/seat)".
+ * Conservative — gives a slow CLI room to start + respond on a
+ * cold-spawned reviewer process. Shorter would pollute the failure
+ * recourse menu with false positives on first-run latency.
+ */
+export declare const PER_SEAT_TIMEOUT_MS = 60000;
+/**
+ * Per-seat outcome rendered by the wizard. Returned by
+ * `runTestMyAgents` in the `seatOutcomes` array so the recourse menu
+ * can display each seat's status individually (per §3 "per-seat
+ * outputs ... are tagged with the seat ID and rendered together").
+ */
+export interface SeatOutcome {
+    seatId: number;
+    agent: WizardSeatPick['agent'];
+    role: WizardSeatPick['role'];
+    /** Wall-clock seconds elapsed for this seat's evaluate() call. */
+    elapsedSeconds: number;
+    /** Discriminated outcome — APPROVE plus the 6 failure shapes. */
+    result: {
+        kind: 'approve';
+    } | {
+        kind: 'revise';
+    } | {
+        kind: 'reject';
+    } | {
+        kind: 'escalate';
+    } | {
+        kind: 'parse_failure';
+    } | {
+        kind: 'spawn_failure';
+        reason: string;
+    } | {
+        kind: 'timeout';
+        elapsedMs: number;
+    } | {
+        kind: 'unknown_error';
+        message: string;
+    };
+}
+export type TestMyAgentsResult = {
+    ok: true;
+    seatOutcomes: SeatOutcome[];
+} | {
+    ok: false;
+    reason: WizardStepFailureReason;
+    canSaveAnyway: boolean;
+    seatOutcomes: SeatOutcome[];
+};
+/**
+ * Inputs for `runTestMyAgents`. The registry factory is injected so
+ * tests can swap in a mock; production passes
+ * `createSubprocessReviewerRegistry`.
+ */
+export interface TestMyAgentsDeps {
+    wizardRunId: string;
+    seats: WizardSeatPick[];
+    registryFactory?: () => {
+        evaluate: (spec: ReviewerSpec, gateId: string) => Promise<ReviewerVerdict>;
+    };
+    /**
+     * Status renderer. Tests pass a buffer; production passes a function
+     * that writes to process.stdout. Each call gets one line (no
+     * trailing newline added — caller controls).
+     */
+    write?: (line: string) => void;
+    /**
+     * Test seam: a synthetic gateId. Phase 3.a's wizard is wholly
+     * client-side (PHASE-3-A-DESIGN.md §5 "Wizard never spawns through
+     * OrchestrationClient.connect()"), so the gateId is a local
+     * synthetic UUID — providers echo it back on the verdict but the
+     * wizard does not persist it. Tests can pin a known value.
+     */
+    gateId?: string;
+}
+/**
+ * Run Step 2. Emits `wizard_step_started`, dispatches all seats in
+ * parallel via Promise.allSettled, classifies each outcome, emits
+ * `wizard_step_completed` (all APPROVE) or `wizard_step_failed` with
+ * the worst-blocker reason. Returns per-seat outcomes for the
+ * wizard's recourse renderer.
+ */
+export declare function runTestMyAgents(deps: TestMyAgentsDeps): Promise<TestMyAgentsResult>;
+/**
+ * Render a per-failure-kind explanatory sentence per the §6 outcome
+ * table + §1 line 140 "Display the structured error describing what
+ * failed" requirement. The wizard prints this before the recourse
+ * menu so users see WHY each non-APPROVE seat failed, not just a
+ * status line.
+ *
+ * R1 round-1 M3 (resolved 2026-05-08).
+ */
+export declare function humanizeStep2Failures(outcomes: SeatOutcome[]): string[];

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

@@ -0,0 +1,140 @@
+import type { ReviewerRole as PolicyReviewerRole } from '../reviewer/types.js';
+import type { AgentKind } from '../reviewer/types.js';
+import { AgentType } from '../types/session.js';
+import { ReviewerRole as SchemaReviewerRole } from '../types/reviewer.js';
+/**
+ * Tier returned by `getSubscriptionStatus`. Drives seat budget +
+ * tier-gate at bootstrap.
+ *
+ * UPPERCASE wire format matches `codevibe-backend/graphql/schema.graphql:209`
+ * (`enum SubscriptionTier { FREE PRO MAX }`).
+ */
+export type WizardTier = 'FREE' | 'PRO' | 'MAX';
+/**
+ * Tier-aware seat budget. Mirrors
+ * `codevibe-backend/lambda/user-management/index.ts:184-188`'s
+ * `REVIEWER_SEAT_COUNT` map. Free has no seats — orchestration is not
+ * permitted at that tier; the wizard short-circuits at bootstrap with
+ * the §6 upgrade interstitial.
+ */
+export declare const SEAT_BUDGET: Record<WizardTier, number | null>;
+/**
+ * The 3-role lock from PHASE-3-A-DESIGN.md: the wizard offers ONLY
+ * `architecture` / `correctness` / `security`. The schema's
+ * `ReviewerRole` enum at `codevibe-backend/graphql/schema.graphql:167-177`
+ * still has 9 variants for backward compat / 2.0.x custom-roles
+ * (#80) — but the wizard NEVER sends a non-3-role seat to
+ * `updateReviewerPolicy`.
+ *
+ * snake_case matches `codevibe-core/src/reviewer/types.ts:52-61` (the
+ * reviewer-module wire). The wizard converts to AppSync UPPERCASE at
+ * the save boundary via `roleToAppSync()`.
+ */
+export declare const WIZARD_ROLES: readonly ["architecture", "correctness", "security"];
+export type WizardRole = (typeof WIZARD_ROLES)[number];
+/**
+ * Tier-aware default role for each seat (§1 "Default-role fallback").
+ * Seat 0 = architecture, Seat 1 = correctness, Seat 2 = security.
+ * When the canonical default is already taken by a previous seat, the
+ * wizard falls back to the first remaining role in canonical order.
+ */
+export declare const DEFAULT_ROLE_BY_SEAT: WizardRole[];
+/**
+ * Canonical agent ordering used for wizard defaults. The first
+ * installed agent in this order is the default for each seat unless
+ * the user picks otherwise.
+ */
+export declare const AGENT_PRIORITY: AgentKind[];
+/**
+ * The wizard's terminal outcomes. Drives `wizard_completed` /
+ * `wizard_aborted` GA4 events and the exit code.
+ */
+export type WizardOutcome = {
+    kind: 'ok';
+    saved: true;
+    seats: ReadonlyArray<WizardSeatPick>;
+} | {
+    kind: 'saved_after_test_warning';
+    saved: true;
+    seats: ReadonlyArray<WizardSeatPick>;
+} | {
+    kind: 'aborted';
+    reason: WizardAbortReason;
+    lastStep: WizardStep;
+};
+/**
+ * Reasons the wizard exited without saving. Mirror the
+ * `wizard_aborted.reason` taxonomy in PHASE-3-A-DESIGN.md §7.
+ */
+export type WizardAbortReason = 'ctrl_c' | 'tier_gate_free' | 'no_clis' | 'step_user_exit' | 'step_save_failed_exit' | 'auth_expired' | 'bootstrap_failure';
+/**
+ * Wizard step taxonomy — used for `wizard_step_started`/`completed`/
+ * `failed` and `wizard_aborted.last_step`.
+ */
+export type WizardStep = 'bootstrap' | 'seat_assignment' | 'test_my_agents' | 'save';
+/**
+ * Per-step `wizard_step_failed.reason` codes. Mirror the table in
+ * PHASE-3-A-DESIGN.md §7. Each step has its own bounded reason set;
+ * `seat_assignment` has no failure modes (the picker filters out
+ * invalid choices UI-side).
+ */
+export type WizardStepFailureReason = 'tier_gate_free' | 'not_signed_in' | 'subscription_status_network' | 'no_clis_installed' | 'test_revise' | 'test_reject' | 'test_escalate' | 'test_parse_failure' | 'test_spawn_failure' | 'test_timeout' | 'update_policy_network' | 'update_policy_5xx' | 'update_policy_throttle' | 'auth_token_expired';
+/**
+ * One seat the user picked in Step 1. The wizard converts these to
+ * `ReviewerAgentSpecInput[]` at save time by uppercase-mapping role +
+ * agent (the schema's wire form).
+ */
+export interface WizardSeatPick {
+    seatId: number;
+    agent: AgentKind;
+    role: WizardRole;
+}
+/**
+ * Latency bucket for GA4 `latency_bucket_s` / `total_latency_bucket_s`
+ * dimensions. Bounded set — keeps GA4 cardinality tractable per R2
+ * round-1 MEDIUM (PHASE-3-A-DESIGN.md §7).
+ */
+export type LatencyBucket = '<2' | '2-5' | '5-10' | '10-30' | '30+';
+/**
+ * Categorical bucket for "how many agents are installed" /
+ * "how many seats". Locked at "1" / "2" / "3" — there is no "4+"
+ * because Max is the ceiling.
+ */
+export type CountBucket = '1' | '2' | '3';
+/**
+ * Entry point identifier — distinguishes meta CLI invocation from
+ * each plugin's alias (`codevibe-{claude,gemini,codex} orchestration setup`).
+ */
+export type WizardEntry = 'meta_cli' | 'claude_alias' | 'gemini_alias' | 'codex_alias';
+/**
+ * Bucket a wall-clock duration into one of the 5 latency-bucket values.
+ * Used by telemetry for per-step + total-wizard timing dimensions.
+ */
+export declare function bucketLatencySeconds(seconds: number): LatencyBucket;
+/**
+ * Bucket an integer count into "1" / "2" / "3", clamping anything
+ * higher to "3". Used for `seats_bucket`, `agents_distinct_bucket`,
+ * `roles_distinct_bucket`, `installed_agents_bucket`.
+ */
+export declare function bucketCount(n: number): CountBucket;
+/**
+ * Map a wizard role (snake_case) to the reviewer-module's snake_case
+ * `ReviewerRole` literal type — used when building a `ReviewerSpec`
+ * for `createSubprocessReviewerRegistry().evaluate()`. Pass-through
+ * because `WizardRole` is a strict subset of `PolicyReviewerRole`.
+ */
+export declare function roleToReviewerSpec(role: WizardRole): PolicyReviewerRole;
+/**
+ * Map a wizard role (snake_case) to the AppSync schema's UPPERCASE
+ * `ReviewerRole` enum — used when building a `ReviewerAgentSpecInput`
+ * for the `updateReviewerPolicy` mutation. The wizard locks to 3
+ * roles, so this mapping is exhaustive over `WizardRole` and never
+ * produces one of the 6 non-3-role variants.
+ */
+export declare function roleToAppSync(role: WizardRole): SchemaReviewerRole;
+/**
+ * Map AgentKind (lowercase reviewer-module wire) to the AppSync
+ * `AgentType` enum (UPPERCASE). Used at save time when building the
+ * `ReviewerAgentSpecInput[]` for `updateReviewerPolicy`.
+ */
+export declare function agentToAppSync(agent: AgentKind): AgentType;

package/dist/orchestration/setup-wizard.d.ts

@@ -0,0 +1,57 @@
+import { DetectableAgent } from './detect-agents.js';
+import { WizardEntry } from './setup-types.js';
+import { PickerIO } from './setup-seat-picker.js';
+import { AppSyncClient } from '../appsync/appsync-client.js';
+import type { ReviewerSpec, ReviewerVerdict } from '../reviewer/index.js';
+/**
+ * Parse `--entry=<value>` from argv. Defaults to `meta_cli` if absent
+ * or invalid. Plugin wrappers pass `--entry=claude_alias` /
+ * `gemini_alias` / `codex_alias` per the §4 alias contract.
+ */
+export declare function parseEntry(argv: string[]): WizardEntry;
+/**
+ * Injectable dependencies for `runSetupWizardWithDeps`. Factored out
+ * so unit tests can drive the whole state machine deterministically
+ * (no real readline, no real subprocess spawn, no real network).
+ *
+ * Production callers use `runSetupWizard`, which wires the production
+ * deps + calls `process.exit(result.exitCode)`.
+ */
+export interface SetupWizardDeps {
+    /** Builds an authenticated AppSyncClient or returns null if unauthenticated. */
+    clientFactory: () => Promise<AppSyncClient | null>;
+    /** Returns the subset of agents present on PATH. */
+    agentDetector: () => DetectableAgent[];
+    /** Optional reviewer registry (Step 2). Default: real subprocess registry. */
+    registryFactory?: () => {
+        evaluate: (spec: ReviewerSpec, gateId: string) => Promise<ReviewerVerdict>;
+    };
+    /** Output writer — writes the line as-is (caller controls newlines). */
+    write: (line: string) => void;
+    /** Build a fresh PickerIO + close handle for the next interactive prompt. */
+    createPickerIO: () => {
+        io: PickerIO;
+        close: () => void;
+    };
+}
+/**
+ * Result of the wizard's state machine. The public `runSetupWizard`
+ * wrapper translates this to a `process.exit(exitCode)`.
+ */
+export interface SetupWizardResult {
+    exitCode: number;
+}
+/**
+ * Production entry point. Called from `runOrchestrationCli` when
+ * `argv[3] === 'setup'`. Builds production deps + calls process.exit
+ * with the wizard's exit code. Drives the full state machine via
+ * `runSetupWizardWithDeps`.
+ */
+export declare function runSetupWizard(argv: string[]): Promise<void>;
+/**
+ * Testable wizard core. Exits with code 0 on success or any user-
+ * initiated abort; exit 1 on a failure the user couldn't recover
+ * from in the recourse loop. SIGINT is registered + cleaned up
+ * around the call (no-op for tests when SIGINT is never fired).
+ */
+export declare function runSetupWizardWithDeps(argv: string[], deps: SetupWizardDeps): Promise<SetupWizardResult>;

package/dist/orchestration/v1-options.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Discriminator value emitted by the engine on
+ * `metadata.prompt_kind` for orchestration-escalated gate prompts.
+ *
+ * Sources of truth (any drift breaks the V1 bridge):
+ *   - Engine emit: codevibe-core-rs `appsync_emit.rs:847-862`
+ *     (`build_metadata_json` — emits exactly 5 keys: `tool_name`,
+ *     `payload`, `prompt_kind`, `summary`, `timeline`).
+ *   - iOS branch: MessageBubble.swift `extractInteractivePromptOptions`.
+ *   - Android branch: MessageBubble.kt `extractOptions`.
+ */
+export declare const V1_ORCHESTRATION_PROMPT_KIND: "orchestration_escalated_gate";
+/**
+ * V1 user-decision kind (3-position subset of the 5-kind enum).
+ *
+ * Lowercase snake_case matches `@quantiya/quorum-core`'s `UserDecisionKind`
+ * caller-facing type at `codevibe-core-rs/packages/quorum-core/src/types.ts:232-238`.
+ * The quorum-core SDK's `applyUserDecision` mutator accepts this lowercase
+ * form and internally uppercases via `toWireEnum` before AppSync wire-send
+ * (`client.ts:244-246` + line 474). Plugins pass lowercase; the SDK is the
+ * conversion layer.
+ *
+ * iOS + Android pin UPPERCASE in their own enums because they call AppSync
+ * GraphQL directly via Amplify (no SDK conversion layer in their path).
+ * Both are correct at their respective layers.
+ *
+ * The two `_WITH_NOTES` variants from the full 5-kind enum are V2 — they
+ * require a `notes: EncryptedPayloadInput` value alongside the kind, and
+ * V1's "type a number" UX has no notes-input surface. They are deliberately
+ * EXCLUDED from this union; `mapOptionNumberToUserDecisionKind` cannot
+ * return them.
+ */
+export type V1UserDecisionKind = 'accept' | 'reject_restart' | 'abort_task';
+/**
+ * One row of the V1 orchestration option table.
+ *
+ * `number` is a string (`"1"` / `"2"` / `"3"`) to match iOS' tuple shape
+ * `(number: String, text: String)` and the existing
+ * `InteractivePromptOption` shape elsewhere in the mobile renderers.
+ */
+export interface V1OrchestrationOption {
+    readonly number: string;
+    readonly label: string;
+    readonly kind: V1UserDecisionKind;
+}
+/**
+ * The V1 hardcoded 3-position option table.
+ *
+ * Order is LOAD-BEARING — `V1_ORCHESTRATION_OPTIONS[i].kind` is the kind
+ * sent to the server when the user types option-number `i+1`. Drift from
+ * iOS / Android = wrong `UserDecisionKind` on the wire (engine has no
+ * server-side validation).
+ *
+ *   position 1 -> accept          -> "Accept"
+ *   position 2 -> reject_restart  -> "Reject (restart proposal)"
+ *   position 3 -> abort_task      -> "Abort task"
+ *
+ * (Kind values are lowercase to match the SDK caller-facing type — see
+ * the header comment on the SDK conversion layer. iOS + Android pin
+ * UPPERCASE in their own constant tables because they hit AppSync
+ * directly without the SDK.)
+ *
+ * Frozen with `as const` so callers cannot mutate the array nor swap
+ * entries in place at runtime.
+ */
+export declare const V1_ORCHESTRATION_OPTIONS: readonly [
+    V1OrchestrationOption,
+    V1OrchestrationOption,
+    V1OrchestrationOption
+];
+/**
+ * Map a 1-based option number typed by the user to the matching V1
+ * `UserDecisionKind`. Returns `null` for ANY number outside 1..3 —
+ * callers MUST surface an error and abort the submit on null (the
+ * engine would reject `_WITH_NOTES` kinds without a notes payload in
+ * V1, and ANY out-of-range number means the user hit a typo, an
+ * accidental keystroke, or a malformed prompt).
+ *
+ * Out-of-range MUST return null — NOT fall back to `ACCEPT` or any
+ * default. A silent fallback would silently destroy or accept the
+ * user's work without their consent. Pinned by the
+ * `out-of-range returns null` test.
+ *
+ * @param optionNumber 1-based option position as typed by the user.
+ * @returns The matching `V1UserDecisionKind`, or `null` when out of range.
+ */
+export declare function mapOptionNumberToUserDecisionKind(optionNumber: number): V1UserDecisionKind | null;
+/**
+ * Shorter alias of `mapOptionNumberToUserDecisionKind`. Matches the helper
+ * name used in `PHASE-3-B-MOBILE-V1-BRIDGE-DESIGN.md` §3.1 + §6 Test 9 +
+ * §8 source-map row (`mapOptionToUserDecisionKind`). Both names point at
+ * the same function — pick whichever reads cleaner at the call site.
+ *
+ * Plugins can `import { mapOptionToUserDecisionKind }` per the design
+ * doc's call-site example at §3.1.
+ */
+export declare const mapOptionToUserDecisionKind: typeof mapOptionNumberToUserDecisionKind;

package/dist/orchestration-shell/__tests__/cli-authority-bridge.test.d.ts

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

package/dist/orchestration-shell/__tests__/cli-planner-stack.test.d.ts

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

package/dist/orchestration-shell/__tests__/cli-singleton-enforcement.test.d.ts

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

package/dist/orchestration-shell/__tests__/cli-stub-session-adapter.test.d.ts

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

package/dist/orchestration-shell/__tests__/components.test.d.ts

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

package/dist/orchestration-shell/__tests__/emit-shell-event.test.d.ts

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

package/dist/orchestration-shell/__tests__/gate-prompts.test.d.ts

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

package/dist/orchestration-shell/__tests__/hostile-grep.test.d.ts

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

package/dist/orchestration-shell/__tests__/mode-selection.test.d.ts

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

package/dist/orchestration-shell/__tests__/process-markers.test.d.ts

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

package/dist/orchestration-shell/__tests__/reducer.test.d.ts

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

package/dist/orchestration-shell/__tests__/runOrchestrationShell-classify-dispatch.test.d.ts

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

package/dist/orchestration-shell/__tests__/runOrchestrationShell-planner-wiring.test.d.ts

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

package/dist/orchestration-shell/__tests__/runOrchestrationShell-signal.test.d.ts

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

package/dist/orchestration-shell/__tests__/runOrchestrationShell.test.d.ts

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

package/dist/orchestration-shell/__tests__/slash-router.test.d.ts

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

package/dist/orchestration-shell/__tests__/sticky-preference.test.d.ts

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

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

@@ -0,0 +1,96 @@
+import { AppSyncClient } from '../appsync';
+import { Session } from '../types';
+import { type ShellEventEmit } from './emit-shell-event';
+import { BackendPlannerClient, PlannerCacheLayer, PlannerHealthMachine } from '../planner';
+import type { PlannerAdapter, PlannerInput, PlannerDecision, PlannerProbeResult } from '../planner/adapter';
+/**
+ * CP-1.b IMPL r5 H-1 — Sentinel error thrown by the stub-session
+ * planner adapter. `handleShellUserInput` catches this typed class and
+ * routes it through the explicit error renderer (SLASH_OUTPUT) so the
+ * user sees an actionable message in the conversation pane instead of
+ * a silent log line. Stub sessions (sessionId prefix `cp1a-local-` or
+ * empty `encryptedKeys`) cannot reach the Lambda — `encryptedKeys` is
+ * missing, the keychain resolver returns null, and the planner client
+ * throws "session key unresolved" deep inside classify(). Surfacing
+ * that as a typed error at the adapter boundary is cleaner than the
+ * generic Error from `BackendPlannerClient.classify()`.
+ */
+export declare class PlannerUnavailableError extends Error {
+    constructor(msg: string);
+}
+/**
+ * CP-1.b IMPL r5 H-1 — Stub-session planner adapter.
+ *
+ * CP-1.a still ships a fake `cp1a-local-*` session with no
+ * `encryptedKeys[]`. The production `BackendPlannerClient` cannot
+ * classify against that session — the Lambda requires E2E-encrypted
+ * payloads, which requires the session key, which the keychain
+ * resolver cannot derive without `encryptedKeys`.
+ *
+ * Rather than wire up the production stack and let it fail with a
+ * generic "session key unresolved" Error deep inside classify(), we
+ * detect stub sessions at bootstrap and construct this adapter, which
+ * throws a typed `PlannerUnavailableError` on classify(). The shell's
+ * `handleShellUserInput` catches this and renders an actionable
+ * message to the user (`PLANNER_UNAVAILABLE: <reason>`). CP-1.c lands
+ * the real session bootstrap (resumeOrCreateSession + AppSync) and
+ * this adapter is no longer wired in.
+ */
+export declare class PlannerUnavailableAdapter implements PlannerAdapter {
+    private readonly reason;
+    private activeSessionId;
+    constructor(reason: string);
+    classify(_input: PlannerInput): Promise<PlannerDecision>;
+    probe(): Promise<PlannerProbeResult>;
+    setActiveSession(sessionId: string | null): void;
+}
+/**
+ * CP-1.b IMPL r5 H-1 — Detect a CP-1.a stub session. Two signals:
+ *   (a) `sessionId` starts with `cp1a-local-` (the
+ *       `buildStubSession()` prefix).
+ *   (b) `session.encryptedKeys` is empty / missing (any session
+ *       lacking E2E keys cannot route through the Lambda).
+ *
+ * Either signal triggers the stub-session adapter. The (b) gate is
+ * a defensive fallback for the case where CP-1.c starts a real
+ * session bootstrap but `prepareSessionEncryption()` returns null
+ * (no device keys registered): the planner is genuinely unavailable
+ * until the user registers a device key.
+ */
+export declare function isStubSession(session: Session): boolean;
+export declare function main(argv: string[]): Promise<number>;
+/**
+ * CP-1.b IMPL r4 H-1 — Production planner stack factory.
+ *
+ * Builds the full BackendPlannerClient + PlannerCacheLayer +
+ * PlannerHealthMachine chain so the orchestration shell can call
+ * `plannerAdapter.classify()` on natural-language input.
+ *
+ * Co-located with the CLI bootstrap (NOT inside `runOrchestrationShell`)
+ * because the shell accepts an injected adapter for tests; the
+ * production bootstrap site is the single canonical instantiation
+ * point.
+ *
+ * Exported for unit tests; production callers go through `main()`.
+ */
+export declare function buildProductionPlannerStack(appsyncClient: AppSyncClient, emitter: (args: ShellEventEmit) => Promise<void>): {
+    adapter: BackendPlannerClient;
+    cache: PlannerCacheLayer;
+    health: PlannerHealthMachine;
+};
+import { HookBridge } from '../local-executor/hook-bridge';
+export interface BridgeRefusalArgs {
+    refusedMessageId: string;
+    shellContent: string;
+    shellMetadata?: Record<string, unknown>;
+}
+/**
+ * Wrap any async operation that may throw `AuthorityError`; on refusal, emit
+ * the two-channel refusal pair (LOCK #C4-3) via the supplied HookBridge and
+ * re-throw. Non-AuthorityError exceptions propagate unchanged.
+ *
+ * The HookBridge passed in MUST be the same instance the orchestration shell
+ * uses for plugin-hook ingestion — both paths share the audit-before-shell
+ * ordering invariant via the bridge's `bridgeAuthorityRefusal` method.
+ */
+export declare function bridgeAuthorityErrorToShellRefusal<T>(bridge: HookBridge, refusalArgs: BridgeRefusalArgs, fn: () => Promise<T>): Promise<T>;