@capgo/cli 8.8.1 → 8.9.0

package/dist/src/build/onboarding/mcp/engine.d.ts

@@ -1,10 +1,11 @@
-import type { AndroidOnboardingProgress } from '../android/types.js';
+import type { AndroidOnboardingProgress, AndroidOnboardingStep } from '../android/types.js';
 import type { AndroidEffectDeps } from '../android/flow.js';
-import type { OnboardingProgress } from '../types.js';
+import type { IosEffectDeps, IosStepCtx, IosStepView } from '../ios/flow.js';
+import type { OnboardingProgress, OnboardingStep } from '../types.js';
 import type { NextStepResult, Platform } from './contract.js';
 import type { BuildOutputRecord } from '../../output-record.js';
 import { androidViewForStep } from '../android/flow.js';
-import { beginOAuthSession, clearOAuthSession, pollOAuthSession } from './oauth-session.js';
+import { brokerBegin, brokerClear, brokerPoll } from './broker-session.js';
 /** Facts gathered during preflight; the pure deciders branch only on these. */
 export interface PreflightFacts {
     capacitorProject: boolean;
@@ -30,6 +31,14 @@ interface OnboardingInput {
     gcpProjectName?: string;
     androidPackage?: string;
     saMethodChoice?: 'retry' | 'save-anyway' | 'oauth';
+    /** Set true at google-sign-in to (re)open the browser for a fresh OAuth — recovery when the browser didn't open, was closed, or the sign-in stalled. */
+    reopenSignIn?: boolean;
+    /** At google-sign-in: open the broker sign-in link in the user's browser (true) or let them open it (false/omit). */
+    openSignInBrowser?: boolean;
+    /** The confirmation code the user reads off the broker success page — releases the token on poll. */
+    confirmCode?: string;
+    /** Answer to the resume prompt: 'continue' resumes the saved step, 'restart' wipes this platform's saved progress and begins again. */
+    resumeChoice?: 'continue' | 'restart';
     credentialsExistChoice?: 'backup' | 'cancel';
     keystoreMethod?: 'existing' | 'generate';
     keystorePath?: string;
@@ -39,16 +48,110 @@ interface OnboardingInput {
     keystoreNewAlias?: string;
     keystorePasswordMethod?: 'random' | 'manual';
     keystoreCommonName?: string;
+    /** Answer to the parked iOS verify-app gate (the TUI Select vocabulary). */
+    verifyAction?: 'pick' | 'create-new' | 'autofix' | 'continue' | 'recheck' | 'open' | 'reopen' | 'back' | 'cancel';
+    /** The picked App Store app's bundle id — only with verifyAction 'pick'. */
+    verifyAppId?: string;
+    /**
+     * Answer to the parked iOS cert-limit-prompt (S6b): the Apple resource id of
+     * the Distribution certificate to revoke, or '__exit__' (the engine's
+     * OPTION_CERT_LIMIT_EXIT sentinel) to stop.
+     */
+    certToRevoke?: string;
+    /** Answer to the parked iOS duplicate-profile-prompt (S6b). */
+    duplicateProfileAction?: 'delete' | 'exit';
+    /**
+     * Answer to the parked iOS error recovery screen (S6b): 'retry' re-runs the
+     * failing step (carried.retryStep), 'restart' wipes progress + session and
+     * starts over, 'exit' stops, 'email-support' surfaces support instructions
+     * (MCP-only arm — no host-side opens).
+     */
+    errorAction?: 'retry' | 'restart' | 'exit' | 'email-support';
+    /** Answer to the CI-secrets choice steps (target-select / ask / overwrite / push-confirm / setup / failed). */
+    ciSecretAction?: 'github' | 'gitlab' | 'skip' | 'yes' | 'no' | 'replace' | 'retry' | 'continue' | 'confirm' | 'cancel';
+    /** Answer to ask-github-actions-setup ('no' maps to the persisted setupMode 'declined'). */
+    githubActionsSetup?: 'with-workflow' | 'secrets-only' | 'no';
+    /** Answer to ask-export-env (yes/no) and confirm-env-export-overwrite (replace/skip). */
+    exportEnvAction?: 'yes' | 'no' | 'replace' | 'skip';
+    /** Custom .env target path — only together with exportEnvAction 'yes'. */
+    envExportPath?: string;
+    /** Answer to pick-package-manager. */
+    packageManager?: 'bun' | 'npm' | 'pnpm' | 'yarn';
+    /** Answer to pick-build-script: a script name, '__custom__', or '__skip__'. */
+    buildScript?: string;
+    /** Answer to pick-build-script-custom: the exact custom build command. */
+    buildScriptCustom?: string;
+    /** Answer to preview-workflow-file: write / view (returns the file text, re-asks) / cancel. */
+    workflowFileAction?: 'write' | 'view' | 'cancel';
+    /** Answer to the iOS setup-method fork: create fresh credentials via Apple, or import from this Mac's Keychain. */
+    setupMethod?: 'create-new' | 'import-existing';
+    /** Answer to import-distribution-mode ('__cancel__' switches to the create-new path). */
+    importDistribution?: 'app_store' | 'ad_hoc' | '__cancel__';
+    /** Answer to import-pick-identity: the chosen identity's SHA-1 (an option value), or '__cancel__' for create-new. */
+    identityChoice?: string;
+    /** Answer to import-pick-profile: the chosen profile's UUID (an option value), or '__back__' to re-pick the identity. */
+    profileChoice?: string;
+    /** Answer to the import-no-match-recovery hub. */
+    importRecoveryAction?: 'create' | 'provide-profile-path' | 'browser' | 'back';
+    /** Answer to import-portal-explanation (the manual Apple-portal walkthrough). */
+    portalAction?: 'use-create' | 'open-anyway' | 'use-file' | 'back';
+    /** Absolute path to a .mobileprovision file — answers import-provide-profile-path (the MCP's manual-path arm of the TUI's native picker). */
+    profilePath?: string;
+    /** Answer to import-export-warning: 'go' exports from the Keychain (the one macOS permission dialog), 'back' re-picks the profile, 'exit' stops. */
+    exportConfirm?: 'go' | 'back' | 'exit';
 }
 /** Decide the first/again step for a fresh or resumed session. */
 export declare function decideStart(facts: PreflightFacts, progress: OnboardingProgress | null, deps: EngineDeps): Promise<NextStepResult>;
-export declare function decideIos(facts: PreflightFacts): NextStepResult;
+/**
+ * Map an interactive IosStepView into a NextStepResult — the iOS mirror of
+ * mapAndroidView. State names reuse the engine step ids; option values mirror
+ * the TUI Select values. Only NON-SECRET, view-derived data may appear here.
+ */
+export declare function mapIosView(view: IosStepView, facts: PreflightFacts, ctx?: IosStepCtx): NextStepResult;
+export declare function decideIos(facts: PreflightFacts, deps: EngineDeps, opts?: {
+    verifyAction?: OnboardingInput['verifyAction'];
+    verifyAppId?: string;
+    certToRevoke?: string;
+    duplicateProfileAction?: 'delete' | 'exit';
+    errorAction?: 'retry' | 'restart' | 'exit' | 'email-support';
+    /** import-pick-identity answer: an identity SHA-1 or '__cancel__'. */
+    identityChoice?: string;
+    /** import-pick-profile answer: a profile UUID or '__back__'. */
+    profileChoice?: string;
+    /** import-no-match-recovery answer. */
+    importRecoveryAction?: 'create' | 'provide-profile-path' | 'browser' | 'back';
+    /** import-portal-explanation answer. */
+    portalAction?: 'use-create' | 'open-anyway' | 'use-file' | 'back';
+    /** import-provide-profile-path answer: the .mobileprovision path. */
+    profilePath?: string;
+    /** import-export-warning answer. */
+    exportConfirm?: 'go' | 'back' | 'exit';
+    /**
+     * S9-S11: the explicit tail step a validated tail answer routed to
+     * (drive() → applyMcpTailAnswer). Honored only while the slim tail
+     * progress carries credentialsSaved — the same guard as the tail park.
+     */
+    tailNext?: OnboardingStep;
+}): Promise<NextStepResult>;
 export declare function mapAndroidView(view: ReturnType<typeof androidViewForStep>, facts: PreflightFacts, opts?: {
     keystorePath?: string;
     keystorePassword?: string;
 }): NextStepResult;
 export declare function decideAndroid(facts: PreflightFacts, deps: EngineDeps, opts?: {
     signInProceed?: boolean;
+    /** Drop any in-flight Google OAuth session and (re)open the browser for a fresh
+     *  sign-in — recovery for "still waiting" when the browser never opened / was closed. */
+    reopenSignIn?: boolean;
+    /** At google-sign-in: open the broker sign-in link in the user's browser (vs. letting them open it). */
+    openSignInBrowser?: boolean;
+    /** The confirmation code the user reads off the broker success page — released the token on the next poll. */
+    confirmCode?: string;
+    /**
+     * S9-S11: the explicit tail step a validated tail answer routed to
+     * (drive() → applyMcpTailAnswer). Honored only while the slim tail
+     * progress carries credentialsSaved — the same guard as the tail park.
+     */
+    tailNext?: AndroidOnboardingStep;
 }): Promise<NextStepResult>;
 export declare function decideAdvance(facts: PreflightFacts, progress: OnboardingProgress | null, input: OnboardingInput | undefined, deps: EngineDeps): Promise<NextStepResult>;
 export interface EngineDeps {
@@ -66,40 +169,34 @@ export interface EngineDeps {
         error: string;
     }>;
     loadAndroidProgress: (appId: string) => Promise<AndroidOnboardingProgress | null>;
-    finalizeAndroidCredentials: (appId: string) => Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        error: string;
-    }>;
     readBuildRecord: (path: string) => Promise<BuildOutputRecord | null>;
     buildRecordPath: (appId: string, platform: Platform) => string;
-    setIosApiKey: (appId: string, keyId: string, issuerId: string, p8Path: string) => Promise<void>;
-    finalizeIosCredentials: (appId: string) => Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        error: string;
-    }>;
+    /**
+     * Remove a build record (and its QR png) left behind by an earlier build.
+     * Called by runBuild BEFORE the hand-off so checkBuild can never read a
+     * stale record as the new build's result (hostile-review 2026-06-12).
+     * Optional so legacy fixtures keep working; production wires
+     * removeBuildOutputRecord.
+     */
+    clearBuildRecord?: (recordPath: string) => Promise<void>;
+    /**
+     * The shared iOS flow engine's IO deps (Apple API / CSR / fs / persistence),
+     * pre-bound by the driver (buildIosEffectDeps in onboarding-tools.ts for
+     * production; canned fakes in tests). decideIos threads the per-app carried
+     * session state in on every effect run. Optional so legacy fixtures that
+     * never enter the iOS path keep working — a missing helper inside surfaces
+     * as a caught effect error, never a crash.
+     */
+    iosEffectDeps?: IosEffectDeps;
     androidEffectDeps: AndroidEffectDeps;
-    /** Returns true when the current host can launch Terminal.app (macOS). Injectable for tests. */
-    canLaunchTerminal: () => boolean;
-    /** Launch `command` in a new macOS Terminal.app window. Injectable for tests. */
-    launchBuildInTerminal: (command: string) => Promise<{
-        ok: true;
-    } | {
-        ok: false;
-        error: string;
-    }>;
     /**
-     * Optional injectable OAuth session registry for testing. When provided, the
-     * engine uses these instead of the module-level functions in oauth-session.ts.
-     * Production builds omit this and rely on the module-level registry.
+     * Optional injectable broker OAuth session for testing. When provided, the engine uses these instead of the
+     * disk-persisted broker-session.ts functions. Production omits this and relies on the broker session.
      */
     oauthSession?: {
-        begin: typeof beginOAuthSession;
-        poll: typeof pollOAuthSession;
-        clear: typeof clearOAuthSession;
+        begin: typeof brokerBegin;
+        poll: typeof brokerPoll;
+        clear: typeof brokerClear;
     };
     /**
      * Write the generated/loaded Android keystore (.p12) to a file on disk so the
@@ -112,14 +209,34 @@ export interface EngineDeps {
     writeKeystoreFile?: (appId: string, base64: string, alias: string) => Promise<string>;
 }
 export declare function gatherFacts(deps: EngineDeps): Promise<PreflightFacts>;
-export declare function runStart(deps: EngineDeps): Promise<NextStepResult>;
+export declare function runStart(deps: EngineDeps, platform?: Platform): Promise<NextStepResult>;
 export declare function runAdvance(deps: EngineDeps, input?: OnboardingInput): Promise<NextStepResult>;
 /**
  * Read-only: determine the onboarding state the user is currently on, WITHOUT
- * running any side effect. Mirrors the branch selection of decideStart/decideAndroid
- * (preflight → platform → android resume step) but never calls effects.
+ * running any side effect. Mirrors the branch selection of decideStart/
+ * decideAndroid/decideIos (preflight → platform → resume step, with the same
+ * ask-build → build-ready / .p8-chain → ios-api-key name mapping) but never
+ * calls effects.
  */
 export declare function resolveCurrentState(facts: PreflightFacts): string;
+/** State names the MCP constructs directly that are NOT engine step ids. */
+export declare const MCP_ONLY_STATES: readonly string[];
+/**
+ * Engine step ids (present in the type tables) the MCP can NEVER emit as a
+ * state name:
+ *  - TUI bootstrap / TUI-only screens: welcome, adding-platform,
+ *    the AI build-debug sub-flow (decideIos reroutes its entry to
+ *    'build-failed'), the contact-support sub-flow (the MCP's error screen has
+ *    the email-support arm instead), the native file pickers (the MCP collects
+ *    paths as text), the google-sign-in-running spinner (the MCP parks on
+ *    'google-sign-in' via its OAuth session), and view-workflow-diff (the MCP
+ *    folds the diff into preview-workflow-file's context — 'view' re-parks);
+ *  - the .p8 input chain, collapsed into the single 'ios-api-key' gate;
+ *  - 'ask-build', mapped to the shared 'build-ready' choice (decideBuildPhase);
+ *  - 'requesting-build', never run over MCP (the C2/D2 handoff + checkBuild
+ *    polling replace it).
+ */
+export declare const MCP_UNREACHABLE_STEPS: ReadonlySet<string>;
 /**
  * Read-only "explain the current step" entry point backing the
  * capgo_builder_onboarding_explain tool. Gathers facts (read-only) and returns a

package/dist/src/build/onboarding/mcp/onboarding-tools.d.ts

@@ -1,5 +1,7 @@
 import type { CapgoSDK } from '../../../sdk.js';
 import type { EngineDeps } from './engine.js';
+import type { BuildJobDeps } from './build-job.js';
+import { type CredentialsManageDeps } from './credentials-manage.js';
 /** Minimal shape of the MCP server's tool registrar (matches McpServer.tool). */
 interface McpLike {
     tool: (name: string, description: string, schema: Record<string, unknown>, handler: (args: any) => Promise<{
@@ -8,10 +10,24 @@ interface McpLike {
             text: string;
         }>;
     }>) => unknown;
+    prompt?: (name: string, description: string, handler: () => {
+        messages: Array<{
+            role: 'user' | 'assistant';
+            content: {
+                type: 'text';
+                text: string;
+            };
+        }>;
+    }) => unknown;
 }
+/**
+ * Production EngineDeps wiring. Exported for tests that pin production-only
+ * behavior (clearBuildRecord wiring, keystore file modes).
+ */
+export declare function buildDeps(sdk: CapgoSDK): EngineDeps;
 /**
  * Register the 2-tool onboarding spine onto an MCP server.
  * `depsOverride` is for tests; production passes only `server` + `sdk`.
  */
-export declare function registerOnboardingTools(server: McpLike, sdk: CapgoSDK, depsOverride?: EngineDeps): void;
+export declare function registerOnboardingTools(server: McpLike, sdk: CapgoSDK, depsOverride?: EngineDeps, buildJobDepsOverride?: BuildJobDeps, credentialsManageDepsOverride?: CredentialsManageDeps): void;
 export {};

package/dist/src/build/onboarding/mcp/session-state.d.ts

@@ -0,0 +1,160 @@
+import type { CiSecretSetupAdvice, CiSecretTarget } from '../ci-secrets.js';
+import type { IosEffectDeps } from '../ios/flow.js';
+import type { TailEffectDeps } from '../tail/flow.js';
+import type { OnboardingStep } from '../types.js';
+import type { Platform } from './contract.js';
+/**
+ * The iOS driver-held transient state — the exact `IosEffectDeps['carried']`
+ * shape, plus the MCP-only `parkedImportStep` (S12): the interactive import
+ * sub-flow prompt the driver parked between tool calls — the headless mirror
+ * of the TUI's React `step` state for the EPHEMERAL import prompts, which
+ * resume routing can never reproduce (see engine.ts iosParkedStep). NON-SECRET
+ * (a step name). Wiped with the session; a restart self-heals via a fresh
+ * import-scanning that re-derives the inventory and re-renders the picker.
+ */
+export type IosCarried = NonNullable<IosEffectDeps['carried']> & {
+    parkedImportStep?: OnboardingStep;
+    /**
+     * The chosen identity's Apple cert resource id (import-checking-apple-cert's
+     * transient — typed on IosStepCtx, not on the engine's carried shape). The
+     * registry really holds it after the transient merge; typing it here lets
+     * the driver DROP it when the user re-picks a different identity (the TUI
+     * clears its appleCertId mirror the same way). NON-SECRET (an Apple id).
+     */
+    _appleCertIdForChosen?: string;
+};
+/**
+ * The tail driver-held transient state — the exact `TailEffectDeps['carried']`
+ * shape, plus the NON-SECRET tail OUTCOME facts the outcome-aware terminal
+ * summary harvests (engine.ts harvestTailOutcomes → tailCompleteResult): the
+ * exact upload summary line (counts/labels only), the written workflow path
+ * and the exported .env path. These three are non-secret BY CONSTRUCTION and
+ * are the one carried subset allowed to surface verbatim in a tool result —
+ * secret VALUES (savedCredentials / ciSecretEntries) must still never leave
+ * this registry.
+ */
+export type TailCarried = NonNullable<TailEffectDeps['carried']> & {
+    ciSecretUploadSummary?: string;
+    workflowFilePath?: string;
+    envExportPath?: string;
+};
+/**
+ * S9-S11: the MCP's parked interactive TAIL step + the NON-SECRET view context
+ * it was rendered with (option inventories / labels — never credential values).
+ * The TUI holds the current tail step in React state; the MCP mirrors it here so
+ * (a) the strict tail gate validates an answer against the step that actually
+ * asked, and (b) a re-render (corrective message, plain re-check) re-asks the
+ * SAME parked question instead of drifting forward through the resume router —
+ * which would collapse past consent gates like preview-workflow-file. A server
+ * restart loses the park; resume routing then takes over (the frozen
+ * tailResumeStep contract). EXPLICITLY NO SECRETS: ciSecretEntries (values)
+ * stay in tailCarried; only derived key NAMES may surface in tool results.
+ */
+export interface TailParkedState {
+    step: string;
+    ciSecretTargets?: CiSecretTarget[];
+    ciSecretSetupAdvice?: CiSecretSetupAdvice[];
+    ciSecretRepoLabel?: string | null;
+    ciSecretError?: string;
+    availableScripts?: Record<string, string>;
+    recommendedScript?: string | null;
+}
+export interface OnboardingSessionState {
+    iosCarried: IosCarried;
+    tailCarried: TailCarried;
+    tailParked?: TailParkedState;
+    /**
+     * The platform this session is setting up, as CHOSEN by the user (platform
+     * picker answer / single-platform auto-route / explicit `{ platform }`), NOT
+     * inferred from on-disk progress. This is what lets a bare `next_step({})`
+     * resume the right platform AND lets two concurrent server processes onboard
+     * the same app for different platforms without reading each other's progress
+     * files. Process-local: a restart loses it and the flow re-asks the picker.
+     */
+    activePlatform?: Platform;
+    /**
+     * The platform whose continue-vs-restart resume prompt has already been
+     * resolved THIS session — shown and answered, or skipped as unnecessary (no
+     * resumable on-disk progress). While it differs from the committed platform, a
+     * fresh platform entry first shows the resume prompt (mirroring the TUI's
+     * `resume-prompt` fork) instead of silently resuming. Process-local: a restart
+     * loses it and the prompt is re-offered. Reset by runStart so a fresh "start
+     * onboarding" always re-asks.
+     */
+    resumeResolvedFor?: Platform;
+}
+/**
+ * Get the session state for `appId`, creating an empty one on demand.
+ * The returned object is the current SNAPSHOT: merges replace the carried
+ * objects rather than mutating them, so re-read after merging.
+ */
+export declare function getSession(appId: string): OnboardingSessionState;
+/**
+ * Read the platform this session committed to (via setSessionPlatform), or
+ * undefined when none has been chosen yet (fresh session, or after a restart).
+ * Deliberately does NOT consult disk progress — the platform is a session
+ * decision, not a property of what happens to be saved on disk.
+ */
+export declare function getSessionPlatform(appId: string): Platform | undefined;
+/**
+ * Record (or, with `undefined`, clear) the platform this session is setting up.
+ * Called when the user picks at the platform gate, when a single-platform
+ * project auto-routes, or on any explicit `{ platform }`. Cleared by runStart so
+ * a fresh "start onboarding" always re-asks instead of silently resuming.
+ */
+export declare function setSessionPlatform(appId: string, platform: Platform | undefined): void;
+/**
+ * Read which platform's resume prompt has already been resolved this session
+ * (shown+answered, or determined unnecessary), or undefined when none has.
+ * Process-local; deliberately ignores disk — the resume decision is a session
+ * decision, exactly like the platform itself.
+ */
+export declare function getResumeResolvedFor(appId: string): Platform | undefined;
+/**
+ * Record (or, with `undefined`, clear) which platform's continue-vs-restart
+ * resume prompt has been resolved this session. Set once the prompt is answered
+ * or skipped as unnecessary; cleared by runStart so a fresh start re-asks.
+ */
+export declare function setResumeResolvedFor(appId: string, platform: Platform | undefined): void;
+/**
+ * Drop the per-flow carried transients (iOS carried, tail carried, tail park)
+ * for `appId` while PRESERVING the session-level decisions (activePlatform,
+ * resumeResolvedFor). Used by the resume prompt's "restart" arm: the on-disk
+ * progress is wiped, so the in-memory carried state from the old run must go
+ * too — but the session stays committed to the same platform and must not
+ * re-ask the resume prompt it just answered. Immutable: builds a NEW entry.
+ */
+export declare function clearSessionCarried(appId: string): void;
+/**
+ * Merge `partial` into the iOS carried state for `appId` and return the new
+ * merged carried object. `undefined` values leave the prior value intact.
+ */
+export declare function mergeIosCarried(appId: string, partial: Partial<IosCarried>): IosCarried;
+/**
+ * Merge `partial` into the tail carried state for `appId` and return the new
+ * merged carried object. `undefined` values leave the prior value intact.
+ */
+export declare function mergeTailCarried(appId: string, partial: Partial<TailCarried>): TailCarried;
+/**
+ * Park the current interactive tail step (+ its non-secret view context) for
+ * `appId`. REPLACES any prior park — each render re-parks the step it shows,
+ * so the park always mirrors the question currently in front of the user.
+ * Immutable: builds a NEW session entry; prior snapshots are untouched.
+ */
+export declare function setTailParked(appId: string, parked: TailParkedState): void;
+/**
+ * Drop `keys` from the iOS carried state for `appId` and return the new
+ * carried object. The complement of mergeIosCarried for one-shot consumable
+ * fields (e.g. the verify-app `verifyAction` pick, which the driver MUST clear
+ * after the resolver effect ran so a later re-entry runs the initial fetch —
+ * merge semantics skip `undefined`, so a merge can never clear). Immutable:
+ * builds a NEW carried object; prior snapshots are untouched.
+ */
+export declare function dropIosCarried(appId: string, keys: (keyof IosCarried)[]): IosCarried;
+/**
+ * Drop the session entry for `appId`. Idempotent: safe on an absent appId and
+ * safe to call twice. The next getSession() recreates a fresh empty session.
+ */
+export declare function clearSession(appId: string): void;
+/** Drop every session (test isolation only — production code clears per appId). */
+export declare function clearAllSessions(): void;

package/dist/src/build/onboarding/mcp/step-input.d.ts

@@ -1,4 +1,5 @@
 import type { AndroidOnboardingStep } from '../android/types.js';
+import type { OnboardingStep } from '../types.js';
 /** state → the set of input fields that legitimately answer it (in order). */
 export declare const STEP_ALLOWED_FIELDS: Partial<Record<AndroidOnboardingStep, string[]>>;
 /** The set of all android input keys we govern (for the extras check). */
@@ -10,8 +11,14 @@ export declare const ANDROID_INPUT_KEYS: string[];
  * fields and no other governed android key. Otherwise { ok:false } with the
  * allowed fields + the offending extra keys for a corrective message.
  *
- * Steps with no allowed-field entry (auto/sign-in/no-field) are not governed and
- * always pass — the strict gate only constrains interactive input steps.
+ * Inputs with NO governed android key always pass (plain continue / other
+ * vocabularies). Steps with no allowed-field entry FAIL CLOSED for governed
+ * keys (hostile-review 2026-06-12): an android field sent at an auto step, at
+ * the google-sign-in park, or before the android flow has rendered its first
+ * step ('welcome', i.e. null progress) is never a legitimate answer — letting
+ * it through allowed jumping the keystore phase past the credentials-exist
+ * data-safety gate (which is seeded only when the flow renders
+ * keystore-method-select).
  *
  * @param currentStep the resume step the user is currently on
  * @param input the next_step input object
@@ -43,3 +50,43 @@ export declare function validateStorePassword(currentStep: AndroidOnboardingStep
     ok: boolean;
     message?: string;
 };
+/** The set of all iOS input keys the MCP governs (for the extras check). */
+export declare const IOS_INPUT_KEYS: string[];
+/**
+ * Validate incoming iOS next_step input against the step it answers.
+ *
+ * Returns { ok:true } when the input is a legitimate answer for `currentStep`
+ * (see the vocabulary rules above). Otherwise { ok:false, message } with a
+ * corrective instruction for the agent. Inputs with NO governed iOS key always
+ * pass — the android gate (and the rest of drive()) owns those.
+ *
+ * @param currentStep the iOS step the user is currently on (the session-parked
+ *   recovery step when one is parked, else the resume step — see
+ *   engine.ts effectiveIosStep)
+ * @param input the next_step input object
+ */
+export declare function validateIosStepInput(currentStep: OnboardingStep, input: Record<string, unknown>): {
+    ok: boolean;
+    message?: string;
+};
+/** The tail family answer fields (one per step family; envExportPath is the ask-export-env companion). */
+export declare const TAIL_FAMILY_FIELDS: readonly ["ciSecretAction", "githubActionsSetup", "exportEnvAction", "packageManager", "buildScript", "buildScriptCustom", "workflowFileAction"];
+/** Every tail input key the MCP governs (for presence/extras checks). */
+export declare const TAIL_INPUT_KEYS: string[];
+/**
+ * Validate an incoming tail next_step input against the step it answers.
+ *
+ * @param currentStep the EFFECTIVE tail step (the session-parked step when one
+ *   is parked, else the platform resume step — see engine.ts)
+ * @param input the next_step input object
+ * @param ctx optional parked inventories for the dynamic vocabularies
+ */
+export declare function validateTailStepInput(currentStep: string, input: Record<string, unknown>, ctx?: {
+    ciSecretTargets?: {
+        provider: string;
+    }[];
+    availableScripts?: Record<string, string>;
+}): {
+    ok: boolean;
+    message?: string;
+};

package/dist/src/build/onboarding/mcp/tail-progress.d.ts

@@ -0,0 +1,6 @@
+import type { AndroidOnboardingProgress } from '../android/types.js';
+import type { OnboardingProgress } from '../types.js';
+/** Build the slim iOS tail progress — WHITELIST ONLY (see module doc). */
+export declare function slimIosTailProgress(progress: OnboardingProgress): OnboardingProgress;
+/** Build the slim Android tail progress — WHITELIST ONLY (see module doc). */
+export declare function slimAndroidTailProgress(progress: AndroidOnboardingProgress): AndroidOnboardingProgress;

package/dist/src/build/onboarding/types.d.ts

@@ -18,7 +18,7 @@ export interface OnboardingResult {
     summary?: OnboardingCompletionSummary;
 }
 export type OnboardingStep = 'welcome' | 'resume-prompt' | 'platform-select' | 'adding-platform' | 'credentials-exist' | 'backing-up' | 'setup-method-select' | 'import-scanning' | 'import-distribution-mode' | 'import-pick-identity' | 'import-pick-profile' | 'import-validating-all-certs' | 'import-checking-apple-cert' | 'import-no-match-recovery' | 'import-portal-explanation' | 'import-provide-profile-path' | 'import-create-profile-only' | 'import-export-warning' | 'import-exporting' | 'p8-source-select' | 'asc-key-generating' | 'asc-key-created' | 'api-key-instructions' | 'p8-method-select' | 'input-p8-path' | 'input-key-id' | 'input-issuer-id' | 'verifying-key' | 'verify-app' | 'creating-certificate' | 'cert-limit-prompt' | 'revoking-certificate' | 'creating-profile' | 'duplicate-profile-prompt' | 'deleting-duplicate-profiles' | 'saving-credentials' | 'detecting-ci-secrets' | 'ci-secrets-setup' | 'ci-secrets-target-select' | 'ask-ci-secrets' | 'checking-ci-secrets' | 'confirm-ci-secret-overwrite' | 'uploading-ci-secrets' | 'ci-secrets-failed' | 'ask-github-actions-setup' | 'confirm-secrets-push' | 'ask-export-env' | 'exporting-env' | 'confirm-env-export-overwrite' | 'overwrite-and-export-env' | 'pick-package-manager' | 'pick-build-script' | 'pick-build-script-custom' | 'preview-workflow-file' | 'view-workflow-diff' | 'writing-workflow-file' | 'ask-build' | 'requesting-build' | 'ai-analysis-prompt' | 'ai-analysis-running' | 'ai-analysis-result' | 'ai-analysis-result-scroll' | 'build-complete' | 'no-platform' | 'error' | 'support-confirm' | 'support-log-view' | 'support-uploading';
-export type OnboardingErrorCategory = 'apple_api_unauthorized' | 'apple_api_rate_limited' | 'cert_limit_reached' | 'profile_creation_failed' | 'p8_invalid' | 'keychain_no_identities' | 'keychain_export_failed' | 'profile_no_match' | 'profile_read_failed' | 'unknown';
+export type OnboardingErrorCategory = 'apple_api_unauthorized' | 'apple_api_forbidden' | 'apple_agreements_missing' | 'apple_api_rate_limited' | 'cert_limit_reached' | 'profile_creation_failed' | 'p8_invalid' | 'keychain_no_identities' | 'keychain_export_failed' | 'profile_no_match' | 'profile_read_failed' | 'unknown';
 export interface ApiKeyData {
     keyId: string;
     issuerId: string;

package/dist/src/build/output-record.d.ts

@@ -26,6 +26,13 @@ export interface WriteBuildOutputRecordInput {
  *
  * Failures rendering the PNG are non-fatal — the JSON is always written. The
  * record's `qrCodePngPath` field is null when the PNG could not be produced.
+ *
+ * Hardening (hostile-review 2026-06-12): the record and PNG paths are unlinked
+ * before writing so a pre-planted symlink is replaced instead of followed; the
+ * record is written with mode 0600 (outputUrl is a signed download URL); a
+ * created parent directory gets mode 0700; and when the record lives under the
+ * shared tmpdir, a parent directory that is a symlink or owned by another user
+ * is refused.
  */
 export declare function writeBuildOutputRecord(recordPath: string, input: WriteBuildOutputRecordInput, onWarn?: (msg: string) => void): Promise<BuildOutputRecord>;
 /**
@@ -36,12 +43,44 @@ export declare function writeBuildOutputRecord(recordPath: string, input: WriteB
  *
  * appId is sanitized: all `/` and `\` characters are replaced with `_`, and
  * any `..` sequences are replaced with `_`, to prevent path traversal.
+ *
+ * The record lives in a per-user `capgo-build-records-<uid>` subdirectory
+ * (created with mode 0700 by `writeBuildOutputRecord`) so that on shared-tmp
+ * systems another user can neither pre-create nor read the record file
+ * (hostile-review 2026-06-12).
  */
 export declare function defaultBuildRecordPath(appId: string, platform: 'ios' | 'android'): string;
 /**
- * Read a build output record from `path`. Returns the parsed `BuildOutputRecord`
- * if the file exists, is valid JSON, and the parsed object contains a string
- * `jobId` property. Returns `null` in all other cases (missing file, parse
- * error, missing/wrong-type jobId).
+ * Remove a build output record and its companion QR PNG. Absent paths are a
+ * no-op. Called before a new build hand-off so a record left behind by an
+ * earlier build can never be read as the new build's result.
+ */
+export declare function removeBuildOutputRecord(recordPath: string): Promise<void>;
+/**
+ * Thrown by `readBuildOutputRecord` when the record file EXISTS but cannot be
+ * used: unreadable (permissions), a symbolic link, not valid JSON (e.g. a
+ * truncated write), or an unexpected shape. Distinct from the `null` return
+ * (no record yet) so callers polling for a build result can surface the
+ * failure instead of waiting forever.
+ */
+export declare class BuildRecordReadError extends Error {
+    readonly recordPath: string;
+    constructor(message: string, recordPath: string);
+}
+/**
+ * Read a build output record from `path`.
+ *
+ * Returns `null` ONLY when the file does not exist yet (ENOENT — the build has
+ * not finished). Every other failure mode (unreadable file, a symlink at the
+ * record path, malformed JSON, missing/wrong-type fields) throws
+ * `BuildRecordReadError`: a present-but-corrupt record is a surfaced failure,
+ * never "still waiting".
+ *
+ * Shape rules (hostile-review 2026-06-12):
+ *  - every record owes the `jobId`/`status`/`outputUrl` trio (forward-tolerant
+ *    baseline for future schemaVersions);
+ *  - a `schemaVersion: 1` record is validated strictly against the full
+ *    `BuildOutputRecord` shape — the v1 writer has always emitted it, and
+ *    checkBuild correlates `appId`/`platform` against the build it launched.
  */
 export declare function readBuildOutputRecord(path: string): Promise<BuildOutputRecord | null>;

package/dist/src/mcp/instructions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP server `instructions` — the connect-time guidance string handed to clients
+ * (Codex, Claude Code, …) in the `initialize` result. Clients that support it inject
+ * this text into the model's context, so it is the one cross-client, server-side lever
+ * for steering WHEN to reach for these tools (tool descriptions only steer WHICH tool
+ * once the model has already decided to use the server).
+ *
+ * The general Capgo Cloud capabilities are always described. The Builder-onboarding
+ * steer is appended only when the onboarding tools are actually registered, so we never
+ * advertise a `start_capgo_builder_onboarding` tool that isn't there.
+ *
+ * Keep the result under 512 characters: some clients (Codex) cap server instructions
+ * at that length. `test/test-mcp-instructions.mjs` pins this.
+ */
+export declare function buildServerInstructions(onboardingEnabled: boolean): string;

package/dist/src/mcp/stdout-guard.d.ts

@@ -0,0 +1,19 @@
+import type { Writable } from 'node:stream';
+/**
+ * Harden a stdio MCP server against stdout pollution.
+ *
+ * The MCP stdio transport frames JSON-RPC over `process.stdout`. Any *other* write to
+ * stdout — a clack `intro`/`log`, a stray `console.log`, a chatty dependency — injects
+ * non-JSON bytes into that stream, and a strict client (e.g. Codex) then drops the
+ * connection with "Transport closed". Per-call `silent` flags (see sdk.ts) are easy to
+ * miss one-by-one, so this is the backstop: it routes EVERY ambient `process.stdout`
+ * write to stderr (still visible for debugging, harmless to the protocol) and returns a
+ * dedicated Writable — bound to the real stdout — for the transport to send JSON-RPC on.
+ *
+ * Call once, before constructing StdioServerTransport, and hand it the returned stream:
+ *   const out = installMcpStdoutGuard()
+ *   const transport = new StdioServerTransport(process.stdin, out)
+ *
+ * @returns a Writable wired to the real fd-1 stdout, for the transport only.
+ */
+export declare function installMcpStdoutGuard(): Writable;