feat(cloud): add operation ledgers and event contract

apps/mobile/src/app/_layout.tsx

@@ -335,7 +335,10 @@ function RootLayoutNav() {
     accountId: userId,
     optionalConsent,
   });
-  useScreenTracking();
+  // Screen capture must wait for consent: analytics eligibility is decided
+  // only after the account's consent decision has loaded without error.
+  const bootstrapSettled = token != null && consentChecked && !needsConsent && !consentCheckError;
+  useScreenTracking(bootstrapSettled);
 
   useEffect(() => {
     if (shareIntentError) {

apps/mobile/src/components/agents/mobile-session-manager.test.ts

@@ -1,4 +1,5 @@
 /* eslint-disable require-await, @typescript-eslint/require-await -- injectable query/sleep fakes settle without await */
+/* eslint-disable max-lines -- the manager suite pins retry cadence and attachment mints in one file. */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { type AgentAttachmentSubmissionPayload } from '@/lib/agent-attachments/agent-attachment-types';
@@ -41,17 +42,22 @@ vi.mock('@/components/agents/tool-card-image-cache', () => ({
 }));
 
 const mutate = vi.fn();
+const prepareSessionMutate = vi.fn();
 vi.mock('@/lib/trpc', () => ({
   trpcClient: {
     cloudAgentNext: {
       getAttachmentDownloadUrl: { mutate },
+      prepareSession: { mutate: prepareSessionMutate },
+    },
+    organizations: {
+      cloudAgentNext: { prepareSession: { mutate: prepareSessionMutate } },
     },
   },
 }));
 
 const { buildRemoteAttachmentParts } =
   await import('@/components/agents/mobile-session-manager-helpers');
-const { fetchSessionWithNotFoundRetry, readFetchSessionErrorCode } =
+const { fetchSessionWithNotFoundRetry, isCloudPrepareRetryableError, readFetchSessionErrorCode } =
   await import('@/components/agents/mobile-session-manager');
 
 const SESSION_ID = 'ses_test_session_id_0000000001' as KiloSessionId;
@@ -62,6 +68,10 @@ function notFoundError(): Error {
   return error;
 }
 
+function withCode(code: string, message: string): Error {
+  return Object.assign(new Error(message), { data: { code } });
+}
+
 describe('buildRemoteAttachmentParts', () => {
   beforeEach(() => {
     mutate.mockReset();
@@ -189,6 +199,46 @@ describe('readFetchSessionErrorCode', () => {
   });
 });
 
+describe('isCloudPrepareRetryableError', () => {
+  it('keeps the key for creation_in_progress (CONFLICT)', () => {
+    expect(isCloudPrepareRetryableError(withCode('CONFLICT', 'creation_in_progress'))).toBe(true);
+  });
+
+  it('keeps the key for a network error with no tRPC code', () => {
+    expect(isCloudPrepareRetryableError(new Error('Network request failed'))).toBe(true);
+  });
+
+  it('keeps the key for transient 5xx-class and rate-limit codes', () => {
+    for (const code of [
+      'INTERNAL_SERVER_ERROR',
+      'BAD_GATEWAY',
+      'SERVICE_UNAVAILABLE',
+      'GATEWAY_TIMEOUT',
+      'TIMEOUT',
+      'TOO_MANY_REQUESTS',
+    ]) {
+      expect(isCloudPrepareRetryableError(withCode(code, 'boom'))).toBe(true);
+    }
+  });
+
+  it('rotates the key on typed terminal rejections', () => {
+    for (const code of [
+      'BAD_REQUEST',
+      'UNAUTHORIZED',
+      'FORBIDDEN',
+      'NOT_FOUND',
+      'PAYMENT_REQUIRED',
+      'PRECONDITION_FAILED',
+    ]) {
+      expect(isCloudPrepareRetryableError(withCode(code, 'nope'))).toBe(false);
+    }
+  });
+
+  it('rotates the key on a CONFLICT with any other message', () => {
+    expect(isCloudPrepareRetryableError(withCode('CONFLICT', 'something else'))).toBe(false);
+  });
+});
+
 describe('fetchSessionWithNotFoundRetry', () => {
   // Production return type is SessionWithRuntimeState; tests inject a minimal
   // stand-in via `query` and only assert retry/cadence behavior.

apps/mobile/src/components/agents/mobile-session-manager.ts

@@ -64,6 +64,38 @@ export function readFetchSessionErrorCode(error: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * tRPC codes transient enough to keep the same cloud-prepare `operationKey`
+ * across a retry. Any other typed code is a terminal rejection and rotates it.
+ */
+const CLOUD_PREPARE_TRANSIENT_CODES = new Set([
+  'INTERNAL_SERVER_ERROR',
+  'BAD_GATEWAY',
+  'SERVICE_UNAVAILABLE',
+  'GATEWAY_TIMEOUT',
+  'TIMEOUT',
+  'TOO_MANY_REQUESTS',
+]);
+
+/** Stable message the ledger returns on a same-key in-flight duplicate (plan P1-A-08b). */
+const CLOUD_PREPARE_IN_PROGRESS_MESSAGE = 'creation_in_progress';
+
+/**
+ * True when a `prepareSession` failure may be retried with the SAME
+ * `operationKey`: `creation_in_progress`, a transient 5xx, or a codeless
+ * transport failure (the ledger reconciles the ambiguous prior attempt).
+ */
+export function isCloudPrepareRetryableError(error: unknown): boolean {
+  const code = readFetchSessionErrorCode(error);
+  if (code === undefined) {
+    return true;
+  }
+  if (code === 'CONFLICT') {
+    return error instanceof Error && error.message === CLOUD_PREPARE_IN_PROGRESS_MESSAGE;
+  }
+  return CLOUD_PREPARE_TRANSIENT_CODES.has(code);
+}
+
 /* eslint-disable @typescript-eslint/promise-function-async, require-await -- thin tRPC passthrough */
 async function defaultFetchSessionQuery(
   sessionId: KiloSessionId

apps/mobile/src/components/agents/use-continue-cloud-create.ts

@@ -0,0 +1,103 @@
+// The cloud-agent leg of `useContinueSession`: one `prepareSession` call, its
+// hoisted operation key, and the contained post-success UI work. Split out of
+// `use-continue-session.ts` (which keeps the paging drain, destination
+// resolution, and the remote spawn leg) so each file stays under the
+// max-lines limit.
+import { useCallback } from 'react';
+import { useRouter } from 'expo-router';
+import { useQueryClient } from '@tanstack/react-query';
+import { generateMessageId } from '@kilocode/cloud-agent-sdk/message-id';
+import * as Haptics from 'expo-haptics';
+
+import { normalizeAgentMode } from '@/components/agents/mode-options';
+import { isCloudPrepareRetryableError } from '@/components/agents/mobile-session-manager';
+import { getAgentSessionPath } from '@/components/agents/session-detail-routes';
+import { useHoistedOperationKey } from '@/lib/operation-key';
+import { captureEvent, SESSION_CREATED_EVENT } from '@/lib/analytics/posthog';
+import { invalidateAgentSessionQueries } from '@/lib/agent-session-cache';
+import { trpcClient, useTRPC } from '@/lib/trpc';
+
+export function useContinueCloudCreate(
+  organizationId: string | undefined
+): (
+  seed: string,
+  dest: { repo: string; model: string; variant: string },
+  mode: string
+) => Promise<void> {
+  const router = useRouter();
+  const queryClient = useQueryClient();
+  const trpc = useTRPC();
+  // P1-A-08b: cloud prepares and remote spawns are different intents, so each
+  // destination family holds its own hoisted `operationKey`.
+  const cloudOperationKey = useHoistedOperationKey();
+
+  return useCallback(
+    async (seed: string, dest: { repo: string; model: string; variant: string }, mode: string) => {
+      const intentFingerprint = JSON.stringify({
+        seed,
+        repo: dest.repo,
+        model: dest.model,
+        variant: dest.variant || undefined,
+        mode,
+        organizationId: organizationId ?? null,
+      });
+      const operationKey = cloudOperationKey.getKey(intentFingerprint);
+      const initialMessageId = generateMessageId();
+      const baseInput = {
+        prompt: seed,
+        initialMessageId,
+        mode: normalizeAgentMode(mode),
+        model: dest.model,
+        variant: dest.variant || undefined,
+        githubRepo: dest.repo,
+        autoCommit: true,
+        autoInitiate: true,
+        operationKey,
+      };
+      try {
+        const result = organizationId
+          ? await trpcClient.organizations.cloudAgentNext.prepareSession.mutate({
+              ...baseInput,
+              organizationId,
+            })
+          : await trpcClient.cloudAgentNext.prepareSession.mutate(baseInput);
+        // The intent settled; the next submit is a fresh intent. Rotate
+        // before the post-success work so a UI failure cannot keep the
+        // successful key for a retry or rotate it a second time.
+        cloudOperationKey.rotateKey();
+
+        // The cloud session already exists, so no post-success UI failure may
+        // report the create as failed or invite a duplicate retry. Each step is
+        // contained on its own so one failure cannot skip the navigation.
+        try {
+          captureEvent(SESSION_CREATED_EVENT, { surface: 'cloud-agent' });
+        } catch {
+          // Analytics is best-effort; stay silent.
+        }
+        try {
+          await invalidateAgentSessionQueries(queryClient, trpc);
+        } catch {
+          // A failed cache invalidation is cosmetic; navigation must still run.
+        }
+        try {
+          await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+        } catch {
+          // A failed haptics call is cosmetic; stay silent and navigate.
+        }
+        try {
+          router.push(getAgentSessionPath(result.kiloSessionId, organizationId));
+        } catch {
+          // A navigation failure is not a create failure.
+        }
+      } catch (error) {
+        // Only `prepareSession` errors reach here; UI failures are contained
+        // above. A typed terminal rejection ends the intent.
+        if (!isCloudPrepareRetryableError(error)) {
+          cloudOperationKey.rotateKey();
+        }
+        throw error;
+      }
+    },
+    [organizationId, queryClient, router, trpc, cloudOperationKey]
+  );
+}