@quantiya/codevibe-core 2.0.0 → 2.0.2

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

@@ -0,0 +1,431 @@
+import { AppSyncClient } from '../appsync';
+import { Session } from '../types';
+import { Mode, Tier } from './types';
+import { type RunOrchestrationShellArgs } from './index';
+import { type ShellEventEmit } from './emit-shell-event';
+import { BackendPlannerClient, PlannerCacheLayer, PlannerHealthMachine, type LocalGemmaAdvisoryRunner, type LocalGemmaPlannerRunner } from '../planner';
+import type { PlannerAdapter, PlannerInput, PlannerDecision, PlannerProbeResult } from '../planner/adapter';
+import { type LocalExecutor, type AuthorityScope, type EmitShellEventFn as LEEmitShellEventFn } from '../local-executor';
+import { type EngineGroupState } from '../local-executor';
+import type { TeamTapEvent } from './index';
+import type { GroupDecisionSubmitDeps } from './gate-decision-submit';
+import { QuorumLoop } from './quorum-loop';
+import type { TaskProgressEvent } from './task-progress';
+import { type VerdictClassifier } from '../reviewer/verdict-classifier';
+import { type LocalModelArtifactConfig, type LocalModelCommand, type LocalModelEntitlement, type LocalModelStore } from '../local-model/manager';
+import { type LocalModelState } from '../local-model/state';
+/**
+ * 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;
+}
+/**
+ * Local-LLM planner placeholder for the Gemma QAT migration slice. This adapter
+ * is intentionally local-only: it never calls AppSync planner mutations or any
+ * hosted fallback. Until the verified Gemma runner is wired, natural-language
+ * planning requests fail closed with an actionable shell message.
+ */
+export declare class LocalModelPlannerUnavailableAdapter implements PlannerAdapter {
+    private readonly reason;
+    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 buildStubSessionShellArgs(args: Omit<RunOrchestrationShellArgs, 'disableStructuralContextRefresh'>): RunOrchestrationShellArgs;
+/**
+ * CP-1.f §3.C.19 — resolve a REAL backend session for the orchestration loop
+ * (closes #513). When authenticated:
+ *   1. resume the user's most-recent ACTIVE session via `getSession` (which
+ *      returns `encryptedKeys`) AND warm the session-key cache from them so the
+ *      QuorumLoop's `getSessionKey` is non-null, OR
+ *   2. create a new orchestration session with the FULL E2E bootstrap
+ *      (`prepareSessionEncryption` → `createSession` with isEncrypted /
+ *      encryptedKeys / creatorDeviceId / encryptionVersion → `cacheSessionKey`),
+ *      so the orchestration/planner-proxy Lambda is a recipient in
+ *      `Session.encryptedKeys` (can decrypt encProposal/verdict) AND the local
+ *      key cache is warm. Stage-1 FIX 1 — replaces the prior crypto-dropping
+ *      `createSession` reimplementation that hung the loop ("no session key").
+ * Falls back to `buildStubSession()` when unauthenticated / offline / on any
+ * error — the stub-session guards downstream keep that path fully usable.
+ *
+ * The tier is resolved here too (§3.C.19): a `CODEVIBE_TIER` env override wins
+ * (the dev/dogfood lever), else `getSubscriptionStatus`, else FREE (fail-closed
+ * — Orchestration Mode is never surfaced to Free).
+ */
+export declare function resumeOrCreateSession(appsyncClient: AppSyncClient, deps?: {
+    resolveSessionIdFn?: (client: AppSyncClient) => Promise<string | null>;
+}): Promise<{
+    session: Session;
+    tier: Tier;
+}>;
+/**
+ * CP-8 Slice C (#570) — parse a top-level `audit show <task-id> [--json]
+ * [--session <id>]` subcommand from the raw argv. Returns null when the argv is
+ * NOT an audit subcommand (so `main` falls through to mode selection). Detected
+ * BEFORE the mode parse so `audit` isn't swallowed as a passthrough arg.
+ */
+export interface ParsedAuditArgs {
+    taskId: string;
+    json: boolean;
+    /** Explicit session override; when absent the runner resolves the active session. */
+    sessionId?: string;
+}
+export declare function parseAuditArgs(argv: string[]): ParsedAuditArgs | null;
+export interface ParsedModelArgs {
+    command: LocalModelCommand | 'help';
+    viaWithLocalModelFlag: boolean;
+}
+/**
+ * Parse local-model meta commands before mode selection. These commands must
+ * not be swallowed as Companion passthrough args, because the entitlement gate
+ * has to run before any model download, warmup, or health check can start.
+ */
+export declare function parseModelArgs(argv: string[]): ParsedModelArgs | null;
+export declare function runModelCli(parsed: ParsedModelArgs, deps?: {
+    appsyncClient?: AppSyncClient;
+    resolveEntitlement?: () => Promise<LocalModelEntitlement>;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+}): Promise<number>;
+export interface LocalModelBootDecision {
+    mode: Mode;
+    notice: string | null;
+}
+export declare function resolveLocalModelBoot(args: {
+    requestedMode: Mode;
+    entitlement: LocalModelEntitlement;
+    state: LocalModelState;
+}): LocalModelBootDecision;
+export interface LocalGemmaPlannerBuildResult {
+    adapter: PlannerAdapter;
+    advisoryRunner: LocalGemmaAdvisoryRunner | null;
+    /**
+     * REVIEWER-VERDICT-GEMMA-CLASSIFIER-DESIGN.md (§Wiring) — the SAME resolved
+     * Gemma runner instance as {@link advisoryRunner} (both `null` on the unavailable
+     * path), exposed with the wider `LocalGemmaPlannerRunner` type (it carries
+     * `classify`, which the verdict classifier needs; `advisoryRunner` keeps the
+     * stricter `LocalGemmaAdvisoryRunner` type its consumer requires). One instance ⇒
+     * a SINGLE availability source for both the planner and the verdict classifier —
+     * they can never disagree about whether Gemma is up.
+     */
+    classifyRunner: LocalGemmaPlannerRunner | null;
+    runtimeKind: NonNullable<RunOrchestrationShellArgs['plannerRuntimeKind']>;
+    /**
+     * TUI redesign (2026-06-29) — display label for the status-bar planner badge
+     * (model name, tag-stripped, e.g. `gemma4`). Derived even on the unavailable
+     * path so the degraded badge can still name the intended model.
+     */
+    runtimeLabel: string;
+    reason: string | null;
+}
+export declare function buildLocalGemmaPlannerAdapter(args: {
+    state: LocalModelState;
+    config?: LocalModelArtifactConfig;
+    store?: LocalModelStore;
+    env?: NodeJS.ProcessEnv;
+}): Promise<LocalGemmaPlannerBuildResult>;
+/**
+ * CP-8 Slice C (#570) — the meta-CLI `codevibe audit show <task-id> [--json]`
+ * entrypoint. Authenticates the AppSync client (mirrors the `main()` auth
+ * wiring), resolves the task's session id (explicit `--session` OR the most
+ * recent ACTIVE session), runs the Max-gated browser, and prints either the
+ * JSON model (`--json`) or a readable newest-first timeline (default).
+ *
+ * Returns a process exit code (0 = printed something the user expects; 2 =
+ * usage error). The Max interstitial + error empty-state are NOT failures —
+ * they print and return 0.
+ *
+ * Exported for unit tests; production goes through `main()`.
+ */
+export declare function runAuditCli(parsed: ParsedAuditArgs, deps?: {
+    appsyncClient?: AppSyncClient;
+    /** Test seam — overrides the active-session resolution. */
+    resolveSessionIdFn?: (client: AppSyncClient) => Promise<string | null>;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+}): Promise<number>;
+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;
+};
+export interface BuildTeamLocalExecutorResult {
+    localExecutor: LocalExecutor;
+    teamShellEventTap: {
+        fn: (args: TeamTapEvent) => void;
+    };
+    /**
+     * CP-1.f §3.C — the reviewer-quorum loop driver, constructed alongside the LE
+     * and wired into the LE's Class B consumer (real Ed25519 verify +
+     * REVIEWER_DISPATCH spawnReviewers + REVISE_FEEDBACK runReviseRound).
+     * `runOrchestrationShell` threads it for start_task START + reconnect recovery.
+     */
+    quorumLoop: QuorumLoop;
+    /**
+     * CP-1.f live progress surfacing — the progress tap holder (see
+     * `BuildQuorumLoopExecutorResult.progressTap`).
+     */
+    progressTap: ProgressTap;
+    /**
+     * Audited-path fix (Fix 1) — the PolicyRejection tap holder (see
+     * `BuildQuorumLoopExecutorResult.policyRejectionTap`).
+     */
+    policyRejectionTap: PolicyRejectionTap;
+    /**
+     * PHASE-589/469 W3.2 — the two-phase group-escalation decision deps (WITHOUT
+     * the store; `runOrchestrationShell` completes it). Threaded into
+     * `gateDecisionDeps.groupDecision` so a synthesized `task_group_halted`
+     * 5-option prompt resolves through `submitGroupDecision`.
+     */
+    groupDecisionDeps: Omit<GroupDecisionSubmitDeps, 'store'>;
+    /**
+     * PHASE-589/469 W3.1 (C4) — the startup reconcile-before-GC over the durable
+     * revert manifests. `runOrchestrationShell` awaits it ONCE at team-wiring
+     * startup, BEFORE the live Class B loop consumes packets.
+     */
+    reconcileRevertManifests: () => Promise<void>;
+}
+/**
+ * CP-1.f live progress surfacing — the desktop-local progress tap holder
+ * (mirrors `teamShellEventTap`). `cli.ts` builds it with a no-op `fn`; the
+ * QuorumLoop's `onProgress` calls `progressTap.fn(event)`, and
+ * `runOrchestrationShell` installs the store-dispatching `fn` at startup. Until
+ * then (and for non-loop sessions) the `fn` is inert. The loop also wraps every
+ * emit so a throwing `fn` can never break the loop.
+ */
+export interface ProgressTap {
+    fn: (event: TaskProgressEvent) => void;
+}
+/**
+ * Audited-path fix (Fix 1) — the PolicyRejection tap holder (mirrors
+ * `progressTap`). `cli.ts` builds it with a no-op `fn`; the LE's
+ * `onPolicyRejection` dep calls `policyRejectionTap.fn(info)`, and
+ * `runOrchestrationShell` installs the store-dispatching `fn` (a classified
+ * `SHELL_ADVISORY`) at startup. Until then (and for non-loop sessions) the `fn`
+ * is inert. The shadow-discard side is handled inside `cli.ts`'s wiring (it has
+ * the QuorumLoop reference); this tap carries ONLY the user-visible advisory.
+ */
+export interface PolicyRejectionTap {
+    fn: (info: {
+        detail: string;
+        category: string;
+        recommendedRecovery: string;
+    }) => void;
+}
+/**
+ * [Gemma classifier · D11 + §Wiring] Resolve the reviewer verdict classifier
+ * threaded onto `QuorumLoopDeps.classifyVerdict`.
+ *
+ *  - `classifyRunner === undefined` → the classifier is NOT wired (unit tests /
+ *    the canned-prompt legacy paths the design leaves on regex) → `undefined`
+ *    (the provider uses `parseVerdictOutput`). Production ALWAYS wires it (a
+ *    `LocalGemmaPlannerRunner | null`), so this branch never fires in production.
+ *  - `CODEVIBE_REVIEWER_VERDICT_CLASSIFIER=regex` → `undefined` (the ONLY operator
+ *    revert to the regex parser). Any other value (incl. a typo) stays `gemma` so
+ *    a mistyped flag can NEVER silently disable the fail-closed classifier.
+ *  - `gemma` (default) → the real fail-closed Gemma classifier when the runner is
+ *    present; a dummy always-ESCALATE classifier when it is `null` (Ollama
+ *    unreachable at boot) — NEVER a silent regex fallback (agy-MED-1).
+ */
+export declare function resolveVerdictClassifier(classifyRunner: LocalGemmaPlannerRunner | null | undefined, env?: NodeJS.ProcessEnv): VerdictClassifier | undefined;
+export interface BuildQuorumLoopExecutorResult {
+    localExecutor: LocalExecutor;
+    quorumLoop: QuorumLoop;
+    /**
+     * CP-1.f live progress surfacing — the progress tap holder. `cli.ts` threads
+     * it into `runOrchestrationShell`, which installs the store-dispatching `fn`.
+     */
+    progressTap: ProgressTap;
+    /**
+     * Audited-path fix (Fix 1) — the PolicyRejection tap holder. `cli.ts` threads
+     * it into `runOrchestrationShell`, which installs the store-dispatching `fn`
+     * (a classified `SHELL_ADVISORY`).
+     */
+    policyRejectionTap: PolicyRejectionTap;
+}
+/**
+ * CP-1.f §3.C — Stage-2 r2 (Codex) FIX B. Construct the SINGLE-TASK QuorumLoop +
+ * its driving LE for a non-team orchestration session (Pro OR Max-without-teams).
+ *
+ * The single-implementor reviewer-quorum loop is a Pro+Max feature (Pro = 2
+ * seats, Max = 3 seats per `codevibe-policy`); only Agent Teams / MergeGate
+ * (CP-12) is Max-only. Before this fix the QuorumLoop was built ONLY inside
+ * `buildTeamLocalExecutor` (gated on `tier === 'MAX'`), so a real Pro
+ * orchestration session got NO loop → `start_task` silently no-op'd (the only
+ * `start_task` execution branch requires `args.quorumLoop`).
+ *
+ * The LE here is a MINIMAL single-track LE — it OMITS every team dep
+ * (`spawnTrackImplementor` / `buildTrackArgv` / `appsyncClient` / `repoRoot` /
+ * `deviceSigningKey` / `teamSessionKeyB64` / …), so `teamModeEnabled` is FALSE
+ * (a teams Class B packet is dropped, not acted on). It KEEPS the 4
+ * reviewer-quorum consumer deps (so the loop receives GATE_DISPATCH /
+ * REVIEWER_DISPATCH / REVISE_FEEDBACK) + the substrate engager (so the
+ * implementor still spawns inside the CP-7 moat). The shell wires the returned
+ * `localExecutor` for the Class B subscription + `quorumLoop` for start_task +
+ * reconnect recovery, EXACTLY as the team path does.
+ *
+ * Exported for unit tests; production goes through `main()`.
+ */
+export declare function buildQuorumLoopExecutor(args: {
+    appsyncClient: AppSyncClient;
+    session: Session;
+    emitter: (args: ShellEventEmit) => Promise<void>;
+    /** CP-1.f LOCK RP-6 — host-detected agents threaded into the loop. */
+    detectedAgents?: string[];
+    /** #585 auto-continuation (Max) — the resolved tier, threaded to the loop. */
+    tier?: Tier;
+    /**
+     * [Gemma classifier · §Wiring] The resolved Gemma runner (same instance as the
+     * planner's), forwarded to `buildAndArmQuorumLoop` where the verdict classifier is
+     * built. ABSENT (tests) → the classifier is not wired → regex parser.
+     */
+    classifyRunner?: LocalGemmaPlannerRunner | null;
+}): Promise<BuildQuorumLoopExecutorResult>;
+/**
+ * PHASE-589+469 W2 (#TC-5) — map an LE hook-bridge event to the chokepoint's
+ * `ShellEventEmit`. The team-result summary (`ASSISTANT_RESPONSE`, from
+ * `emitGroupConvergence`) KEEPS its type AND forwards `content` (the
+ * light-markdown digest the phone renders); `LOCAL_AUTHORITY_REFUSAL` maps 1:1;
+ * every other type is coerced to `NOTIFICATION` (audit fallback — those never
+ * occur on the team paths). Exported so the #TC-5 test drives the REAL mapping
+ * (not a reproduction): a regression that dropped the `ASSISTANT_RESPONSE` type
+ * or its `content` — which would silently make the mobile summary dead — is
+ * caught here.
+ */
+export declare function mapTeamLeEventToShellEmit(e: Parameters<LEEmitShellEventFn>[0]): ShellEventEmit;
+/**
+ * Construct the team-mode LocalExecutorImpl + the store-tap holder. Returns the
+ * pair `runOrchestrationShell` consumes (`localExecutor` + `teamShellEventTap`).
+ *
+ * Exported for the W3 E2E smoke (which injects stub deps) + future callers;
+ * production goes through `main()`.
+ */
+export declare function buildTeamLocalExecutor(args: {
+    appsyncClient: AppSyncClient;
+    session: Session;
+    emitter: (args: ShellEventEmit) => Promise<void>;
+    initialScope: AuthorityScope;
+    /** CP-1.f LOCK RP-6 — host-detected agents threaded into the loop. */
+    detectedAgents?: string[];
+    /** #585 auto-continuation (Max) — the resolved tier, threaded to the loop. */
+    tier?: Tier;
+    /**
+     * TEST SEAM — override the durable revert-manifest store root. Production omits it
+     * (defaults to the shared `~/.codevibe/revert-state/`). Tests pass an ISOLATED temp
+     * dir so the CLAIM→revert→COMMIT flow can't be contaminated by another test's
+     * leftover manifest/journal in the shared root (which stranded the COMMIT phase →
+     * `['claim']` in the full suite while passing in isolation), and so a sandboxed
+     * runner that can't write `~/.codevibe` doesn't EPERM.
+     */
+    durableRootDir?: string;
+    /**
+     * [Gemma classifier · §Wiring] The resolved Gemma runner (same instance as the
+     * planner's), forwarded to `buildAndArmQuorumLoop` where the verdict classifier is
+     * built. ABSENT (tests) → the classifier is not wired → regex parser.
+     */
+    classifyRunner?: LocalGemmaPlannerRunner | null;
+}): Promise<BuildTeamLocalExecutorResult>;
+/**
+ * PHASE-589/469 W3.1 (C4 / RESIDUAL 2) — probe the engine's TERMINAL view of a
+ * team group for the startup reconcile, via the `getTaskGroupStatus` query (the
+ * group row's authoritative `status` + `halt_reason`). This is what closes the
+ * OFFLINE lease-timeout case: a group the sweeper drove `Halted` while the desktop
+ * was down now resolves to `terminal_rejected` here → the reconcile auto-reverts
+ * the applied tree before a backend expiry could strand it dirty.
+ *
+ *   - `halted`                                  → `'terminal_rejected'` (revert)
+ *   - `complete`                                → `'terminal_kept'`     (mark accepted)
+ *   - any non-terminal status (scheduling /     → `'in_flight'`         (leave the
+ *     tracks_in_flight / draining /                                      manifest)
+ *     merge_gate_pending)
+ *   - `unknown` (vanished / unowned / TTL'd)    → `'unknown'`           (orphan-TTL
+ *     OR a probe error                                                   fallback GC)
+ *
+ * Fail-open on a probe error → `'unknown'` (the manifest is kept for the orphan-TTL
+ * fallback rather than blindly reverting a possibly-kept group). A
+ * `reject_revert_in_progress` CLAIM-crash manifest is NEVER GC'd regardless (its
+ * lifecycle is non-terminal), so it survives every restart and resumes its revert.
+ */
+export declare function probeEngineGroupState(appsyncClient: AppSyncClient, taskGroupId: string): Promise<EngineGroupState>;
+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>;