@timekast/factory 1.27.0 → 1.28.1

package/dist/commands/provision.js

@@ -26,13 +26,13 @@ import prompts from 'prompts';
 import { FACTORY_ORG } from '../lib/constants.js';
 import { CLIError } from '../lib/cli-error.js';
 import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, ensureCnameRecord, ensureDnsRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, resolveZoneIdForDomain, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, existingProvisionDomains, ORG_ZONE_NAMES, } from '../lib/cloudflare-api.js';
-import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
+import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, NEON_MAIN_BRANCH, getNeonProjectOrg, listNeonOrgs, resolveNeonOrg, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
 import { defaultEnvPath, readEnvKeyNames, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
 import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, getVercelProjectByName, GitHubAppNotInstalledError, linkGitRepo, listProjectDomains, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, removeVercelProject, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, VERCEL_AUTO_APEX, writeVercelProjectJson, } from '../lib/vercel-env.js';
 import { decideInitialMigration, hasGeneratedMigrations, MIGRATION_SKIP_MESSAGES, MIGRATIONS_DIR, } from '../lib/initial-migration.js';
 import { writeBacklogLocalCreds, writeE2eLocalCreds, writeEmailLocalCreds, writeEnvLocal, } from '../lib/env-file.js';
-import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
+import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readRemintState, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
  * `setup:e2e`) reads to create an ISOLATED Neon branch per CI run. provision sets
@@ -206,6 +206,8 @@ export function parseProvisionFlags(argv) {
         services: parseServices(readValueFlag(argv, 'services')),
         team: readValueFlag(argv, 'team'),
         orgId: readValueFlag(argv, 'org-id'),
+        neonOrg: readValueFlag(argv, 'neon-org'),
+        remint: argv.includes('--remint'),
         slug: readValueFlag(argv, 'slug'),
         repo: parseRepoFlag(readValueFlag(argv, 'repo')),
         domain: readValueFlag(argv, 'domain'),
@@ -229,11 +231,18 @@ const SERVICE_LABEL = {
     dns: 'DNS + Resend (dominio del entorno)',
     backlog: 'Backlog central (proyecto en backlog.timekast.mx + API key)',
 };
-/** Build the ordered plan: each requested service is `skip` if complete, else `create`. */
-function buildPlan(services, state) {
+/**
+ * Build the ordered plan: each requested service is `skip` if complete, else
+ * `create`.
+ *
+ * `remint` forces the `neon` step to run even when complete — the whole point of
+ * that flag is to re-enter a finished step, so skipping it here would make the flag
+ * a silent no-op. It changes nothing for any other service.
+ */
+function buildPlan(services, state, opts = {}) {
     return services.map((service) => ({
         service,
-        action: isServiceComplete(state, service) ? 'skip' : 'create',
+        action: isServiceComplete(state, service) && !(opts.remint && service === 'neon') ? 'skip' : 'create',
     }));
 }
 /** Print the plain-text plan (the `--dry-run` and pre-run narration). */
@@ -436,6 +445,51 @@ function neonErrorToCliError(error, projectName, context) {
             return new CLIError(`Falló la llamada a Neon en ${context}: ${error.message}`);
     }
 }
+/**
+ * The branch name the E2E runner clones its throwaway branches FROM, for this repo.
+ *
+ * Read from the repo's own workflow (`E2E_PARENT_BRANCH:` in
+ * `.github/workflows/e2e.yml`), because that is where the value actually lives and the
+ * runner honors the same one (`resolveParentBranchName` in `scripts/tools/neon-branch.ts`).
+ * A provisioned derivative pins `develop` there; the Factory itself pins `production`,
+ * and a project is free to pin anything. Returns `null` when there is no workflow or no
+ * pin — the caller then falls back to `develop` and finally to the project's default
+ * branch.
+ *
+ * 🔴 Assuming `develop` here is what broke `--remint` on the Factory, whose Neon project
+ * has a single branch called `production`: the re-mint would have refused (or, worse,
+ * pushed a DATABASE_URL for a branch the runner never parents on).
+ */
+export function readE2eParentBranch(rootDir) {
+    try {
+        const workflow = readFileSync(join(rootDir, '.github', 'workflows', 'e2e.yml'), 'utf8');
+        const match = workflow.match(/^\s*E2E_PARENT_BRANCH:\s*(\S+)/m);
+        const pinned = match?.[1];
+        // The template ships the placeholder with its anchor comment; an unsubstituted
+        // placeholder is not a branch name.
+        if (!pinned || pinned.startsWith('__'))
+            return null;
+        return pinned;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the branch whose connection string becomes the E2E `DATABASE_URL` secret, on
+ * a project that ALREADY exists. Preference: the repo's pinned parent branch → a branch
+ * literally named `develop` (what provision creates) → the project's default branch.
+ *
+ * Never creates anything: a re-mint repairs credentials, and creating a branch to
+ * satisfy a credential refresh would be a side effect nobody asked for.
+ */
+function pickE2eBranch(branches, pinnedName) {
+    const byName = (name) => branches.find((b) => b.name === name);
+    return ((pinnedName ? byName(pinnedName) : undefined) ??
+        byName(NEON_DEVELOP_BRANCH) ??
+        branches.find((b) => b.isDefault) ??
+        branches[0]);
+}
 /** The GitHub repo (`owner/name`) the project-scoped secret is pushed to. */
 function neonSecretRepo(state) {
     // `state.github.repo` carries the RESOLVED repo: `runProvision` seeds it before
@@ -464,13 +518,22 @@ async function setGithubSecret(key, value, repo) {
  * after `develop`, so a mid-step failure leaves a resumable partial state
  * (issue §6 + §8 Gherkin).
  *
- * Endpoint order (asserted by the unit test): POST /projects → POST branches
- * (develop) → GET connection_uri (main) → GET connection_uri (develop) →
- * POST /api_keys → `gh secret set`.
+ * Endpoint order (asserted by the unit test): GET /users/me/organizations (only
+ * when the org is not already known) → POST /projects → POST branches (develop) →
+ * GET connection_uri (develop) → POST /organizations/{org_id}/api_keys →
+ * `gh secret set`.
+ *
+ * The org resolution sits AFTER the `apiKeySecretDone` guard on purpose: a
+ * completed Neon step must still make zero network calls.
  *
  * `--resume` short-circuits ENTIRELY when `state.neon.projectId` already exists
  * (caller skips the step via `isServiceComplete`; this is a defensive guard too).
+ * `deps.remint` is the one switch that deliberately re-enters a completed step.
  *
+ * @returns the project-scoped key minted in THIS run, or `null` when nothing was
+ *   minted (completed step, no remint). The value is a credential: it is never
+ *   persisted to the state, only handed to the caller so the `.env.local` step of
+ *   the same process can write it.
  * @throws {CLIError} mapping the Neon §8 edges (401/402/409/429) and a `develop`
  *   failure (state saved partial → resumable). A failed `gh secret set` does NOT
  *   abort: it records `apiKeySecretPending` and reports (issue §8).
@@ -479,8 +542,10 @@ export async function provisionNeon(rootDir, state, deps = {}) {
     // Fully complete only when the FINAL step landed (key minted + stored as the GH
     // secret). developBranchId alone is NOT "done": re-entering must finish the
     // remaining steps WITHOUT re-minting the key. Every sub-step below is idempotent.
-    if (state.neon?.apiKeySecretDone)
-        return;
+    // `--remint` is the deliberate exception: it exists to re-issue a key that was
+    // revoked out-of-band, which is the one case a "done" step must be re-entered.
+    if (state.neon?.apiKeySecretDone && !deps.remint)
+        return null;
     const envPath = deps.envPath ?? defaultEnvPath();
     const apiKey = readNeonApiKey(envPath);
     if (!apiKey) {
@@ -489,16 +554,72 @@ export async function provisionNeon(rootDir, state, deps = {}) {
     }
     const setSecret = deps.setSecret ?? setGithubSecret;
     const apiDeps = { fetchImpl: deps.fetchImpl };
-    // Neon org-id from the rail (`NEON_ORGANIZATION_ID`), like the Vercel team-id —
-    // org-fixed config, not hardcoded. Neon REQUIRES it for org-scoped API keys.
-    const orgId = readGateValue('NEON_ORGANIZATION_ID', envPath) ?? undefined;
+    // See `persistState`: an adopted stack's state file must not be overwritten with
+    // this step's shape. `saveState` is the ONLY writer below.
+    const persist = deps.persistState ?? true;
+    const saveState = () => {
+        if (persist)
+            writeProvisionState(rootDir, state);
+    };
+    // WHICH org. Three sources, and which one applies depends on whether the project
+    // already exists — that distinction is the whole point:
+    //   - already recorded in the state → use it verbatim, no call, no guessing;
+    //   - exists in Neon but the state predates `orgId` (or this is a --remint on an
+    //     older stack) → ask Neon which org owns that project ID (`getNeonProjectOrg`);
+    //   - brand new → resolve the selector / the rail default / the only org.
+    // Pointing a teardown or a re-mint at the default instead of the project's real
+    // org is exactly the class of error this whole change is fixing.
+    let orgId = state.neon?.orgId;
+    if (!orgId) {
+        try {
+            if (state.neon?.projectId) {
+                // 🔴 BY ID, not by name. Asking which project is called like this repo's folder
+                // fails for almost every real project — they are named by hand in the console
+                // (`Aditivo CRM`, `agent-fimubac`) — and the fallback then aims at the default
+                // org: silently right inside it, `404 project not found` outside. Both happened
+                // the same afternoon. With the id recorded, one GET answers it exactly.
+                orgId = (await getNeonProjectOrg(apiKey, state.neon.projectId, apiDeps)) ?? undefined;
+                if (!orgId) {
+                    throw new CLIError(`El proyecto Neon \`${state.neon.projectId}\` que registra el estado de este ` +
+                        'repo no existe o la key del rail no lo alcanza.\n' +
+                        '  Si el proyecto se borró, reconstruye el estado con `factory provision --adopt ' +
+                        '--force`. Si existe, revisa que la `NEON_API_KEY` del rail sea la de la cuenta ' +
+                        'de servicio con acceso a su organización.');
+                }
+            }
+            if (!orgId) {
+                const selector = deps.neonOrg ?? readGateValue('NEON_ORG', envPath) ?? undefined;
+                orgId = (await resolveNeonOrg(apiKey, selector, apiDeps)).id;
+            }
+        }
+        catch (error) {
+            if (error instanceof CLIError)
+                throw error;
+            if (error instanceof NeonApiError) {
+                throw neonErrorToCliError(error, state.projectName, 'resolver la organización de Neon');
+            }
+            // resolveNeonOrg throws plain Errors whose message is already the es-MX text the
+            // user needs; surface it as-is.
+            throw new CLIError(error instanceof Error ? error.message : String(error));
+        }
+    }
     // 1. Reuse the project from a partial run; create it only if missing. Persist it
     //    immediately so a branch failure leaves projectId + mainBranchId durable.
+    //
+    // 🔴 A RECORDED `projectId` is sufficient to reuse, and this is not a style
+    // preference. This condition used to require `mainBranchId` too, so a state that
+    // carried the project but not that branch fell through to CREATE — and produced a
+    // SECOND Neon project for a derivative that already had one, with the CLI then
+    // pointing the repo's secrets and `.env.local` at the empty one. That is exactly
+    // what happened on a real client repo (2026-09-12) the first time `--remint` ran
+    // over an adopted stack, whose shape never recorded `mainBranchId`.
+    // When the primary branch is genuinely needed (only to parent a missing `develop`),
+    // it is resolved from Neon below — never by creating anything.
     let projectId;
     let mainBranchId;
-    if (state.neon?.projectId && state.neon?.mainBranchId) {
+    if (state.neon?.projectId) {
         projectId = state.neon.projectId;
-        mainBranchId = state.neon.mainBranchId;
+        mainBranchId = state.neon.mainBranchId ?? '';
     }
     else {
         let project;
@@ -513,31 +634,73 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         }
         projectId = project.projectId;
         mainBranchId = project.mainBranchId;
-        state.neon = { projectId, mainBranchId, developBranchId: '' };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId: '' };
+        saveState();
     }
     // 2. CLEAN `develop` branch — reuse the recorded id; else create it (idempotent
     //    on a 409: createDevelopBranch reuses an existing develop) and persist the id
     //    IMMEDIATELY (FIX 6 — it was saved only at step 3, so a connection-string
     //    failure lost it and the resume re-created → 409).
     let developBranchId = state.neon?.developBranchId ?? '';
+    if (!developBranchId && deps.remint) {
+        // A re-mint over a project whose working branch the state never recorded (an
+        // adopted stack) resolves it from Neon, honoring whatever this repo pinned as the
+        // E2E parent. It must NOT create a branch: see `pickE2eBranch`.
+        let branches;
+        try {
+            branches = await listNeonBranches(apiKey, projectId, apiDeps);
+        }
+        catch (error) {
+            if (error instanceof NeonApiError) {
+                throw neonErrorToCliError(error, state.projectName, 'listar los branches del proyecto');
+            }
+            throw error;
+        }
+        const picked = pickE2eBranch(branches, readE2eParentBranch(rootDir));
+        if (!picked) {
+            throw new CLIError(`El proyecto Neon \`${projectId}\` no reporta ningún branch, así que no puedo ` +
+                'saber de cuál sacar el `DATABASE_URL` de E2E. Revísalo en la consola de Neon.');
+        }
+        developBranchId = picked.id;
+        console.log(`  · Branch de E2E para el \`DATABASE_URL\`: ${picked.name}`);
+    }
     if (!developBranchId) {
+        // The parent of a new `develop` is the project's primary branch. An adopted state
+        // does not record it, so resolve it from Neon rather than assume — and rather than
+        // let a create run with an empty parent.
+        if (!mainBranchId) {
+            try {
+                const branches = await listNeonBranches(apiKey, projectId, apiDeps);
+                mainBranchId =
+                    branches.find((b) => b.name === NEON_MAIN_BRANCH)?.id ?? branches[0]?.id ?? '';
+            }
+            catch (error) {
+                if (error instanceof NeonApiError) {
+                    throw neonErrorToCliError(error, state.projectName, 'leer los branches del proyecto para ubicar el branch primario');
+                }
+                throw error;
+            }
+            if (!mainBranchId) {
+                throw new CLIError(`El proyecto Neon \`${projectId}\` no reporta ningún branch, así que no puedo ` +
+                    'crear `develop` sin inventar recursos. Revísalo en la consola de Neon.');
+            }
+        }
         try {
             developBranchId = await createDevelopBranch(apiKey, projectId, mainBranchId, apiDeps);
         }
         catch (error) {
             // Save the partial state (issue §8 Gherkin: "guarda el state parcial").
             // IDs only — never a connection string (those are re-derived from Neon on demand).
-            state.neon = { projectId, mainBranchId, developBranchId: '' };
-            writeProvisionState(rootDir, state);
+            state.neon = { projectId, orgId, mainBranchId, developBranchId: '' };
+            saveState();
             if (error instanceof NeonApiError) {
                 throw new CLIError(`El proyecto Neon se creó pero falló la creación del branch \`develop\` (${error.message}).\n` +
                     'El estado parcial se guardó; reintenta con `--resume` para crear solo el branch develop.');
             }
             throw error;
         }
-        state.neon = { projectId, mainBranchId, developBranchId };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId };
+        saveState();
     }
     // 3. Read the develop branch's POOLED connection string (idempotent GET) — the
     //    ONLY string this step needs, for the E2E `DATABASE_URL` secret below. provision
@@ -554,14 +717,25 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         }
         throw error;
     }
-    // 4. Mint a PROJECT-SCOPED API key (blast radius = this project only). Only the
-    //    `apiKeySecretDone` guard above prevents re-minting; a resume after a pending
-    //    secret push DOES re-mint (the prior key value was never persisted — it is a
-    //    credential) and the old key is left orphaned. Acceptable: it only happens
-    //    when the GH secret push keeps failing (e.g. the repo does not exist yet).
+    // 4. Mint a PROJECT-SCOPED API key — blast radius = this project only, and now
+    //    actually so: the key comes from `POST /organizations/{org_id}/api_keys`,
+    //    which 404s on a sibling project (the old `POST /api_keys` silently returned
+    //    a personal, all-orgs key). Only the `apiKeySecretDone` guard above prevents
+    //    re-minting; a resume after a pending secret push DOES re-mint (the prior key
+    //    value was never persisted — it is a credential) and the old key is left
+    //    orphaned. Acceptable: it only happens when the GH secret push keeps failing
+    //    (e.g. the repo does not exist yet).
+    const keyName = `${state.projectName}-e2e`;
     let projectKey;
     try {
-        projectKey = await createProjectApiKey(apiKey, projectId, `${state.projectName}-e2e`, apiDeps);
+        // `--remint` revokes the live key BEFORE issuing its replacement, so the org
+        // does not accumulate a key per rotation. Best-effort by contract: a key that
+        // was already revoked out-of-band (the case that motivated --remint) is a
+        // no-op here, not an error.
+        if (deps.remint) {
+            await deleteNeonApiKeysByName(apiKey, orgId, keyName, apiDeps);
+        }
+        projectKey = await createProjectApiKey(apiKey, orgId, projectId, keyName, apiDeps);
     }
     catch (error) {
         if (error instanceof NeonApiError) {
@@ -579,17 +753,19 @@ export async function provisionNeon(rootDir, state, deps = {}) {
         await setSecret(NEON_KEY_SECRET, projectKey, repo);
         await setSecret(NEON_PROJECT_ID_SECRET, projectId, repo);
         await setSecret(E2E_DATABASE_URL_SECRET, developDatabaseUrl, repo);
-        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretDone: true };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId, apiKeySecretDone: true };
+        saveState();
+        return projectKey;
     }
     catch {
-        state.neon = { projectId, mainBranchId, developBranchId, apiKeySecretPending: true };
-        writeProvisionState(rootDir, state);
+        state.neon = { projectId, orgId, mainBranchId, developBranchId, apiKeySecretPending: true };
+        saveState();
         console.warn(`⚠ No se pudieron guardar los secrets de E2E ` +
             `(\`${NEON_KEY_SECRET}\`/\`${NEON_PROJECT_ID_SECRET}\`/\`${E2E_DATABASE_URL_SECRET}\`) ` +
             `en \`${neonSecretRepo(state)}\` (¿el repo no existe aún o falta permiso?).\n` +
             '  La API key project-scoped se creó; reintenta con `--resume` cuando el repo exista.');
     }
+    return projectKey;
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // BSYNC-003 — `backlog`: register the project in backlog.timekast.mx
@@ -961,13 +1137,18 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     else if (envLocal === 'skipped') {
         console.log('  ⏭ .env.local ya existía (no se sobrescribe — usa --force para regenerarlo)');
     }
-    // Local E2E creds: write NEON_API_KEY (the org key from the rail — already on the
-    // dev's host) + NEON_PROJECT_ID so `pnpm test:e2e` runs locally with zero manual
+    // Local E2E creds: write the PROJECT-SCOPED key minted by `provisionNeon` in this
+    // same process + NEON_PROJECT_ID, so `pnpm test:e2e` runs locally with zero manual
     // `setup:e2e`. Both are PROVISION_OWNED → never pushed to Vercel. Safe on a skipped
-    // `.env.local` (setEnvLine touches only these two keys). The key value is never printed.
-    if (state.neon?.projectId &&
-        writeE2eLocalCreds(rootDir, state.neon.projectId, readNeonApiKey(envPath))) {
-        console.log('  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)');
+    // `.env.local` (setEnvLine touches only these two keys). The key value is never
+    // printed. NEVER falls back to the rail key: that is what leaked an all-orgs
+    // credential into every derivative's `.env.local`.
+    const e2eKey = deps.neonProjectKey ?? null;
+    if (state.neon?.projectId && writeE2eLocalCreds(rootDir, state.neon.projectId, e2eKey)) {
+        console.log(e2eKey
+            ? '  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)'
+            : '  ＋ .env.local (NEON_PROJECT_ID) · ⚠ sin NEON_API_KEY: la key de este run no se acuñó — ' +
+                'córrelo con `--remint` para refrescarla');
     }
     // Email config: write the org Resend key (from the rail) + the fixed EMAIL_FROM so local
     // sends (`invite:admin`, magic-link, `db:seed`) DELIVER instead of the console fallback.
@@ -2555,15 +2736,28 @@ function printClientDomainPlan(domain, interim, route, confirm) {
  * `vercel` (PROV-003) and `dns` (PROV-005) are implemented. `teamId` is required
  * for the Vercel + GitHub + DNS steps (validated upstream).
  */
-async function runServiceStep(service, rootDir, state, flags) {
+async function runServiceStep(service, rootDir, state, flags, 
+/**
+ * Carries the project-scoped Neon key from the `neon` step to the `vercel` step
+ * (which writes `.env.local`) WITHIN this process. A credential, so it is never
+ * persisted — the state has no field for it and must not grow one.
+ */
+runCtx = {}) {
     switch (service) {
         case 'neon':
-            await provisionNeon(rootDir, state);
+            runCtx.neonProjectKey = await provisionNeon(rootDir, state, {
+                neonOrg: flags.neonOrg,
+                remint: flags.remint,
+                persistState: runCtx.persistState,
+            });
             break;
         case 'vercel':
             // PROV-003: push env (teamId on every call) + write .vercel/project.json +
             // pnpm install. The Vercel PROJECT itself is created by PROV-004.
-            await provisionVercel(rootDir, state, flags.team, { force: flags.force });
+            await provisionVercel(rootDir, state, flags.team, {
+                force: flags.force,
+                neonProjectKey: runCtx.neonProjectKey,
+            });
             break;
         case 'github':
             // PROV-004: git substrate (rename → remote add → push main) + create the
@@ -2700,25 +2894,48 @@ function projectsToCandidates(projects, slug, teamId) {
     }));
 }
 /**
- * Reconstruct the Neon project id + `develop` branch id (read-only). Filters the
- * org's projects by slug; once the project resolves, lists its branches to find
- * the `develop` one. A branch lookup failure leaves the branch id `unknown`
- * without failing the whole adopt (issue §4).
+ * Reconstruct the Neon project id + its org + the `develop` branch id (read-only).
+ *
+ * Sweeps EVERY org the rail key can reach (`GET /users/me/organizations`, then one
+ * project listing per org) and filters by slug across all of them. The org is
+ * therefore READ OFF the project that matches — never taken from a configured
+ * default, which may well point somewhere else: a backfill that recorded the
+ * default's org id would aim a later `--destroy` at the wrong organization.
+ *
+ * The per-org listing still passes `org_id`, which Neon REQUIRES (it answers
+ * `400 org_id is required` without it).
+ *
+ * Once the project resolves, lists its branches to find the `develop` one. A branch
+ * lookup failure leaves the branch id `unknown` without failing the whole adopt
+ * (issue §4).
  */
-async function adoptNeon(slug, apiKey, orgId, deps, recordAmbiguity) {
-    const projects = await listNeonProjects(apiKey, orgId, { fetchImpl: deps.fetchImpl });
-    const candidates = matchProjectsBySlug(projects, slug).map((p) => ({
-        id: p.id,
-        name: p.name,
-        url: `https://console.neon.tech/app/projects/${p.id}`,
-    }));
+async function adoptNeon(slug, apiKey, deps, recordAmbiguity) {
+    const apiDeps = { fetchImpl: deps.fetchImpl };
+    const orgs = await listNeonOrgs(apiKey, apiDeps);
+    const candidates = [];
+    /** projectId → owning org id, so the chosen candidate can report its org. */
+    const orgOfProject = new Map();
+    let scanned = 0;
+    for (const org of orgs) {
+        const projects = await listNeonProjects(apiKey, org.id, apiDeps);
+        scanned += projects.length;
+        for (const p of matchProjectsBySlug(projects, slug)) {
+            orgOfProject.set(p.id, org.id);
+            candidates.push({
+                id: p.id,
+                name: `${p.name} · ${org.name}`,
+                url: `https://console.neon.tech/app/projects/${p.id}`,
+            });
+        }
+    }
     if (candidates.length === 0) {
-        console.log(`  · Ningún proyecto de Neon se parece a \`${slug}\` (revisé ${projects.length} de la org) — \`neonProjectId: unknown\`.`);
-        return { projectId: null, branchDevId: null };
+        console.log(`  · Ningún proyecto de Neon se parece a \`${slug}\` (revisé ${scanned} en ${orgs.length} organización(es)) — \`neonProjectId: unknown\`.`);
+        return { projectId: null, orgId: null, branchDevId: null };
     }
     const projectId = await resolveCandidate('Neon', candidates, deps, recordAmbiguity);
     if (!projectId)
-        return { projectId: null, branchDevId: null };
+        return { projectId: null, orgId: null, branchDevId: null };
+    const orgId = orgOfProject.get(projectId) ?? null;
     // Resolve the develop branch (best-effort — a failure → unknown, not a hard stop).
     let branchDevId = null;
     try {
@@ -2728,7 +2945,7 @@ async function adoptNeon(slug, apiKey, orgId, deps, recordAmbiguity) {
     catch {
         branchDevId = null;
     }
-    return { projectId, branchDevId };
+    return { projectId, orgId, branchDevId };
 }
 /**
  * Reconstruct the GitHub repo (read-only) via `gh repo view {org}/{slug} --json
@@ -2939,17 +3156,16 @@ export async function runAdopt(flags, deps = {}) {
     // Neon (GET /projects + branches) — needs the rail key. Absent → `unknown` (the
     // Gherkin "Provider Neon sin token disponible" path).
     let neonProjectId = null;
+    let neonOrgId = null;
     let neonBranchDevId = null;
     const neonApiKey = readNeonApiKey(envPath);
-    // Same rail value the create path threads (`NEON_ORGANIZATION_ID`): Neon REQUIRES
-    // it on an org-scoped key, and answers `400 org_id is required` without it.
-    const neonOrgId = readGateValue('NEON_ORGANIZATION_ID', envPath) ?? undefined;
     if (neonApiKey) {
         try {
-            const neon = await adoptNeon(slug, neonApiKey, neonOrgId, adeps, (list) => {
+            const neon = await adoptNeon(slug, neonApiKey, adeps, (list) => {
                 candidates.neon = list;
             });
             neonProjectId = neon.projectId;
+            neonOrgId = neon.orgId;
             neonBranchDevId = neon.branchDevId;
         }
         catch {
@@ -2971,6 +3187,7 @@ export async function runAdopt(flags, deps = {}) {
         slug,
         vercelProjectId: vercelProjectId ?? ADOPT_UNKNOWN,
         neonProjectId: neonProjectId ?? ADOPT_UNKNOWN,
+        neonOrgId: neonOrgId ?? ADOPT_UNKNOWN,
         neonBranchDevId: neonBranchDevId ?? ADOPT_UNKNOWN,
         githubRepo: githubRepo ?? ADOPT_UNKNOWN,
         domains,
@@ -2983,6 +3200,7 @@ export async function runAdopt(flags, deps = {}) {
         slug,
         vercelProjectId: partial.vercelProjectId,
         neonProjectId: partial.neonProjectId,
+        neonOrgId: partial.neonOrgId,
         neonBranchDevId: partial.neonBranchDevId,
         githubRepo: partial.githubRepo,
         domains,
@@ -3093,18 +3311,44 @@ async function destroyNeonBranch(target, apiKey, fetchImpl) {
  * project id, so it also tears down a PARTIAL stack whose develop branch never got
  * created (FIX 9). A 404 → already gone (§8). The dev's key does this, never the
  * shared org create-only key.
+ *
+ * The org id is resolved BEFORE the nuke, because after it the project is gone and
+ * nothing can say which org owned it any more. It comes from the state when present
+ * and is asked of Neon BY PROJECT ID otherwise (every stack provisioned before `orgId`
+ * existed takes that path). Unresolvable → the project is still nuked and only the key
+ * cleanup is skipped, with the key named so it can be revoked by hand.
  */
 async function destroyNeonProject(target, apiKey, fetchImpl) {
     const resource = `Neon project (${target.neonProjectId})`;
     if (!target.neonProjectId) {
         return { resource: 'Neon project', status: 'skipped', detail: 'sin id en el estado' };
     }
+    const keyName = `${target.slug}-e2e`;
+    let orgId = target.neonOrgId;
+    if (!orgId) {
+        // BY ID (see `getNeonProjectOrg`): the project's name in the console rarely equals
+        // the repo's slug, so the by-name sweep this used to do found nothing for most real
+        // projects — and the key cleanup was then skipped for no good reason.
+        try {
+            orgId = await getNeonProjectOrg(apiKey, target.neonProjectId, { fetchImpl });
+        }
+        catch {
+            orgId = null;
+        }
+    }
     try {
         await deleteNeonProject(apiKey, target.neonProjectId, { fetchImpl });
+        if (!orgId) {
+            return {
+                resource,
+                status: 'removed',
+                detail: `proyecto eliminado (nuke) — no pude resolver la org, revoca \`${keyName}\` a mano`,
+            };
+        }
         // Project gone — clean the project-scoped API key(s) it minted (`{slug}-e2e`)
         // so the Neon org does not accumulate dead keys across provisions/tests.
         // Best-effort (never throws): the project nuke already succeeded.
-        const keysDeleted = await deleteNeonApiKeysByName(apiKey, `${target.slug}-e2e`, { fetchImpl });
+        const keysDeleted = await deleteNeonApiKeysByName(apiKey, orgId, keyName, { fetchImpl });
         return {
             resource,
             status: 'removed',
@@ -3601,17 +3845,51 @@ export async function runProvision(flags) {
     if (flags.force) {
         clearProvisionState(rootDir);
     }
+    // `--remint` re-enters an EXISTING stack by definition: it re-issues the key of a
+    // project that is already provisioned. Requiring `--resume` alongside it would be a
+    // trap with no upside — there is nothing to start fresh — so it reads the state the
+    // same way a resume does, and the existing-state guard below lets it through.
+    const reentersState = flags.resume || flags.remint || standaloneDomain;
     let state = null;
-    if ((flags.resume || standaloneDomain) && !flags.force) {
-        state = readProvisionState(rootDir); // throws CLIError on corrupt → hints --force
+    // A `--remint` reads the state through the SHAPE-TOLERANT reader, because the whole
+    // existing fleet carries the adopted shape (`slug`/`neonProjectId`, no `neon` block)
+    // and `readProvisionState` rejects it. Without this, the one command written to
+    // repair those projects failed on exactly them. When that shape is what we got, the
+    // step must not persist (see `persistState`): writing this step's shape over an
+    // adopted file would drop `vercelProjectId`, `githubRepo` and the domains.
+    let remintOverAdopted = false;
+    if (reentersState && !flags.force) {
+        try {
+            state = readProvisionState(rootDir); // throws CLIError on corrupt → hints --force
+        }
+        catch (error) {
+            // `readProvisionState` THROWS on a shape it does not recognize, and the adopted
+            // shape is one of those — so for a re-mint the throw is not an error, it is the
+            // signal to read the other shape. Any other flag keeps the original behavior:
+            // a genuinely corrupt file must still abort loudly.
+            if (!flags.remint)
+                throw error;
+            state = null;
+        }
+        if (!state && flags.remint) {
+            state = readRemintState(rootDir);
+            remintOverAdopted = state !== null;
+        }
         if (!state) {
             throw new CLIError(standaloneDomain
                 ? '`--domain` en modo patch requiere un provision existente (`.timekast/provision.json`), ' +
                     'pero no hay estado. Corre el provision inicial (`--services=...`) primero.'
-                : 'No hay estado de provision para retomar (`--resume`). Corre sin `--resume` para empezar.');
+                : flags.remint
+                    ? '`--remint` reacuña la key de un proyecto YA provisionado, pero no hay estado ' +
+                        '(`.timekast/provision.json`) en este directorio. Corre el provision inicial ' +
+                        '(`--services=neon`) primero.'
+                    : 'No hay estado de provision para retomar (`--resume`). Corre sin `--resume` para empezar.');
         }
     }
-    else if (!flags.force && flags.services.length > 0 && hasProvisionState(rootDir)) {
+    else if (!flags.force &&
+        !flags.remint &&
+        flags.services.length > 0 &&
+        hasProvisionState(rootDir)) {
         // A fresh (non-resume, non-force) service run must not clobber a prior state.
         throw new CLIError('Ya existe un estado de provision (`.timekast/provision.json`). ' +
             'Usa `--resume` para retomarlo o `--force` para descartarlo y empezar de cero.');
@@ -3629,7 +3907,7 @@ export async function runProvision(flags) {
     const repoSlug = flags.services.includes('github') || flags.services.includes('neon')
         ? await resolveRepoSlug(rootDir, projectName, state?.github?.repo, flags.repo, gitInDir)
         : undefined;
-    const steps = buildPlan(flags.services, state);
+    const steps = buildPlan(flags.services, state, { remint: flags.remint });
     const result = {
         projectName,
         lifecycle: state?.lifecycle ?? lifecycle,
@@ -3692,20 +3970,35 @@ export async function runProvision(flags) {
     }
     // Ensure the state dir exists + a baseline file before the first step, so a
     // step failure on the very first service still leaves a resumable state.
-    writeProvisionState(rootDir, runState);
+    //
+    // 🔴 Never for a re-mint over an ADOPTED stack. This baseline write is the one that
+    // actually clobbered a client repo's adopted state file on 2026-09-12: the step
+    // itself was already guarded, and this line — three screens away from it — was not.
+    // An adopted file holds `vercelProjectId`, `githubRepo` and the domains, none of
+    // which this shape carries, so writing it here loses them for good.
+    if (!remintOverAdopted)
+        writeProvisionState(rootDir, runState);
     // 5.0. Initial migration (GAP-001) — BEFORE the steps, so the `.sql` is committed
     //      before the `github` step pushes `main` and Vercel builds the remote tree
     //      (`vercel-build` = `pnpm build && pnpm db:migrate`). A failed generate/install
     //      aborts here, with nothing pushed and nothing deployed.
     await ensureInitialMigration(rootDir, greenfield);
+    // In-memory carrier for the project-scoped Neon key (see `runServiceStep`), plus
+    // whether this run may persist the step-by-step state at all.
+    const runCtx = {
+        persistState: !remintOverAdopted,
+    };
     for (const step of steps) {
         if (step.action === 'skip')
             continue;
-        await runServiceStep(step.service, rootDir, runState, flags);
+        await runServiceStep(step.service, rootDir, runState, flags, runCtx);
         // Persist after each create. PROV-002 (neon) already writes its state
         // atomically inside the step; the remaining stubs record nothing yet, and
-        // this write keeps the baseline durable for them too.
-        writeProvisionState(rootDir, runState);
+        // this write keeps the baseline durable for them too. Skipped entirely for a
+        // re-mint over an adopted stack, whose state file is a different shape we must
+        // not overwrite.
+        if (!remintOverAdopted)
+            writeProvisionState(rootDir, runState);
     }
     // 5a. Retry the E2E GitHub Secrets if Neon recorded them pending. Neon runs BEFORE
     //     the git substrate, so on a fresh bootstrap the repo may not exist yet when it
@@ -3716,16 +4009,25 @@ export async function runProvision(flags) {
     //     Without this, CI E2E stays credential-less until a MANUAL `--resume`.
     if (!flags.dryRun && runState.neon?.apiKeySecretPending && runState.github?.repo) {
         console.log('\n↻ Reintentando los secrets de E2E ahora que el repo existe...');
-        await provisionNeon(rootDir, runState);
-        writeProvisionState(rootDir, runState);
+        runCtx.neonProjectKey = await provisionNeon(rootDir, runState, {
+            neonOrg: flags.neonOrg,
+            remint: flags.remint,
+            persistState: !remintOverAdopted,
+        });
+        if (!remintOverAdopted)
+            writeProvisionState(rootDir, runState);
     }
     // 5a.2. Ensure the local E2E creds are in `.env.local` even on a resume/adopt where
     //       the Vercel substrate was already `done` (writeE2eLocalCreds only runs inside
     //       that step's first pass). Idempotent — `setEnvLine` replaces/appends the two
     //       keys — so `pnpm test:e2e` works locally without a manual edit after a re-run.
     if (!flags.dryRun && runState.neon?.projectId) {
-        if (writeE2eLocalCreds(rootDir, runState.neon.projectId, readNeonApiKey())) {
-            console.log('  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)');
+        const e2eKey = runCtx.neonProjectKey ?? null;
+        if (writeE2eLocalCreds(rootDir, runState.neon.projectId, e2eKey)) {
+            console.log(e2eKey
+                ? '  ＋ .env.local (NEON_API_KEY · NEON_PROJECT_ID — para `pnpm test:e2e` local)'
+                : '  ＋ .env.local (NEON_PROJECT_ID) · ⚠ sin NEON_API_KEY: no se acuñó una key en este run — ' +
+                    'corre `factory provision --services=neon --remint` para refrescarla');
         }
     }
     // Same for email config on resume/adopt (writeEmailLocalCreds only runs in the first

package/dist/index.js

@@ -94,6 +94,13 @@ Sobre \`provision\`:
     --slug=<slug>    Identificador del stack (nombre del proyecto + dominios interinos)
     --team=<id>      Team de Vercel (override; default = \`VERCEL_TEAM_ID\` del rail ~/.claude/.env)
     --org-id=<id>    Org de GitHub (override; default = org del Factory)
+    --neon-org=<x>   Organización de Neon donde CREAR el proyecto: nombre o id.
+                     Default = \`NEON_ORG\` del rail; si la key ve una sola org, esa.
+                     Varias orgs y sin selector → aborta (nunca adivina). Un proyecto
+                     que YA existe ignora este flag: su org se lee del proyecto
+    --remint         Reacuña la API key project-scoped de Neon aunque el paso esté
+                     completo (revoca la vigente, sube los 3 secrets de E2E y
+                     reescribe .env.local). Para una key revocada por fuera
     --domain=<dom>   Dominio definitivo del cliente (diferible; standalone o inicial)
     --dns=<ruta>     Ruta DNS para --domain: org (default) | cliente-cf | registrar
     --verify-timeout=<min>  Timeout del sondeo de verificación de Vercel (default 10)

package/dist/lib/env-file.js

@@ -36,8 +36,9 @@ export const PROVISION_OWNED = new Set([
     'MFA_ENCRYPTION_KEY',
     'WEBAUTHN_RP_ID',
     // LOCAL-ONLY E2E credentials (like DATABASE_URL_MAIN): the E2E runner reads them
-    // from `.env.local` to spin an isolated Neon branch per run. CI gets them as GitHub
-    // Secrets; they must NEVER reach Vercel (a day-2 push would leak the Neon key).
+    // from `.env.local` to spin an isolated Neon branch per run. Both local and CI hold
+    // the SAME project-scoped key (see `writeE2eLocalCreds`); they must NEVER reach
+    // Vercel (a day-2 push would leak it).
     'NEON_API_KEY',
     'NEON_PROJECT_ID',
     // LOCAL-ONLY backlog-central credentials (BSYNC-003): the derivative's `backlog
@@ -98,24 +99,37 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
 /**
  * Write the LOCAL E2E Neon credentials into `.env.local` so `pnpm test:e2e` runs on
  * the dev's machine without a manual `setup:e2e`. The E2E runner reads NEON_API_KEY +
- * NEON_PROJECT_ID from `.env.local` to spin an isolated branch per run. CI gets these
- * as GitHub Secrets (a project-scoped key); locally we reuse the dev's ORG key from
- * the rail (already on their host). Both stay LOCAL-ONLY (PROVISION_OWNED → never
- * pushed to Vercel). Returns false (no-op) when the key/project id is missing or
- * `.env.local` does not exist yet (`writeEnvLocal` creates it first). Safe on an
- * existing file: `setEnvLine` only touches these two keys, preserving the rest.
+ * NEON_PROJECT_ID from `.env.local` to spin an isolated branch per run.
+ *
+ * 🔴 `apiKey` is the PROJECT-SCOPED key provision just minted — the same value CI
+ * gets as a GitHub Secret — and never the rail key. This used to write the rail key
+ * ("locally we reuse the dev's ORG key, already on their host"), which is how a
+ * credential reaching every organization ended up in the `.env.local` of every
+ * derivative. A scoped key 404s on any other project, so it is the only value that
+ * belongs in a per-project file.
+ *
+ * `apiKey` of `null` means "no key was minted in this run" (a resume over an already
+ * complete Neon step, where the value is unrecoverable because it was never
+ * persisted). Then only `NEON_PROJECT_ID` is written — never a fallback to the rail —
+ * and the caller tells the dev the local key was not refreshed.
+ *
+ * Both keys stay LOCAL-ONLY (PROVISION_OWNED → never pushed to Vercel). Returns
+ * false (no-op) when the project id is missing or `.env.local` does not exist yet
+ * (`writeEnvLocal` creates it first). Safe on an existing file: `setEnvLine` only
+ * touches these two keys, preserving the rest.
  */
 export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
-    if (!apiKey || !projectId)
+    if (!projectId)
         return false;
     const localPath = join(rootDir, '.env.local');
     if (!existsSync(localPath))
         return false;
     let body = readFileSync(localPath, 'utf8');
     body = setEnvLine(body, 'NEON_PROJECT_ID', projectId);
-    body = setEnvLine(body, 'NEON_API_KEY', apiKey);
+    if (apiKey)
+        body = setEnvLine(body, 'NEON_API_KEY', apiKey);
     writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
-    chmodSync(localPath, 0o600); // holds NEON_API_KEY → owner-only.
+    chmodSync(localPath, 0o600); // may hold NEON_API_KEY → owner-only.
     return true;
 }
 /**

package/dist/lib/initial-migration.js

@@ -12,11 +12,17 @@
  * 🔴 THE SIGNAL FAILS TOWARD "DO NOT TOUCH". `.timekast/lockfile.json` is written by
  * `new`/`add`/`update` in every derivative and does NOT exist in the Factory, so its
  * ABSENCE means "this is the Factory, or a checkout that cannot be identified" and the
- * predicate answers `false`. A false positive INSIDE the Factory would commit a `0000`
- * here, and since the `full` distribution profile is `include: ["**"]` without excluding
- * `src/lib/db/migrations/`, that `.sql` would ride the tarball into every new derivative
- * — breaking BR-FACTORY-005 from the origin. A false negative only leaves the migration
- * ungenerated, which the dev fixes with one `pnpm db:generate`.
+ * predicate answers `false`. A false positive INSIDE the Factory would commit a SECOND
+ * `0000` on top of the one the Factory now maintains for itself — a duplicate against the
+ * same schema, which `drizzle-kit check` then reports as a broken journal. A false
+ * negative only leaves the migration ungenerated, which the dev fixes with one
+ * `pnpm db:generate`.
+ *
+ * ℹ️ This used to warn that a `0000` committed here would RIDE THE TARBALL into every new
+ * derivative, because `profiles.full` was `include: ["**"]` with no exclusion for
+ * `src/lib/db/migrations/`. That hole is closed: the exclusion now exists (and is pinned
+ * by a test over the REAL profiles.json), which is precisely what let the Factory adopt
+ * migrations without breaking the born-clean rule. A derivative still generates its own.
  *
  * If this signal ever disagrees with the markdown detection `/deploy` uses (`is_factory`
  * in `project/planning/project-config.md`), the ABSENCE OF THE LOCKFILE WINS and nothing

package/dist/lib/neon-api.js

@@ -95,6 +95,113 @@ async function safeBody(response) {
         return '';
     }
 }
+/**
+ * List the organizations the API key can reach — `GET /users/me/organizations`.
+ *
+ * This is the ONLY way to learn an org id from a key, and it is why the rail no
+ * longer carries `NEON_ORGANIZATION_ID`: the id is derived, never configured.
+ *
+ * Only a PERSONAL key answers here (an org key gets `404 not allowed for
+ * organization API keys`), which is exactly the shape the rail now holds: the
+ * personal key of a service account that is a member of the TimeKast orgs and
+ * of nothing else. A service account that belongs to ONE org therefore returns a
+ * single entry, and {@link resolveNeonOrg} needs no configuration at all.
+ *
+ * @throws {NeonApiError} on any non-2xx.
+ */
+export async function listNeonOrgs(apiKey, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/users/me/organizations`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /users/me/organizations');
+    }
+    const data = (await response.json());
+    return (data.organizations ?? [])
+        .filter((o) => Boolean(o.id))
+        .map((o) => ({ id: o.id, name: o.name ?? o.id, handle: o.handle ?? '' }));
+}
+/**
+ * Resolve WHICH organization a new project is created in. Three tiers, in order
+ * (the caller passes tiers 1 and 2; this function owns the fallback):
+ *
+ *   1. `--neon-org <name|id>` — the explicit ask, for the deliberate detour
+ *      (an overflow org once the default one fills up, a reserved one).
+ *   2. `NEON_ORG` from the rail — the durable default, a NAME not an id, set once.
+ *   3. Neither: a key that sees exactly ONE org uses it; a key that sees several
+ *      THROWS, naming them. Fail-closed on purpose — guessing here would create a
+ *      client's database in the wrong organization, and there is no prompt to fall
+ *      back on (headless Agent Server runs have nobody to answer it).
+ *
+ * `selector` matches the `org-...` id verbatim, or the name/handle
+ * case-insensitively, so both `--neon-org TimeKast` and `--neon-org org-abc123`
+ * work. An unknown selector throws rather than falling through to a default: the
+ * caller asked for a specific org and silently using another is the failure mode
+ * this whole resolution exists to prevent.
+ *
+ * @throws {CLIError-ready Error} with an es-MX message the caller surfaces as-is.
+ * @throws {NeonApiError} if the listing itself fails.
+ */
+export async function resolveNeonOrg(apiKey, selector, deps = {}) {
+    const orgs = await listNeonOrgs(apiKey, deps);
+    if (orgs.length === 0) {
+        throw new Error('La `NEON_API_KEY` del archivo de secretos no ve ninguna organización de Neon.\n' +
+            '  Debe ser la key PERSONAL de la cuenta de servicio, y esa cuenta tiene que ser ' +
+            'Admin de la organización (solo un Admin puede acuñar API keys project-scoped).');
+    }
+    if (selector) {
+        const needle = selector.trim().toLowerCase();
+        const hit = orgs.find((o) => o.id === selector.trim() ||
+            o.name.toLowerCase() === needle ||
+            o.handle.toLowerCase() === needle);
+        if (!hit) {
+            throw new Error(`La key no ve ninguna organización de Neon llamada \`${selector}\`.\n` +
+                `  Organizaciones visibles: ${orgs.map((o) => `${o.name} (${o.id})`).join(', ')}.`);
+        }
+        return hit;
+    }
+    if (orgs.length === 1)
+        return orgs[0];
+    throw new Error(`La key ve ${orgs.length} organizaciones de Neon y no dijiste en cuál crear el proyecto.\n` +
+        `  Visibles: ${orgs.map((o) => `${o.name} (${o.id})`).join(', ')}.\n` +
+        '  Elige una con `--neon-org "<nombre>"`, o fija el default del rail con ' +
+        '`NEON_ORG=<nombre>` en `~/.claude/.env`.');
+}
+/**
+ * The organization that owns a project, asked BY ID — `GET /projects/{id}`.
+ *
+ * 🔴 This is the right question whenever the project id is known, and the reason is a
+ * bug that shipped: the org used to be resolved by sweeping every org for a project
+ * whose NAME equals the repo's slug. Projects are named by humans in the console
+ * (`Aditivo CRM`, `agent-fimubac`), so that match usually fails — and when it fails the
+ * caller falls back to a configured default. In the org that happens to be the default
+ * it silently "works"; outside it, the mint 404s with `project not found`. Observed on
+ * both, the same afternoon. With an id in hand, asking by name is a detour.
+ *
+ * Returns `null` when the project does not exist or the key cannot see it — the caller
+ * then decides (a re-mint refuses; nothing is ever created on a guess).
+ *
+ * @throws {NeonApiError} on a non-2xx that is NOT 404 (auth, quota, network): those are
+ *   real failures and must not be read as "no such project".
+ */
+export async function getNeonProjectOrg(apiKey, projectId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}`, {
+        method: 'GET',
+        headers: neonHeaders(apiKey),
+        signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+    });
+    if (response.status === 404)
+        return null;
+    if (!response.ok) {
+        throw new NeonApiError(response.status, await safeBody(response), 'GET /projects/{id}');
+    }
+    const data = (await response.json());
+    return data.project?.org_id ?? null;
+}
 /**
  * Create a Neon project. The project is born WITH its primary branch — we name
  * that branch `main` and use it as production (issue §4: do NOT create an extra
@@ -187,6 +294,39 @@ export async function createDevelopBranch(apiKey, projectId, parentBranchId, dep
     }
     return branchId;
 }
+/**
+ * The database a branch actually holds, plus its owning role.
+ *
+ * 🔴 These were hardcoded to Neon's defaults for an API-provisioned project
+ * (`neondb` / `neondb_owner`), which is right for a project this CLI created and WRONG
+ * for every project it merely adopted. A real client project whose database is named
+ * `adi_capital` got a `DATABASE_URL` secret pointing at a `neondb` that does not exist
+ * there — CI would have run against a database nobody had. Asking the branch costs one
+ * GET and is right in both cases.
+ *
+ * Falls back to Neon's defaults when the branch reports no database (or the lookup
+ * fails), so a freshly-created project behaves exactly as before.
+ */
+export async function getBranchDatabase(apiKey, projectId, branchId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/databases`, {
+            method: 'GET',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+        const data = (await response.json());
+        const first = (data.databases ?? []).find((d) => d.name);
+        if (!first?.name)
+            return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+        return { database: first.name, role: first.owner_name ?? NEON_DEFAULT_ROLE };
+    }
+    catch {
+        return { database: NEON_DEFAULT_DATABASE, role: NEON_DEFAULT_ROLE };
+    }
+}
 /**
  * Read a branch's connection string for the requested mode via Neon's
  * `GET /projects/{id}/connection_uri`:
@@ -203,12 +343,15 @@ export async function createDevelopBranch(apiKey, projectId, parentBranchId, dep
  */
 export async function getConnectionUri(apiKey, projectId, branchId, pooled, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
-    // Neon's connection_uri requires database_name + role_name (the project's default
-    // db + owner role). Without them it 400s "database_name not set".
+    // Neon's connection_uri requires database_name + role_name. They come from the
+    // BRANCH (see `getBranchDatabase`), not from a constant: an adopted project's
+    // database is whatever its team named it, and assuming `neondb` there hands out a
+    // connection string to a database that does not exist.
+    const { database, role } = await getBranchDatabase(apiKey, projectId, branchId, deps);
     const query = new URLSearchParams({
         branch_id: branchId,
-        database_name: NEON_DEFAULT_DATABASE,
-        role_name: NEON_DEFAULT_ROLE,
+        database_name: database,
+        role_name: role,
         pooled: pooled ? 'true' : 'false',
     });
     const response = await fetchImpl(`${NEON_API_BASE}/projects/${encodeURIComponent(projectId)}/connection_uri?${query.toString()}`, {
@@ -300,20 +443,34 @@ export async function listNeonBranches(apiKey, projectId, deps = {}) {
     const data = (await response.json());
     return (data.branches ?? [])
         .filter((b) => Boolean(b.id) && Boolean(b.name))
-        .map((b) => ({ id: b.id, name: b.name }));
+        .map((b) => ({ id: b.id, name: b.name, isDefault: b.default === true }));
 }
 /**
- * Mint a PROJECT-SCOPED Neon API key (issue §4 + plan: the GH secret stores a
- * project-scoped key, NOT the org key — blast radius is one project's infra).
- * Neon's `POST /api_keys` with a `project_id` scopes the key to that project.
- * Returns the key value (the ONE place this value is read — it is handed
- * straight to `gh secret set` over STDIN, never logged).
+ * Mint a PROJECT-SCOPED Neon API key: `POST /organizations/{org_id}/api_keys`
+ * with a `project_id`. The result is an ORG-OWNED key restricted to that one
+ * project (Editor level), which is what the GH secret and the derivative's
+ * `.env.local` store — never the rail key. Returns the key value (the ONE place
+ * this value is read — handed straight to `gh secret set` over STDIN, never
+ * logged).
+ *
+ * 🔴 The endpoint matters, and getting it wrong was a real incident. This used to
+ * call `POST /api_keys` with the same `project_id` in the body. That endpoint
+ * takes `key_name` and NOTHING else, so Neon ignored the scope and handed back a
+ * PERSONAL key with access to every organization its owner belonged to — which
+ * provision then distributed to every repo's GitHub Secrets and `.env.local`.
+ * Verified 2026-09-12: the key this endpoint returns 404s on a sibling project in
+ * the same org and 404s on `DELETE /projects/{id}`, while still covering the whole
+ * E2E branch cycle (create branch, connection_uri, reveal_password, delete).
+ *
+ * Requires a PERSONAL key belonging to an ADMIN of the org: an org key gets
+ * `404 This endpoint requires a personal API key`, and there is no alternative
+ * route (`POST /projects/{id}/api_keys` does not exist).
  *
  * @throws {NeonApiError} on any non-2xx.
  */
-export async function createProjectApiKey(apiKey, projectId, keyName, deps = {}) {
+export async function createProjectApiKey(apiKey, orgId, projectId, keyName, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const mint = () => fetchImpl(`${NEON_API_BASE}/api_keys`, {
+    const mint = () => fetchImpl(`${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys`, {
         method: 'POST',
         headers: neonHeaders(apiKey),
         body: JSON.stringify({ key_name: keyName, project_id: projectId }),
@@ -326,33 +483,41 @@ export async function createProjectApiKey(apiKey, projectId, keyName, deps = {})
     // resume must converge, not 409. (Only the secret-pending path re-enters here;
     // the happy path sets apiKeySecretDone and short-circuits before minting again.)
     if (response.status === 409) {
-        await deleteNeonApiKeysByName(apiKey, keyName, { fetchImpl });
+        await deleteNeonApiKeysByName(apiKey, orgId, keyName, { fetchImpl });
         response = await mint();
     }
     if (!response.ok) {
-        throw new NeonApiError(response.status, await safeBody(response), 'POST /api_keys');
+        throw new NeonApiError(response.status, await safeBody(response), 'POST /organizations/{org_id}/api_keys');
     }
     const data = (await response.json());
     if (!data.key) {
-        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /api_keys (respuesta sin key)');
+        throw new NeonApiError(response.status, JSON.stringify(data).slice(0, 500), 'POST /organizations/{org_id}/api_keys (respuesta sin key)');
     }
     return data.key;
 }
 /**
- * Best-effort delete of every account/org API key whose name matches `keyName`
- * (GET /api_keys → DELETE /api_keys/{id}). Two callers:
- *   - the idempotent re-mint (clear a stale key before re-minting on resume), and
+ * Best-effort delete of every ORG API key whose name matches `keyName`
+ * (`GET /organizations/{org_id}/api_keys` → `DELETE .../api_keys/{id}`). Three
+ * callers:
+ *   - the idempotent re-mint (clear a stale key before re-minting on resume),
+ *   - `--remint` (revoke the live key before issuing its replacement), and
  *   - the ephemeral `--destroy` nuke (delete the project-scoped key it minted so
  *     the org does not accumulate dead keys across provisions/tests).
+ *
+ * Org-scoped for the same reason the mint is (see {@link createProjectApiKey}):
+ * the keys provision issues are owned by the org, so the personal `/api_keys`
+ * listing never saw them — and with a service-account key it 404s outright.
+ *
  * Returns the count deleted. NEVER throws — a cleanup failure must not abort the
  * caller (the re-mint surfaces its own error; the destroy already nuked the
  * project).
  */
-export async function deleteNeonApiKeysByName(apiKey, keyName, deps = {}) {
+export async function deleteNeonApiKeysByName(apiKey, orgId, keyName, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
+    const keysBase = `${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys`;
     let deleted = 0;
     try {
-        const listResp = await fetchImpl(`${NEON_API_BASE}/api_keys`, {
+        const listResp = await fetchImpl(keysBase, {
             method: 'GET',
             headers: neonHeaders(apiKey),
             signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
@@ -366,7 +531,7 @@ export async function deleteNeonApiKeysByName(apiKey, keyName, deps = {}) {
             .filter((k) => k?.name === keyName && k?.id != null)
             .map((k) => String(k.id));
         for (const id of ids) {
-            const del = await fetchImpl(`${NEON_API_BASE}/api_keys/${encodeURIComponent(id)}`, {
+            const del = await fetchImpl(`${keysBase}/${encodeURIComponent(id)}`, {
                 method: 'DELETE',
                 headers: neonHeaders(apiKey),
                 signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),

package/dist/lib/preflight.js

@@ -139,6 +139,11 @@ export async function runPreflight() {
  * The methodology-rail keys the launcher expects in `~/.claude/.env` (imported
  * via `factory secrets <file>`). Provisioning tokens + their team/org ids + the
  * proposal tooling keys. Single source so the check + tests agree.
+ *
+ * `NEON_ORG` is deliberately NOT here: it only names a default organization, and
+ * its absence is a valid configuration (a key that reaches exactly one org needs
+ * no default). Listing it would warn every dev about a key they may never need.
+ * The Neon ORG ID is not here either — it is derived from the key, never stored.
  */
 export const REQUIRED_SECRET_KEYS = [
     'NEON_API_KEY',
@@ -148,7 +153,6 @@ export const REQUIRED_SECRET_KEYS = [
     'SHORTIO_API_KEY',
     'GAMMA_API_KEY',
     'VERCEL_TEAM_ID',
-    'NEON_ORGANIZATION_ID',
 ];
 /** The ordered launcher labels (single source so render + tests agree). */
 const LAUNCHER_LABELS = {

package/dist/lib/provision-preflight.js

@@ -19,8 +19,10 @@
  *
  * What is OPTIONAL (a WARNING, never an abort — frozen plan decision):
  *   - `neonctl`. Provision mutates Neon over REST with the rail `NEON_API_KEY`,
- *     so a missing or un-authenticated `neonctl` is a convenience gap, not a
+ *     so a missing or session-less `neonctl` is a convenience gap, not a
  *     blocker (issue §1, §8). Absent → warn with the install hint and continue.
+ *     The session is detected by its credentials FILE, never by running
+ *     `neonctl me` — that command starts a login instead of failing.
  *
  * The token reader, the `fetch`, and the `gh` spawns are all injectable seams so
  * the unit tests drive every branch (401/403/missing-token/no-gh/no-neonctl)
@@ -183,6 +185,14 @@ function assertGateTokensPresent(services, present) {
             'Ejecuta `factory secrets <archivo>` para bajarlos del archivo de secretos del org y vuelve a intentar.');
     }
 }
+/**
+ * Where `neonctl` keeps its OAuth session. Honors `NEONCTL_CONFIG_DIR`, which the CLI
+ * itself reads, so a dev who moved its config is not reported as session-less.
+ */
+export function neonctlCredentialsPath() {
+    const base = process.env.NEONCTL_CONFIG_DIR ?? path.join(homedir(), '.config', 'neonctl');
+    return path.join(base, 'credentials.json');
+}
 /**
  * Optional `neonctl` check — NEVER aborts (frozen plan decision: provision mutates
  * Neon over REST with the rail `NEON_API_KEY`). Returns a structured report the
@@ -208,19 +218,29 @@ async function checkNeonctlOptional(spawn) {
             message: 'No se pudo ejecutar `neonctl` (opcional). Continúo con la mutación por REST.',
         };
     }
-    // Installed → check it is authenticated (`neonctl me`). Un-authed is still only
-    // a warning: provision does not depend on the neonctl session.
-    try {
-        await spawn('neonctl', ['me']);
-    }
-    catch {
+    // Installed → is there a session? Answered by looking for the credentials file,
+    // NOT by running `neonctl me`.
+    //
+    // 🔴 `neonctl me` without a session does not fail — it STARTS A LOGIN and opens a
+    // browser. A check the plan froze as optional diagnostics ("provision does not
+    // depend on the neonctl session") therefore had two side effects it had no business
+    // having: it popped an OAuth consent in the dev's browser mid-provision, and, if
+    // approved, wrote an OAuth session to their host. Worse where nobody can see it: on
+    // a headless Agent Server there is no browser and no one to approve, so the spawn
+    // sits waiting and hangs the preflight of a run that never needed it.
+    //
+    // Reading the credentials file is the same answer with no side effects. It can go
+    // stale (an expired session still leaves the file), which is why the `ok` message
+    // says "con sesión" and not "authenticated" — and being wrong in that direction
+    // costs a wrong word in a warning, while the old one cost a credential.
+    if (!existsSync(neonctlCredentialsPath())) {
         return {
             status: 'warn',
-            message: '`neonctl` está instalado pero no autenticado (opcional).\n' +
+            message: '`neonctl` está instalado pero sin sesión (opcional).\n' +
                 'Autentícalo con `neonctl auth` si lo quieres para inspección; provision no lo necesita.',
         };
     }
-    return { status: 'ok', message: '`neonctl` instalado y autenticado.' };
+    return { status: 'ok', message: '`neonctl` instalado y con sesión.' };
 }
 /**
  * Step 3 — `VERCEL_TOKEN` is valid and scoped to `teamId` via `GET /v2/teams/{teamId}`.

package/dist/lib/provision-state.js

@@ -199,6 +199,7 @@ export function adoptState(rootDir, partial, options = {}) {
         slug,
         vercelProjectId: partial.vercelProjectId ?? ADOPT_UNKNOWN,
         neonProjectId: partial.neonProjectId ?? ADOPT_UNKNOWN,
+        neonOrgId: partial.neonOrgId ?? ADOPT_UNKNOWN,
         neonBranchDevId: partial.neonBranchDevId ?? ADOPT_UNKNOWN,
         githubRepo: partial.githubRepo ?? ADOPT_UNKNOWN,
         domains: partial.domains ?? { dev: ADOPT_UNKNOWN, prod: ADOPT_UNKNOWN },
@@ -305,6 +306,47 @@ function isAdoptedShape(obj) {
     // `projectName` + nested `vercel.projectId`. `slug` present = adopt.
     return typeof obj.slug === 'string';
 }
+/**
+ * Read the state as a {@link ProvisionState} for a `--remint`, tolerating BOTH shapes
+ * the way {@link readDestroyTarget} does.
+ *
+ * 🔴 Why this exists: the ADOPTED shape is what the whole existing fleet has — a
+ * derivative provisioned before this state file existed gets one from `--adopt`, and
+ * that shape has `slug`/`neonProjectId` instead of `projectName`/`neon`. So
+ * `readProvisionState` rejects it, and `--remint` (the command whose entire purpose is
+ * re-issuing the key of an already-provisioned project) failed on precisely the
+ * projects that need it, suggesting `--force` — which with `--services=neon` would
+ * discard the state and try to CREATE A SECOND Neon project for a derivative that
+ * already has one.
+ *
+ * Returns `null` when there is no state at all, and throws the same typed error as
+ * `readDestroyTarget` on a corrupt file. `mainBranchId` comes back empty for an
+ * adopted stack (that shape never recorded it), and so does `developBranchId` when the
+ * adopt found no branch by that name — the normal case for a project whose working
+ * branch is called something else (the Factory's is `production`). A re-mint resolves
+ * the branch it needs from Neon, honoring the repo's pinned E2E parent, and never
+ * creates one.
+ */
+export function readRemintState(rootDir) {
+    const target = readDestroyTarget(rootDir);
+    if (!target)
+        return null;
+    if (!target.neonProjectId)
+        return null;
+    return {
+        projectName: target.slug,
+        lifecycle: target.lifecycle,
+        scope: target.scope ?? '',
+        neon: {
+            projectId: target.neonProjectId,
+            orgId: target.neonOrgId ?? undefined,
+            mainBranchId: '',
+            developBranchId: target.neonBranchDevId ?? '',
+        },
+        github: target.githubRepo ? { repo: target.githubRepo } : undefined,
+        createdAt: new Date(0).toISOString(),
+    };
+}
 /**
  * Read the provision state file as a {@link DestroyTarget}, tolerating BOTH the
  * step-by-step {@link ProvisionState} and the flat {@link AdoptedState} shapes
@@ -351,6 +393,7 @@ export function readDestroyTarget(rootDir) {
             lifecycle: adopted.lifecycle === 'live' ? 'live' : 'live', // adopt is always live
             scope: null, // the adopt shape does not persist the team scope
             neonProjectId: realId(adopted.neonProjectId),
+            neonOrgId: realId(adopted.neonOrgId),
             neonBranchDevId: realId(adopted.neonBranchDevId),
             vercelProjectId: realId(adopted.vercelProjectId),
             githubRepo: realRepo(adopted.githubRepo),
@@ -388,6 +431,7 @@ export function readDestroyTarget(rootDir) {
         lifecycle,
         scope: realId(step.scope),
         neonProjectId: realId(step.neon?.projectId),
+        neonOrgId: realId(step.neon?.orgId),
         neonBranchDevId: realId(step.neon?.developBranchId),
         vercelProjectId: realId(step.vercel?.projectId),
         githubRepo: realRepo(step.github?.repo),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.27.0",
+  "version": "1.28.1",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",