@kortix/ui 0.14.3 → 0.14.5

package/dist/workspace/new/use-create-workspace.js

@@ -0,0 +1,751 @@
+'use client';
+import { uiRoutes } from '../../lib/routes.js';
+import { useQueryClient } from '@tanstack/react-query';
+import { useUiRouter, useUiViewerId } from '../../providers/ui-provider.js';
+import { useCallback, useState } from 'react';
+import { attemptKeyFor, clearAttemptKey } from './create-workspace-key.js';
+import { buildCreateRepoPayload, buildLinkRepositoryPayload, buildManagedImportPayload, isManagedImport, } from './github-source.js';
+import { buildProvisionPayload, isForeignAccountList, resolveDefaultCreatableAccountId, } from './new-workspace-form.js';
+import { createRepoWithGitHubAuthorization } from './github-user-authorization.js';
+import { useCreatableAccounts } from './use-creatable-accounts.js';
+import { useAccountsList } from '../../internal/hooks/account/use-accounts-list.js';
+import { isManagedGitUnavailableError, isProjectLimitError, } from '../../internal/lib/onboarding/provision-errors.js';
+import { requestGitHubUserProof } from '../../internal/lib/github-user-proof.js';
+import { writeLastProjectId } from '../../internal/lib/onboarding/last-project-cookie.js';
+import { createProjectRepo, storeGitHubUserToken, linkRepository, PROVISION_IN_FLIGHT_CODE, PROVISION_STREAM_UNTERMINATED_CODE, provisionProject, provisionProjectStream, setProjectOnboardingComplete, } from '@kortix/sdk';
+import { qk } from '@kortix/sdk/react';
+/**
+ * Backoff for a 409 `provision_in_flight` retry, ms — one entry per retry.
+ * Identical to `/projects/start`'s `RETRY_DELAY_MS`
+ * (`app/(app)/projects/start/page.tsx:36`, `const RETRY_DELAY_MS = [400,
+ * 1200]`): both doors run the SAME logical create against the same persisted
+ * `idempotency_key`, so their backoffs must not diverge.
+ */
+export const RETRY_DELAY_MS = [400, 1_200];
+/**
+ * What makes one create *distinct* from another, for `attemptKeyFor`.
+ *
+ * Deliberately NOT the full form state. `icon` and `defaultBranch` are
+ * refinements a user can still be adjusting between a failed submit and a
+ * retry — a retry must reuse the SAME key, not mint a new one just because
+ * the icon changed. `name`, `accountId`, `templateId` and `source` are what
+ * actually identifies a genuinely different workspace: keying on those means
+ * creating "suna-web" then, moments later, "kortix-api" in the same account
+ * mints two independent keys instead of the second create silently returning
+ * the first project (the exact failure mode `projects.ts`'s `idempotency_key` doc
+ * comment warns about).
+ */
+export function fingerprintOf(state) {
+    return [
+        state.accountId ?? 'default',
+        state.name.trim(),
+        state.templateId ?? '',
+        state.source,
+    ].join(':');
+}
+/**
+ * The account a create actually targets.
+ *
+ * `account_id` is ALWAYS resolved here — never left for the server to
+ * default from an omitted key. `resolveAccountId`
+ * (`apps/api/src/shared/resolve-account.ts:117-129`) picks the caller's
+ * EARLIEST-JOINED account membership with NO role check when `account_id` is
+ * absent:
+ *
+ * ```ts
+ * .where(eq(accountMembers.userId, userId))
+ * .orderBy(accountMembers.joinedAt)
+ * .limit(1)
+ * ```
+ *
+ * A user who joined account A as a plain member in January and later created
+ * account B as owner in March has exactly ONE creatable account (B) —
+ * `AccountPicker` hides itself below two accounts
+ * (`account-picker.tsx`), `state.accountId` stays legitimately `null`, and
+ * `creatableAccounts.length === 1` no longer implies "the user has only one
+ * account total". Omitting `account_id` in that case would resolve to A on
+ * the server and 403 "Owner or admin role required" — precisely the failure
+ * the picker's owner/admin filter (Task 12) exists to prevent, reopened
+ * through the server's default path. So the fallback is
+ * `resolveDefaultCreatableAccountId` (identity match → primary owner → first
+ * creatable) against the SAME filtered list the picker itself renders from —
+ * never the raw, unfiltered account list.
+ *
+ * Two independent fail-closed checks (Task 2 item 3, G2), both of which
+ * throw rather than let a create proceed:
+ *
+ * 1. `creatableAccounts` itself must not be FOREIGN
+ *    (`isForeignAccountList` — two or more accounts, none of them
+ *    `userId`'s own). Checked BEFORE looking at `state.accountId` at all: a
+ *    poisoned list taints every id it could produce, including one an
+ *    explicit (but stale) pick already carried, not only the default tier.
+ *    `new-workspace-page.tsx` already disables submit and hides the account
+ *    name for this case (item 2) — this is the second, independent layer
+ *    for any caller that resolves a target id without going through that
+ *    page-level gate, e.g. a future host of `useCreateWorkspace`.
+ * 2. The resolved id — from an explicit `state.accountId` or from the
+ *    default below — must actually be one of `creatableAccounts`.
+ *    `state.accountId` is normally only ever set from an `AccountPicker`
+ *    selection, itself built from this exact list, so this should never fire
+ *    in ordinary use; it is the last line of defense against a resolved id
+ *    that is stale, or a caller that skipped the page's own gating, ever
+ *    reaching the network with the signed-in user's JWT.
+ *
+ * Extracted out of `buildCreatePayload` (below) as its own function so the
+ * account a create actually targets is resolved in exactly one place.
+ *
+ * `userId` is required, not optional (G4): an omitted argument used to
+ * compile clean and silently degrade to `undefined`, which made
+ * `isForeignAccountList` treat ANY 2+-account list as foreign and throw —
+ * a functional break for real multi-account users that every single-
+ * account test passed straight through. The type is `string | null`, not
+ * `| undefined`: a caller that genuinely cannot establish identity yet must
+ * say so explicitly with `null`, which already fails closed correctly (see
+ * `isForeignAccountList`'s doc comment) rather than by accidental omission.
+ */
+export function resolveTargetAccountId(state, creatableAccounts, userId) {
+    if (isForeignAccountList(creatableAccounts, userId)) {
+        throw new Error('Could not verify the target account for this workspace. Refresh and try again.');
+    }
+    const resolved = state.accountId ?? resolveDefaultCreatableAccountId(creatableAccounts, userId) ?? undefined;
+    if (resolved === undefined)
+        return undefined;
+    const isCreatable = creatableAccounts.some((account) => account.account_id === resolved);
+    if (!isCreatable) {
+        throw new Error('Could not verify the target account for this workspace. Refresh and try again.');
+    }
+    return resolved;
+}
+/** The exact `POST /projects/provision` request body for one create attempt. */
+export function buildCreatePayload(state, creatableAccounts, idempotencyKey, userId) {
+    return {
+        ...buildProvisionPayload(state),
+        account_id: resolveTargetAccountId(state, creatableAccounts, userId),
+        idempotency_key: idempotencyKey,
+    };
+}
+/**
+ * The `POST /projects/create-repo` body, with the create's target account
+ * resolved through the SAME `resolveTargetAccountId` the provision path uses.
+ *
+ * Resolved here rather than left to the server for the reason that function's
+ * own doc comment gives at length: an omitted `account_id` resolves to the
+ * caller's earliest-joined membership with NO role check, which for a user who
+ * joined someone else's account first is an account they cannot create in.
+ * That reasoning is about the SERVER's default, not about which route is being
+ * called, so it holds identically for all three sources.
+ */
+export function buildGitHubCreatePayload(state, creatableAccounts, userId) {
+    return buildCreateRepoPayload(state, resolveTargetAccountId(state, creatableAccounts, userId));
+}
+/** The `POST /projects/link-repository` body. Same account resolution. */
+export function buildGitHubImportPayload(state, creatableAccounts, userId) {
+    return buildLinkRepositoryPayload(state, resolveTargetAccountId(state, creatableAccounts, userId));
+}
+/**
+ * The `POST /projects/link-repository` body for an existing MANAGED repository
+ * — the operator-only import path. Same account resolution; the installation
+ * is the managed-git backend rather than an account's GitHub App installation.
+ */
+export function buildManagedImportRequest(state, creatableAccounts, userId) {
+    return buildManagedImportPayload(state, resolveTargetAccountId(state, creatableAccounts, userId));
+}
+/**
+ * Matches the two placeholder sentences the SDK writes onto a failed create
+ * when the error response carried NO JSON body — the one case where the
+ * server's reason is genuinely lost and the generic retry line is the only
+ * honest wording:
+ *
+ * - `Provision failed: HTTP <status>` — `provisionProjectStream`'s
+ *   pre-stream branch (a non-2xx response with an unparseable body, e.g. a
+ *   proxy's HTML error page);
+ * - `HTTP <status>: <statusText>` — the plain path's `readErrorBody`
+ *   fallback (same shape, same cause).
+ *
+ * Both literals are SDK-owned (`packages/sdk/src/core/rest/projects-client/
+ * projects.ts`, `packages/sdk/src/core/http/api/client.ts`), so this sniff
+ * is pinned by tests in both directions: a placeholder gets the generic
+ * line, and a real server sentence — which never begins with `HTTP <n>` —
+ * passes through. The match is anchored at the string start and only
+ * affects WORDING in `messageFor`, never control flow, so the worst case of
+ * a false negative is today's generic wording, not a wrong outcome.
+ */
+const LOST_PROVISION_REASON_RE = /^(?:Provision failed: )?HTTP \d{3}(?::|$)/;
+/**
+ * A user-facing message for a failed create.
+ *
+ * `ApiError` field names verified at
+ * `packages/sdk/src/core/http/api/errors.ts:46-55`: `status?: number`,
+ * `code?: string` — branches below read those, not invented names. Both
+ * transports (`provisionProject` and, since final-review FIX 1,
+ * `provisionProjectStream`) throw an `ApiError` carrying the same fields, so
+ * every branch below reads identically regardless of which one ran.
+ *
+ * Managed git being unconfigured is NOT an upstream failure and must not share
+ * its message. `isManagedGitUnavailableError`
+ * (`packages/ui/src/internal/lib/onboarding/provision-errors.ts`) names it by its message: on the wire
+ * it is a 503, but so is every 502, which the API's edge middleware rewrites to
+ * 503 (`apps/api/src/index.ts`, EDGE_REWRITTEN_STATUSES). Managed git
+ * unconfigured is a server-config state no client-side retry can fix. Telling the
+ * user to "try again" there is false: nothing they do changes the outcome
+ * until an operator configures it.
+ *
+ * Any OTHER 502 or 503 shows the server's own reason when one arrived
+ * (KRTX-1754), not a bare retry hint: both transports preserve it — the API's
+ * edge middleware rewrites 502→503 but keeps the JSON body, and the stream
+ * route carries the reason in-band — so the sentence the backend reported
+ * ("GitHub /user/repos failed (403): …", "You have exceeded a secondary rate
+ * limit…", the seed failure's detail) reaches this function intact. The
+ * dogfood evidence that filed the issue is a user told to "try again" with no
+ * signal of what actually failed. The generic retry line is kept ONLY for the
+ * reason-less shapes: the two placeholder sentences the SDK writes when the
+ * response had no JSON body at all (a proxy's HTML error page — the reason is
+ * genuinely lost, `LOST_PROVISION_REASON_RE` below) and an empty message.
+ * This deliberately diverges from the other call sites that reuse
+ * `isManagedGitUnavailableError` (`project-create-modal.tsx:352`,
+ * `add-to-project-modal.tsx:188`) for their 502/503s: they toast a title with
+ * no body, where a raw upstream sentence has nowhere readable to go; the
+ * inline alert on `/new` is the one surface built to carry a full sentence.
+ *
+ * `project_limit_reached` (final-review FIX 2) is checked BEFORE the generic
+ * 403 branch, and deliberately, not folded into it: `enforceProjectQuota`
+ * (`apps/api/src/projects/lib/access.ts`) returns 403 too, and
+ * `FREE_TIER_PROJECT_LIMIT = 1` (`apps/api/src/shared/account-limits.ts`)
+ * means every free-tier user who already has one project and clicks
+ * "Create a workspace…" hits this — not an edge case. The generic 403 message ("You need owner or admin
+ * access…") is actively false for them: they have the role, they are simply
+ * out of quota. The server's own message is reused verbatim rather than
+ * inventing new copy — it already states the exact limit and the upgrade
+ * path, matching what the deleted create modal's `isProjectLimitError`
+ * handling reused for the same code (`provision-errors.ts`).
+ *
+ * `provision_in_flight` (409, final-review FIX 1) also gets its own branch,
+ * never the raw server text: `PROVISION_IN_FLIGHT_CODE`'s own doc comment
+ * (`packages/sdk/src/core/http/api-client.ts`) names the literal string
+ * "idempotency_key" as something that must never reach the user, and the
+ * server's message for this case names it verbatim. By the time this branch
+ * is reached, `runProvisionAttempt`'s own in-band retry (see its doc
+ * comment) has already exhausted its backoff — this is the terminal case,
+ * not the common one.
+ */
+export function messageFor(error) {
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : undefined;
+    if (isProjectLimitError(error)) {
+        return (message || "This account has reached its plan's workspace limit. Upgrade to create another.");
+    }
+    if (status === 403) {
+        return 'You need owner or admin access in this account to create a workspace.';
+    }
+    if (status === 400)
+        return message || 'Check the workspace name and try again.';
+    if (isManagedGitUnavailableError(error)) {
+        return "Managed git isn't set up on this server. A platform admin connects GitHub in the admin console before workspaces can be created.";
+    }
+    if (status === 409) {
+        // Two different 409s reach here now, and they must not share a message.
+        // `provision_in_flight` carries a typed `code`
+        // (`PROVISION_IN_FLIGHT_CODE`); the GitHub sources' 409s do not — they are
+        // "install the Kortix GitHub App first" (`create-repo` and
+        // `link-repository`, `apps/api/src/projects/routes/project-from-repository.ts`) and "no
+        // available repository name near X". Both of those already say exactly
+        // what to do, so the server's own message is reused verbatim rather than
+        // being overwritten with a wait-and-retry line that is simply false for
+        // them.
+        const code = error?.code;
+        if (code === PROVISION_IN_FLIGHT_CODE) {
+            return 'Another attempt to create this workspace is already in progress. Please wait a moment and try again.';
+        }
+        return message || 'Could not create the workspace. Try again.';
+    }
+    // A 503 that is not managed git is an edge-rewritten 502 (`apps/api/src/index.ts`,
+    // EDGE_REWRITTEN_STATUSES): an upstream failure. See the doc comment above:
+    // the server's reason is shown when it arrived; the generic line is for the
+    // shapes where it did not.
+    if (status === 502 || status === 503) {
+        return message && !LOST_PROVISION_REASON_RE.test(message)
+            ? message
+            : 'Could not create the workspace. Try again.';
+    }
+    return message || 'Could not create the workspace. Try again.';
+}
+/**
+ * `POST /projects/create-repo`'s 409 for a personal GitHub account: GitHub does
+ * not accept the App installation token on `POST /user/repos`, so `createRepo`
+ * refuses before the request (`apps/api/src/projects/github.ts`'s
+ * `GitHubPersonalAccountCreateUnsupportedError`). The owner does not change
+ * between attempts, so a retry fails the same way. `POST /projects/provision`
+ * answers the same code when the INSTANCE backend sits on a personal account.
+ */
+const GITHUB_PERSONAL_ACCOUNT_CREATE_UNSUPPORTED = 'github_personal_account_create_unsupported';
+/**
+ * Whether a failed create should offer a retry.
+ *
+ * Classified by whether ANYTHING could plausibly be different on the next
+ * attempt — NOT by "everything except 503". `retry` (below) resends
+ * `lastState` completely unedited, through the SAME `runCreate` path with
+ * the SAME persisted `idempotency_key`, so a failure whose cause cannot
+ * change between now and a later click must not offer one; doing so would
+ * spend the user's next click on a request guaranteed to fail identically.
+ * Fix round 1 finding: the first version of this function offered a retry
+ * for a 400 too, which fails this exact test — see the `status === 400`
+ * branch below.
+ *
+ * - `400` (bad name / invalid payload) — NOT retryable. `retry` resends the
+ *   exact payload that just failed validation; a deterministic validation
+ *   failure on an unchanged payload fails identically every time. Only
+ *   editing the name, through the primary submit button, can help.
+ * - `403` (wrong account / insufficient role) — retryable. Role and account
+ *   membership are external state that CAN genuinely change between the
+ *   failure and a later click, and `retry` re-closes over `creatableAccounts`
+ *   (`useCreateWorkspace`'s own `useAccountsList()` query), which is refetched —
+ *   so a role grant made in the meantime can turn this into a success.
+ * - `502` (bad gateway) — retryable. A transient upstream/gateway fault; a
+ *   later attempt can land differently with no change on the client at all.
+ * - `503` that `isManagedGitUnavailableError`
+ *   (`packages/ui/src/internal/lib/onboarding/provision-errors.ts`) matches — NOT retryable. A server
+ *   configuration state; see `messageFor` above. Any other `503` is an
+ *   edge-rewritten `502` and falls through to the retryable default. Reuses that detector rather than
+ *   re-deriving the 503 check, so this and `messageFor` can never disagree
+ *   about which failure is which.
+ * - `409` (`provision_in_flight`, final-review FIX 1) — retryable. Named
+ *   explicitly rather than left to the default bucket: whether ANOTHER
+ *   attempt with this key is still running is external state by
+ *   definition, and it usually resolves within `runProvisionAttempt`'s own
+ *   in-band backoff before ever reaching here (see that function's doc
+ *   comment) — this branch only fires once that backoff is exhausted, and
+ *   the underlying condition can still clear before the user's next click.
+ * - `409` (`github_personal_account_create_unsupported`) — NOT retryable.
+ *   The chosen owner is a personal GitHub account; the same owner fails the
+ *   same way on every attempt.
+ * - Anything else (a plain network `Error`, an unrecognized status) —
+ *   retryable. There is no signal here that rules out transience, so the
+ *   safer default is to offer the retry rather than silently block a case
+ *   that might actually succeed.
+ *
+ * Adding a new status code this route can return? Decide which bucket above
+ * it belongs to — "the payload/state is deterministic and unchanged" (block
+ * it) vs. "something could genuinely be different next time" (allow it) —
+ * and add its own named branch rather than folding it into the default.
+ */
+export function isRetryableError(error) {
+    const status = error?.status;
+    const code = error?.code;
+    if (status === 400)
+        return false;
+    // The plan cap is a 403 too, but nothing about a retry changes it — only a
+    // plan change does, and the page offers that instead (`limitReached`).
+    // Before the generic 403 fallthrough, which IS retryable (wrong account,
+    // role granted meanwhile).
+    if (isProjectLimitError(error))
+        return false;
+    if (isManagedGitUnavailableError(error))
+        return false;
+    if (code === GITHUB_PERSONAL_ACCOUNT_CREATE_UNSUPPORTED)
+        return false;
+    if (status === 409)
+        return true;
+    return true;
+}
+const defaultClient = {
+    provisionProject,
+    provisionProjectStream,
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Whether a provisioning failure is TRANSPORT-shaped — the stream itself
+ * never reached the server to do real work, as opposed to a real failure the
+ * server reported through a stream that worked. `runProvisionAttempt` (below)
+ * uses this, ALWAYS in combination with "zero events received", as the only
+ * signal that its fallback to the plain `provisionProject` is safe: retrying
+ * a genuine provisioning failure as a second `POST /projects/provision` risks
+ * a second upstream managed repo, so this classifier stays conservative and
+ * recognizes only the three shapes `provisionProjectStream`'s own doc comment
+ * (`packages/sdk/src/core/rest/projects-client/projects.ts`) names as
+ * "stream unavailable" failures:
+ *
+ * - **A raw network failure** — the `fetch()` call itself never got a
+ *   response. Every fetch implementation (browsers, undici/Node, Bun) throws
+ *   a `TypeError` for this, and ONLY for this; a server-returned failure
+ *   (however bad) is always a plain `Error` or `ApiError`, never a
+ *   `TypeError`. Checking the error's real TYPE, not a message string, is
+ *   what keeps this from being the fragile message-sniffing the brief for
+ *   this task explicitly warns against.
+ * - **No `response.body`** — the React Native case. `provisionProjectStream`
+ *   throws the literal message `'...(no response body)'`.
+ * - **The `/projects/provision-stream` route itself 404s** — an older server
+ *   build without it. `provisionProjectStream` throws
+ *   `` `Provision failed: HTTP ${status}` `` when the response is non-2xx and
+ *   carries no JSON `error` field; a REAL API rejection (400/403/503) always
+ *   carries one, and lands in the pre-stream-denial branch below instead.
+ *
+ * Everything else — an in-stream `error` event, a pre-stream non-2xx WITH a
+ * server message (e.g. "Owner or admin role required"), a malformed-frame
+ * parse failure — is a REAL failure and must rethrow, never fall back.
+ */
+export function isTransportFailure(error) {
+    if (error instanceof TypeError)
+        return true;
+    if (!(error instanceof Error))
+        return false;
+    return error.message.includes('no response body') || /\bHTTP 404\b/.test(error.message);
+}
+/**
+ * Runs one logical create to completion.
+ *
+ * POSTs once. On a `409` `provision_in_flight` — another call carrying this
+ * SAME `idempotency_key` is still mid-provision, per
+ * `apps/api/src/projects/routes/projects.ts` — retries up to `RETRY_DELAY_MS.length`
+ * more times with the IDENTICAL payload. Never a re-minted key: the key
+ * identifies the ATTEMPT, and the whole point of retrying is to land on that
+ * same attempt's result. Any other error, or exhausting the retry budget,
+ * rejects with the triggering error unchanged so the caller can classify it
+ * (`messageFor`).
+ */
+export async function runCreateAttempt(payload, client = defaultClient) {
+    for (let attempt = 0; attempt <= RETRY_DELAY_MS.length; attempt += 1) {
+        try {
+            return await client.provisionProject(payload);
+        }
+        catch (caught) {
+            const code = caught?.code;
+            const canRetry = code === PROVISION_IN_FLIGHT_CODE && attempt < RETRY_DELAY_MS.length;
+            if (!canRetry)
+                throw caught;
+            await client.wait(RETRY_DELAY_MS[attempt]);
+        }
+    }
+    // Unreachable: every iteration above either returns or throws.
+    throw new Error('runCreateAttempt: retry loop exited without resolving');
+}
+/**
+ * One provisioning attempt, preferring the live-progress
+ * `provisionProjectStream` and falling back to the plain `runCreateAttempt`
+ * (the 409-retrying `provisionProject` above) in exactly the cases where the
+ * fallback is provably safe.
+ *
+ * THREE failure shapes reach the catch, and they get three different
+ * treatments:
+ *
+ * 1. **A real provisioning failure** — an in-stream `error` frame, a
+ *    pre-stream denial that carried the API's body, a malformed frame — is
+ *    rethrown unchanged for `messageFor` to name. The gate is **whether
+ *    `onEvent` fired at all**, not the shape of the error: if the stream
+ *    delivered even ONE event it reached the server and did real work, so
+ *    any failure after that is genuine. Retrying it as a fresh
+ *    `runCreateAttempt` call would be a SECOND create for the same user
+ *    intent — the exact "two upstream repos" failure this function exists
+ *    to prevent. Only when NOTHING was ever received AND the failure is
+ *    transport-shaped (`isTransportFailure`) is it safe to conclude the
+ *    stream never reached the server, and the fallback runs.
+ *
+ * 2. **A 409 `provision_in_flight`** (final-review FIX 1, consequence 3) —
+ *    reaches the fallback regardless of `eventsReceived`.
+ *    `emit('validating')` is the first statement of `runProvision`
+ *    (`apps/api/src/projects/provision-core.ts`), so by the time this
+ *    failure can arrive at all, `eventsReceived > 0` is already guaranteed
+ *    — under the plain "any event blocks fallback" rule, that made
+ *    `runCreateAttempt`'s own 409 backoff loop unreachable from the
+ *    streaming path. It is deliberately narrower than the
+ *    transport-failure gate, not a loosening of it: by construction another
+ *    call carrying this SAME `idempotency_key` is already mid-provision, so
+ *    handing it to `runCreateAttempt` (identical key, unchanged payload) is
+ *    exactly correct — either the server returns the SAME project once the
+ *    in-flight attempt commits, or it 409s again and the loop keeps waiting
+ *    — never a second upstream repo, and never a second create for this
+ *    user intent.
+ *
+ * 3. **An unterminated stream** (KRTX-1754 — the code
+ *    `PROVISION_STREAM_UNTERMINATED_CODE`, thrown when the socket closes
+ *    before the route's promised terminal `done`/`error` frame) — also
+ *    reaches the fallback, regardless of `eventsReceived`. The close is NOT
+ *    a provisioning failure; it is an UNKNOWN result. The route's handler
+ *    outlives a lost reader (`write()` swallows the disconnect on purpose,
+ *    so it cannot cancel live work), so by the time the client sees the
+ *    close the create may already have committed upstream. The recovery is
+ *    the SAME key replayed through `runCreateAttempt`: the server's
+ *    idempotency machinery (the partial unique index, the 120s in-flight
+ *    window, the replay response) answers with the true outcome — `201`
+ *    with the same project once the first attempt commits, `409
+ *    provision_in_flight` while it is still running (the loop above keeps
+ *    waiting), or the first attempt's real failure after its rollback. This
+ *    is what makes the second symptom impossible: a submit whose stream
+ *    died mid-provision resolves to the real outcome instead of a jargon
+ *    error or, worse, silence. Like the 409 case, this can never mint a
+ *    second upstream repo — the key dedupes it server-side.
+ *
+ * The fallback reuses `payload` UNCHANGED — same `idempotency_key` the
+ * streaming attempt just sent. It is the SAME logical attempt continuing on
+ * a different transport, not a new one; a re-minted key here would be
+ * exactly the bug this function exists to prevent, just moved one layer up.
+ * Routing the fallback through `runCreateAttempt` (rather than a bare
+ * `client.provisionProject` call) also means it inherits that function's own
+ * 409 `provision_in_flight` retry, so the plain-POST path keeps its full
+ * existing resilience even when reached through the stream.
+ *
+ * `onPhase(null)` fires once, right before the fallback runs — there is no
+ * real phase information once the plain POST takes over, and freezing the UI
+ * on the last streamed phase would show progress that stopped being true.
+ */
+export async function runProvisionAttempt(payload, onPhase, client = defaultClient) {
+    let eventsReceived = 0;
+    try {
+        return await client.provisionProjectStream(payload, (event) => {
+            eventsReceived += 1;
+            if (event.type === 'phase')
+                onPhase(event.phase);
+        });
+    }
+    catch (streamFailure) {
+        const code = streamFailure?.code;
+        const isProvisionInFlight = code === PROVISION_IN_FLIGHT_CODE;
+        const isStreamUnterminated = code === PROVISION_STREAM_UNTERMINATED_CODE;
+        if (!isProvisionInFlight &&
+            !isStreamUnterminated &&
+            (eventsReceived > 0 || !isTransportFailure(streamFailure))) {
+            throw streamFailure;
+        }
+        onPhase(null);
+        return runCreateAttempt(payload, client);
+    }
+}
+/**
+ * The one network call this create makes, chosen by `state.source`.
+ *
+ * Every source ends at the same `KortixProject`, which is what lets the
+ * success path in `runCreate` stay single — prime the cache, invalidate, write
+ * the cookie, enter onboarding — instead of growing a copy per source. The
+ * three routes differ only in what they send and which upstream repository
+ * they end up pointing at.
+ *
+ * `idempotencyKey` is non-null only for `managed`; `runCreate` owns that rule
+ * and this function asserts it rather than re-deriving it, so the two can
+ * never disagree about whether a key was minted.
+ */
+async function runSourceAttempt(state, creatableAccounts, idempotencyKey, 
+// `string | null`, not `| undefined`: normalized once at the `runCreate`
+// call site below so every `build*Payload` this function calls receives
+// the same required, non-omittable identity argument they now require.
+userId, client) {
+    if (state.source === 'github-create') {
+        return client.createGitHubRepoProject(buildGitHubCreatePayload(state, creatableAccounts, userId));
+    }
+    if (state.source === 'github-import') {
+        return client.importGitHubRepoProject(buildGitHubImportPayload(state, creatableAccounts, userId));
+    }
+    // `managed` + a chosen repository is an IMPORT of a repository the managed
+    // owner already holds, not a provision of a new one. `/projects/provision`
+    // cannot adopt an existing repository, so it would create a second, empty
+    // one and ignore the choice.
+    if (isManagedImport(state)) {
+        return client.importGitHubRepoProject(buildManagedImportRequest(state, creatableAccounts, userId));
+    }
+    if (!idempotencyKey) {
+        throw new Error('runCreate: the managed source requires an idempotency key');
+    }
+    return client.runCreateAttempt(buildCreatePayload(state, creatableAccounts, idempotencyKey, userId), 
+    // Only the managed provision streams phases; the GitHub branches above
+    // never touch the sink, so their creates render the base handoff screen.
+    client.onPhase);
+}
+/**
+ * The full sequence one submit runs:
+ *
+ * ```
+ * mint/reuse key -> provision (with retry) ->
+ *   [on success only] clear key -> read the account's prior projects ->
+ *   prime cache -> invalidate -> write cookie
+ *   -> [later projects only] stamp onboarded -> hand off to /projects/:id
+ * ```
+ *
+ * **No onboarding wizard in the create flow — for accounts that already have
+ * a project.** The redirect used to go to `/new?onboarding=<id>`, which
+ * mounted the full-screen three-step wizard over the page; the app never
+ * landed on the project by itself (KRTX-1419). The stamp is what keeps the
+ * shell's copy of that wizard from mounting over the landing page instead.
+ *
+ * **A fresh account's first project is the exception (KRTX-2092).** Its
+ * create skips the stamp so the shell's wizard opens on the landing and the
+ * new user gets the work / apps / models steps the signup journey expects;
+ * the wizard's own Skip control closes it in place and opens the first chat.
+ * An unstamped project is only a trap when the wizard has no exit — the
+ * shell passes `onSkip`, so it has one.
+ *
+ * The stamp is best-effort and precedes the handoff: a failed PATCH must not
+ * keep the user off the project that already exists (the same policy as the
+ * wizard's own exits, `completeThenNotify`), but it must be attempted BEFORE
+ * the navigation so the shell's project-detail read cannot race it and mount
+ * the wizard over the landing.
+ *
+ * The key is cleared FIRST among the success-path steps, before any of the
+ * others. The API's own contract (`projects.ts`) is that the key identifies the
+ * ATTEMPT, not the payload — once the server has confirmed this attempt
+ * succeeded, the key must never be replayed, or a LATER, genuinely different
+ * create with the same name would silently return THIS project instead of
+ * making a new one. Clearing it first, rather than last, also means that if
+ * cache priming or the handoff ever throws, the key is already gone
+ * and cannot be resurrected by a subsequent retry.
+ *
+ * On any failure — including exhausting `runCreateAttempt`'s retry budget —
+ * the key is deliberately left untouched, so a user-initiated retry (the
+ * SAME `state`, submitted again) reuses it instead of minting a new one and
+ * risking a second upstream repo.
+ */
+export async function runCreate(state, creatableAccounts, userId, client) {
+    const fingerprint = fingerprintOf(state);
+    // The key belongs to `POST /projects/provision` and nothing else — it is the
+    // only one of the three routes that accepts an `idempotency_key`. Minting one
+    // for a GitHub source would persist a key that is never sent and never
+    // cleared, so `usesIdempotencyKey` gates BOTH the mint and the clear rather
+    // than only the field in the payload.
+    const usesIdempotencyKey = state.source === 'managed' && !isManagedImport(state);
+    const idempotencyKey = usesIdempotencyKey
+        ? client.attemptKeyFor(fingerprint, client.now())
+        : null;
+    try {
+        const project = await runSourceAttempt(state, creatableAccounts, idempotencyKey, userId ?? null, client);
+        if (usesIdempotencyKey)
+            client.clearAttemptKey(fingerprint);
+        // Read BEFORE priming: `primeProjectCache` prepends the new project, so a
+        // read after it can never see the account's pre-create state.
+        const hadProjects = (client.projectsCachedForAccount(project.account_id)?.length ?? 0) > 0;
+        client.primeProjectCache(project.account_id, project);
+        client.invalidateProjects();
+        client.writeLastProjectId(userId, project.project_id);
+        if (hadProjects) {
+            // Best-effort: a failed stamp must not keep the user off the project
+            // that already exists. The accepted failure mode is the wizard running
+            // the next time they open the workspace — the same one
+            // `completeThenNotify` accepts for the wizard's own exits.
+            await client.completeOnboarding(project.project_id).catch(() => { });
+        }
+        client.enterProject(project.project_id);
+        return { ok: true, project };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+/**
+ * Drives the `/new` submit button: mints/reuses the idempotency key, POSTs
+ * the create (with retry-on-in-flight via `runCreateAttempt`), primes the
+ * workspace caches, stamps the project onboarded, and lands the user on the
+ * new project's page on success. All of that sequencing lives in `runCreate`,
+ * above — this hook only wires it to the live `queryClient`/`router`/`user`
+ * and to component state.
+ *
+ * Reads the account list itself — the same user-scoped cache entry
+ * `new-workspace-page.tsx`,
+ * `WorkspaceSwitcher` and `AccountSwitcher` already read — rather than taking
+ * `creatableAccounts` as a parameter, so this hook can resolve the create's
+ * target account (`resolveTargetAccountId`) without a second, page-specific
+ * query.
+ */
+export function useCreateWorkspace() {
+    const router = useUiRouter();
+    const queryClient = useQueryClient();
+    const viewerId = useUiViewerId();
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    // The raw thrown value, not just its formatted message — `canRetry` below
+    // needs to classify it with `isRetryableError`, which reads `.status`, not
+    // the already-rendered string.
+    const [lastError, setLastError] = useState(null);
+    const [lastState, setLastState] = useState(null);
+    // The latest streamed provisioning phase (`runProvision`'s emits, plus
+    // `null` for "the plain POST took over"). `WorkspaceHandoff` renders it as
+    // the step list; `null` renders the base screen, which is also what the
+    // GitHub sources — whose routes stream nothing — show for the whole wait.
+    const [phase, setPhase] = useState(null);
+    const accountsQuery = useAccountsList();
+    const creatableAccounts = useCreatableAccounts(accountsQuery.data ?? []);
+    const create = useCallback(async (state) => {
+        setLastState(state);
+        setStatus('creating');
+        setError(null);
+        // Reset with the attempt: a retry must not start on the previous
+        // attempt's last phase, and every source starts on the base screen.
+        setPhase(null);
+        const result = await runCreate(state, creatableAccounts, viewerId, {
+            attemptKeyFor,
+            clearAttemptKey,
+            // The phase sink is this hook's own state setter: every streamed
+            // phase lands in `phase`, and `runProvisionAttempt`'s fallback fires
+            // `onPhase(null)` through the same sink, clearing it — the handoff
+            // never shows progress that stopped being true.
+            onPhase: setPhase,
+            runCreateAttempt: (payload, onPhase) => runProvisionAttempt(payload, onPhase),
+            // No stream and no idempotency retry on either GitHub route: neither
+            // emits provisioning phases and neither accepts an `idempotency_key`,
+            // so there is nothing for `runProvisionAttempt`'s machinery to do. A
+            // failed attempt surfaces through `messageFor` and the user presses
+            // Try again, which is the whole retry story for these two.
+            // A personal GitHub owner needs the user's own authorization before
+            // GitHub will create the repository (`github-user-authorization.ts`).
+            // One popup, one retry; an organization never reaches it.
+            createGitHubRepoProject: (payload) => createRepoWithGitHubAuthorization(payload, {
+                create: createProjectRepo,
+                requestProof: requestGitHubUserProof,
+                storeToken: storeGitHubUserToken,
+            }),
+            // `linkRepository` answers `{ project, git_connection }`; the
+            // orchestration only ever needs the project, and unwrapping HERE (not
+            // inside `runCreate`) keeps every source's success path identical.
+            importGitHubRepoProject: (payload) => linkRepository(payload).then((response) => response.project),
+            // The optimistic write goes ONLY into the account this workspace
+            // actually belongs to — the one entry a merge here can never get
+            // wrong. `qk.projects.list()` (no account) is a DIFFERENT, sibling
+            // cache entry backing callers that let the API resolve the account,
+            // so hand-merging into it could inject this workspace into the wrong
+            // account's cached list. The invalidate below reaches that slot too,
+            // correctly, via a real fetch instead of a guess.
+            primeProjectCache: (accountId, project) => {
+                queryClient.setQueryData(qk.projects.list(accountId), (existing) => [
+                    project,
+                    ...(existing ?? []),
+                ]);
+            },
+            // `qk.projects.scope()`, NOT `qk.projects.list()`. Under the old flat
+            // keys `['projects']` was a genuine PREFIX of `['projects', accountId]`,
+            // so invalidating it reached every account's list. Under `qk` those two
+            // are SIBLINGS (`'all'` vs `'<id>'`), so `list()` alone would match only
+            // the accountless slot and silently stop refreshing the list this
+            // create just added to. `scope()` is the shared prefix over every form.
+            invalidateProjects: () => void queryClient.invalidateQueries({ queryKey: qk.projects.scope() }),
+            // The pre-create cached list — the SAME entry `primeProjectCache`
+            // writes and the door/selector read, so on the signup journey (door →
+            // selector → /new) it is always warm. `runCreate` reads it before the
+            // prime to decide whether the created project is the account's FIRST:
+            // an unstamped first project is what makes the shell's onboarding
+            // wizard open for a new user (KRTX-2092).
+            projectsCachedForAccount: (accountId) => queryClient.getQueryData(qk.projects.list(accountId)),
+            writeLastProjectId,
+            // The same PATCH the wizard's own exits run — for a LATER project the
+            // create landing directly on the project page is an implicit skip.
+            // A fresh account's FIRST project is left unstamped instead (the
+            // decision reads `projectsCachedForAccount`), so its onboarding wizard
+            // opens on the landing (KRTX-2092).
+            completeOnboarding: (projectId) => setProjectOnboardingComplete(projectId, true),
+            enterProject: (projectId) => router.replace(uiRoutes().project(encodeURIComponent(projectId))),
+            now: Date.now,
+        });
+        if (!result.ok) {
+            setStatus('error');
+            setError(messageFor(result.error));
+            setLastError(result.error);
+        }
+    }, [creatableAccounts, queryClient, router, viewerId]);
+    const retry = useCallback(() => {
+        if (lastState)
+            void create(lastState);
+    }, [create, lastState]);
+    // Gated on `status === 'error'` as well as `isRetryableError`, not just the
+    // latter: `lastError` deliberately outlives one failed attempt (it is
+    // never cleared on success or on the next `create()` call other than by a
+    // fresh failure overwriting it), so without the status check `canRetry`
+    // could still read `true`/`false` from a PREVIOUS failure while a new
+    // create is `'creating'` or has already succeeded.
+    const canRetry = status === 'error' && isRetryableError(lastError);
+    const limitReached = status === 'error' && isProjectLimitError(lastError);
+    return { create, status, error, retry, canRetry, limitReached, phase };
+}