@timekast/factory 1.28.1 → 2.0.0

package/dist/lib/preflight.js

@@ -15,12 +15,11 @@
  * --launcher` can render every step with ✅ / ❌ across all platforms (the
  * cross-platform equivalent of the macOS launcher's `checkPrereqs`).
  */
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import path from 'node:path';
 import { execa } from 'execa';
 import { PreflightError } from './cli-error.js';
 import { FACTORY_ORG } from './constants.js';
+import { RailError, createRailResolver } from './rail.js';
+import { VAULT_CONFIG } from './vault-config.js';
 /** Minimum Node major version the kit requires (mirrors `engines.node` + the launcher AppleScript). */
 export const MIN_NODE_MAJOR = 22;
 /** Timeout (ms) for the GitHub API calls in the org-membership check — a slow / dead network must not hang. */
@@ -136,9 +135,10 @@ export async function runPreflight() {
     await assertOrgMembership();
 }
 /**
- * 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.
+ * The methodology-rail keys the launcher expects in the vault rail (`rail-timekast`,
+ * read with the person's session — `fx-secrets-vault §3`). 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
@@ -153,14 +153,26 @@ export const REQUIRED_SECRET_KEYS = [
     'SHORTIO_API_KEY',
     'GAMMA_API_KEY',
     'VERCEL_TEAM_ID',
+    // RWAY-003: `provision` asks Railway for the connected repo to discover a repo's destination
+    // (and to refuse a `--target=vercel` over a repo that lives in Railway) — in Vercel repos too.
+    'RAILWAY_TOKEN',
 ];
+/**
+ * Time budget (ms) of the launcher's vault read. Deliberately SHORTER than the
+ * resolver's default (`RAIL_READ_TIMEOUT_MS`, 30 s): the desktop launcher waits 30 s
+ * IN TOTAL for the whole `doctor --launcher --json` document
+ * (`desktop/renderer/panels/home.tsx`), and `npx @latest` already eats part of that.
+ * A vault that does not answer must end as a `warn` "could not be determined" inside
+ * the document — not as a launcher-side "connection error" because the JSON never came.
+ */
+export const LAUNCHER_RAIL_TIMEOUT_MS = 10_000;
 /** The ordered launcher labels (single source so render + tests agree). */
 const LAUNCHER_LABELS = {
     node: `Node ≥ ${MIN_NODE_MAJOR}`,
     gh: 'GitHub CLI (gh) instalado',
     auth: 'Sesión de GitHub activa',
     org: `Membresía del org ${FACTORY_ORG}`,
-    secrets: 'Secrets del org en el rail',
+    secrets: `Secrets del org en la bóveda (${VAULT_CONFIG.rail.name})`,
 };
 /** A confirmation message for a passing check (the `ok` branch). */
 const OK_MESSAGES = {
@@ -168,43 +180,81 @@ const OK_MESSAGES = {
     gh: 'GitHub CLI (gh) está instalado.',
     auth: 'Tu sesión de GitHub CLI está activa.',
     org: `Eres miembro del org ${FACTORY_ORG}.`,
-    secrets: `Las ${REQUIRED_SECRET_KEYS.length} keys del rail están presentes.`,
+    secrets: `Las ${REQUIRED_SECRET_KEYS.length} claves requeridas están en ` +
+        `\`${VAULT_CONFIG.rail.name}\` y tu sesión de la bóveda está activa.`,
 };
+/** The vault state skeleton — coordinates always present, everything else undetermined. */
+function vaultState(overrides) {
+    return {
+        domain: VAULT_CONFIG.domain,
+        project: VAULT_CONFIG.rail.name,
+        session: null,
+        access: null,
+        missingKeys: null,
+        unknownReason: null,
+        ...overrides,
+    };
+}
+/** Map a rail failure (other than a missing key) to the published vault state. */
+function vaultStateForFailure(kind) {
+    switch (kind) {
+        case 'no-session':
+            return vaultState({ session: false });
+        case 'no-access':
+            return vaultState({ session: true, access: false });
+        case 'not-installed':
+        case 'timeout':
+        case 'unrecognized':
+            return vaultState({ unknownReason: kind });
+        case 'key-missing':
+            // Never reaches here (`getOptional` turns it into `null`), kept for exhaustiveness.
+            return vaultState({ session: true, access: true });
+    }
+}
 /**
- * Read the secret KEY NAMES present in the rail (`~/.claude/.env`), never values.
- * A missing/unreadable rail yields an empty set (→ the check warns with all keys
- * missing). Tests inject `railContent` to avoid touching the real home dir.
+ * Build the secrets check against the vault rail: session → access → presence of
+ * each {@link REQUIRED_SECRET_KEYS}, in that order (the resolver reads the rail
+ * project ONCE; a session/access failure surfaces on the first key). NAMES ONLY —
+ * each value is dropped the moment the resolver hands it over.
+ *
+ * Never `fail`, never throws: every outcome is `ok` or `warn`. The message on a
+ * failure is the resolver's own (built from the classification, never from what
+ * the vault printed), so it names the login command with the domain, the rail
+ * project, or how to install `infisical`.
  */
-function readRailKeyNames(railContent) {
-    let content = railContent;
-    if (content === undefined) {
-        try {
-            content = readFileSync(path.join(homedir(), '.claude', '.env'), 'utf8');
-        }
-        catch {
-            content = '';
+async function secretsCheck(rail) {
+    const base = { id: 'secrets', label: LAUNCHER_LABELS.secrets };
+    const missing = [];
+    try {
+        for (const key of REQUIRED_SECRET_KEYS) {
+            // Presence only: the value is compared to null and discarded right here.
+            if ((await rail.getOptional(key)) === null)
+                missing.push(key);
         }
     }
-    const names = new Set();
-    for (const line of content.split(/\r?\n/)) {
-        const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
-        if (match)
-            names.add(match[1]);
+    catch (error) {
+        const kind = error instanceof RailError ? error.kind : 'unrecognized';
+        return {
+            ...base,
+            status: 'warn',
+            // A non-RailError is not ours to echo (its text could carry anything).
+            message: error instanceof RailError
+                ? error.message
+                : 'No se pudo determinar el estado de la bóveda (error interno al leerla).',
+            vault: vaultStateForFailure(kind),
+        };
+    }
+    const vault = vaultState({ session: true, access: true, missingKeys: missing });
+    if (missing.length === 0) {
+        return { ...base, status: 'ok', message: OK_MESSAGES.secrets, vault };
     }
-    return names;
-}
-/** Build the secrets check (`ok` if all required keys present, else `warn`). */
-function secretsCheck(railContent) {
-    const present = readRailKeyNames(railContent);
-    const missing = REQUIRED_SECRET_KEYS.filter((key) => !present.has(key));
     return {
-        id: 'secrets',
-        label: LAUNCHER_LABELS.secrets,
-        status: missing.length === 0 ? 'ok' : 'warn',
-        message: missing.length === 0
-            ? OK_MESSAGES.secrets
-            : `Faltan ${missing.length} de ${REQUIRED_SECRET_KEYS.length} secrets en el rail: ` +
-                `${missing.join(', ')}. Impórtalos desde el card Secrets.`,
+        ...base,
+        status: 'warn',
+        message: `Faltan ${missing.length} de ${REQUIRED_SECRET_KEYS.length} claves en ` +
+            `\`${VAULT_CONFIG.rail.name}\`: ${missing.join(', ')}.\n` +
+            'Pide a un admin de la bóveda que las cargue.',
+        vault,
     };
 }
 /**
@@ -222,6 +272,10 @@ function secretsCheck(railContent) {
  * depends on the previous — no auth without gh, no org without auth) but still
  * RETURNS a full ordered report, marking the checks after the failure as
  * `skipped`. The caller decides exit code (0 = all ok, 1 = any fail).
+ *
+ * Then, always and independently of 1-4, the `secrets` check (5): session → access
+ * → key presence in the vault rail. It is `ok` or `warn`, never `fail`, so it never
+ * trips the exit code.
  */
 export async function runLauncherPreflight(deps = {}) {
     const ghInstalled = deps.ghInstalled ?? assertGhInstalled;
@@ -274,6 +328,6 @@ export async function runLauncherPreflight(deps = {}) {
     }
     // Secrets check — independent of the gh/auth/org chain (runs even if those
     // failed) and non-blocking: resolves to `ok` or `warn`, never `fail`/`skipped`.
-    results.push(secretsCheck(deps.railContent));
+    results.push(await secretsCheck(deps.rail ?? createRailResolver({ timeoutMs: LAUNCHER_RAIL_TIMEOUT_MS })));
     return results;
 }

package/dist/lib/provision-preflight.js

@@ -3,19 +3,23 @@
  *
  * A DEDICATED preflight, independent of `lib/preflight.ts` (whose scope is the
  * `new`/`add`/`update` org-membership gate). Provision mutates external infra
- * (Neon, Vercel, DNS) with the shared org tokens imported into the rail
- * (`factory secrets <archivo>`, SEC-001), so it must fail CLOSED if any credential
- * it will use is missing or invalid — BEFORE a single resource is created.
+ * (Neon, Vercel, DNS) with the org tokens of the rail — read from the vault
+ * (`rail-timekast`) with the person's session through the single resolver
+ * (`rail.ts`, ADR-006) — so it must fail CLOSED if any credential it will use is
+ * missing or invalid — BEFORE a single resource is created.
  *
- * What is FAIL-CLOSED (aborts with `PreflightError`):
+ * What is FAIL-CLOSED (aborts with `PreflightError` / a typed `RailError`):
  *   1. `gh` installed + a valid `gh auth status` session (the git substrate of
- *      PROV-004 needs it; and it is the org identity that gates the secrets import).
- *   2. The rail tokens for the requested services are PRESENT in `~/.claude/.env`
- *      (`VERCEL_TOKEN`, `NEON_API_KEY`, …). Absent → re-run `factory secrets <archivo>`.
+ *      PROV-004 needs it).
+ *   2. The rail tokens for the requested services are PRESENT in the vault
+ *      (`VERCEL_TOKEN`, `NEON_API_KEY`, …). Absent → a vault admin loads them. No
+ *      session / no access / an unrecognized answer is the resolver's own error —
+ *      never read as "absent".
  *   3. `VERCEL_TOKEN` is valid AND team-scoped: `GET /v2/teams/{teamId}` (NOT
  *      `/v2/user` — a personal token passes `/v2/user` yet 403s on the team).
  *      401 = invalid token; 403 = valid token without team access — distinct
- *      messages so the dev knows whether to re-import or check team membership.
+ *      messages so the dev knows whether to check the session / ask for a rotation
+ *      or check team membership.
  *
  * What is OPTIONAL (a WARNING, never an abort — frozen plan decision):
  *   - `neonctl`. Provision mutates Neon over REST with the rail `NEON_API_KEY`,
@@ -24,28 +28,39 @@
  *     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 rail resolver, 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)
- * without touching the real `~/.claude/.env`, the real `gh`, or the network.
+ * without touching the real vault, the real `gh`, or the network.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { execa } from 'execa';
 import { PreflightError } from './cli-error.js';
+import { WITH_VAULT_SCRIPT_FILE } from './constants.js';
+import { hasLockfile, readLockfile } from './lockfile.js';
+import { loginCommand, RAIL_ENV, RAIL_TIMEKAST, readOptionalRailSecret, readRailSecret, } from './rail.js';
+import { RAILWAY_TOKEN_KEY } from './railway-api.js';
 /** Timeout (ms) for the Vercel team-check fetch — a dead network must not hang. */
 const VERCEL_API_TIMEOUT_MS = 10_000;
 /** Base URL of the Vercel REST API (named constant — never an inline literal). */
 export const VERCEL_API_BASE = 'https://api.vercel.com';
-/** The gate token each provision service needs present in `~/.claude/.env`. */
+/** The gate token each provision service needs present in the vault rail. */
 const SERVICE_TOKENS = {
+    // `vault` (VAULT-002) reads no rail token: it talks to the vault with the person's own
+    // session, which the vault client obtains (and names `infisical login` when it is missing).
+    vault: null,
     neon: 'NEON_API_KEY',
     vercel: 'VERCEL_TOKEN',
     // `github` (PROV-004) uses the dev's `gh` session for the substrate AND the
     // gate `VERCEL_TOKEN` to create the Vercel project; `dns` rides the Cloudflare
     // token but only when a `--domain` is requested (PROV-005), so it is not gated
     // at the scaffold stage.
+    // RWAY-003: ONLY with destination Vercel — see `gateTokenFor`: with destination Railway the
+    // `github` step creates no Vercel project and never reads `VERCEL_TOKEN`.
     github: 'VERCEL_TOKEN',
+    // RWAY-003 — the Railway step (RWAY-004) talks to Railway with the team token of the rail.
+    railway: RAILWAY_TOKEN_KEY,
     dns: 'CLOUDFLARE_API_TOKEN',
     // `backlog` (BSYNC-003) registers the project in backlog.timekast.mx with the org
     // `admin` token. NOTE: unlike the other gate tokens (fail-closed here), a missing
@@ -56,46 +71,54 @@ const SERVICE_TOKENS = {
     // entry is the defense-in-depth double-check.
     backlog: 'BACKLOG_ADMIN_TOKEN',
 };
+/**
+ * The gate token of `service` for this run's destination (RWAY-003). The Vercel coupling of the
+ * `github` step exists only with destination Vercel: with Railway, `github` needs no
+ * `VERCEL_TOKEN`. An unresolved destination keeps today's (Vercel) behavior.
+ */
+function gateTokenFor(service, target) {
+    if (service === 'github' && target === 'railway')
+        return null;
+    return SERVICE_TOKENS[service];
+}
 /** True when the thrown error is execa's "command not found" (ENOENT). */
 function isCommandNotFound(error) {
     return error?.code === 'ENOENT';
 }
-/** Absolute path to the per-user secrets rail (`~/.claude/.env`). */
-export function defaultEnvPath() {
-    return path.join(homedir(), '.claude', '.env');
+/**
+ * The process-wide rail resolver (`rail.ts`): one vault read per rail project per
+ * process, shared by every step of a run. The default of every `rail` seam in
+ * `provision` / `env push`; tests inject `createRailResolver({ runner })` instead.
+ */
+export function defaultRail() {
+    return { get: readRailSecret, getOptional: readOptionalRailSecret };
 }
 /**
- * Read the SET of KEY NAMES present in a `KEY=value` rail file — NAMES ONLY, the
- * value of every line is discarded immediately so a secret never leaves this
- * function (no-echo discipline, mirrors `secrets.ts`). Split on the FIRST `=`;
- * comment / blank / no-`=` lines are skipped. A missing file → empty set.
- *
- * `envPath` is injectable so tests point at a temp file (or a non-existent path).
+ * Which of `keys` are PRESENT in the vault rail — NAMES ONLY. Each value is dropped
+ * the moment it is read, so no secret leaves this function (no-echo). Only a missing
+ * key counts as absent: no session, no access, a timeout or an unrecognized answer
+ * propagate as the resolver's typed error — a required token is never skipped
+ * because the vault could not be read.
  */
-export function readEnvKeyNames(envPath = defaultEnvPath()) {
-    if (!existsSync(envPath))
-        return new Set();
-    let text;
-    try {
-        text = readFileSync(envPath, 'utf8');
-    }
-    catch {
-        return new Set(); // unreadable → treat as "no keys" (preflight will report missing)
-    }
+export async function readEnvKeyNames(keys, rail = defaultRail()) {
     const names = new Set();
-    for (const line of text.split('\n')) {
-        const trimmed = line.trimStart();
-        if (trimmed === '' || trimmed.startsWith('#'))
-            continue;
-        const eq = line.indexOf('=');
-        if (eq === -1)
-            continue;
-        const key = line.slice(0, eq).trim();
-        if (key !== '')
+    for (const key of keys) {
+        if ((await rail.getOptional(key)) !== null)
             names.add(key);
     }
     return names;
 }
+/**
+ * The action for a rail token a provider REJECTED (401): first the vault session —
+ * it expires, and a dead session is not a dead token — and only if it is alive, a
+ * vault admin rotates the token in `rail-timekast` under the SAME name
+ * (`fx-secrets-vault §9`). Nobody re-imports anything: there is no local copy.
+ */
+export function railTokenRejectedHint(key) {
+    return (`Comprueba primero tu sesión de la bóveda (\`${loginCommand()}\`); si está viva, avisa a un ` +
+        `admin de la bóveda para que rote \`${key}\` en \`${RAIL_TIMEKAST.name}\` ` +
+        '(el valor nuevo entra con el mismo nombre).');
+}
 /** Step 1a — `gh` is installed on PATH. */
 async function assertGhInstalled(spawn) {
     try {
@@ -165,24 +188,25 @@ async function assertRepoExists(repoSlug, spawn) {
     }
 }
 /**
- * Step 2 — the rail tokens for the requested services are present.
+ * Step 2 — the rail tokens for the requested services are present in the vault.
  *
- * Maps each requested service to its required token (`SERVICE_TOKENS`) and
- * asserts every one is a key in `~/.claude/.env`. A missing token → fail-closed:
- * the dev must re-run `factory secrets <archivo>` (SEC-001) to import them. Services
- * with no required token (e.g. `github`) are skipped.
+ * Maps each requested service to its required token (`SERVICE_TOKENS`) and asserts
+ * every one is a key of `rail-timekast`. A missing token → fail-closed, naming ALL
+ * the missing ones at once (a vault admin loads them). A vault that cannot be read
+ * (no session, no access, …) is the resolver's error, not a "missing token".
  */
-function assertGateTokensPresent(services, present) {
+async function assertGateTokensPresent(services, rail, target) {
     const required = new Set();
     for (const service of services) {
-        const token = SERVICE_TOKENS[service];
+        const token = gateTokenFor(service, target);
         if (token)
             required.add(token);
     }
+    const present = await readEnvKeyNames([...required], rail);
     const missing = [...required].filter((token) => !present.has(token));
     if (missing.length > 0) {
-        throw new PreflightError(`Faltan tokens del archivo de secretos en \`~/.claude/.env\`: ${missing.join(', ')}.\n` +
-            'Ejecuta `factory secrets <archivo>` para bajarlos del archivo de secretos del org y vuelve a intentar.');
+        throw new PreflightError(`Faltan tokens en \`${RAIL_TIMEKAST.name}\` (bóveda, entorno ${RAIL_ENV}): ${missing.join(', ')}.\n` +
+            'Pide a un admin de la bóveda que los cargue y vuelve a intentar.');
     }
 }
 /**
@@ -209,7 +233,7 @@ async function checkNeonctlOptional(spawn) {
         if (isCommandNotFound(error)) {
             return {
                 status: 'warn',
-                message: '`neonctl` no está instalado (opcional — provision muta Neon por REST con el `NEON_API_KEY` del archivo de secretos).\n' +
+                message: '`neonctl` no está instalado (opcional — provision muta Neon por REST con el `NEON_API_KEY` del rail).\n' +
                     'Si lo quieres para inspección manual: `npm i -g neonctl`.',
             };
         }
@@ -226,7 +250,7 @@ async function checkNeonctlOptional(spawn) {
     // 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
+    // a headless run 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
@@ -246,7 +270,8 @@ async function checkNeonctlOptional(spawn) {
  * Step 3 — `VERCEL_TOKEN` is valid and scoped to `teamId` via `GET /v2/teams/{teamId}`.
  *
  * Distinguishes the two failure modes the issue calls out (§8):
- *   - 401 → the token itself is invalid/expired → re-pull
+ *   - 401 → the token itself is invalid/expired → check the vault session, then
+ *           ask a vault admin to rotate it
  *   - 403 → a valid token WITHOUT access to this team (e.g. a personal-scoped
  *           token) → check the team id / membership
  *
@@ -271,7 +296,7 @@ async function assertVercelTeamAccess(token, teamId, fetchImpl) {
         return; // 2xx → token válido y con acceso al team.
     if (response.status === 401) {
         throw new PreflightError('El `VERCEL_TOKEN` es inválido o expiró (Vercel respondió 401).\n' +
-            'Vuelve a bajar los tokens del archivo de secretos con `factory secrets <archivo>` y reintenta.');
+            railTokenRejectedHint('VERCEL_TOKEN'));
     }
     if (response.status === 403) {
         throw new PreflightError(`El \`VERCEL_TOKEN\` no tiene acceso al team \`${teamId}\` (Vercel respondió 403).\n` +
@@ -291,7 +316,12 @@ async function assertVercelTeamAccess(token, teamId, fetchImpl) {
 export async function runProvisionPreflight(input, deps = {}) {
     const spawn = deps.spawn ?? execa;
     const fetchImpl = deps.fetchImpl ?? fetch;
-    const envPath = deps.envPath ?? defaultEnvPath();
+    const rail = deps.rail ?? defaultRail();
+    // 0. VAULT-004 — the brain carries what the vault needs locally. Local reads only, so it runs
+    //    first: a repo that cannot use the vault stops before any network call and before the
+    //    vault step creates the project.
+    if (input.rootDir && input.services.includes('vault'))
+        assertVaultBrainPresent(input.rootDir);
     // 1. gh installed + authenticated.
     await assertGhInstalled(spawn);
     await assertGhAuthenticated(spawn);
@@ -304,25 +334,21 @@ export async function runProvisionPreflight(input, deps = {}) {
         if (input.repoSlug)
             await assertRepoExists(input.repoSlug, spawn);
     }
-    // 2. Gate tokens for the requested services present in the rail.
-    const present = readEnvKeyNames(envPath);
-    assertGateTokensPresent(input.services, present);
+    // 2. Gate tokens for the requested services present in the vault rail.
+    await assertGateTokensPresent(input.services, rail, input.target);
     // 3. Vercel team-scoped token check — when provisioning Vercel (env sync), GitHub
     //    (PROV-004 creates the team-scoped Vercel project), OR DNS (PROV-005 attaches
-    //    the interim domains to the team-scoped project).
-    if (input.services.includes('vercel') ||
-        input.services.includes('github') ||
-        input.services.includes('dns')) {
+    //    the interim domains to the team-scoped project). RWAY-003: only with destination
+    //    Vercel — a Railway run never asks for the team nor reads `VERCEL_TOKEN`.
+    if (input.target !== 'railway' &&
+        (input.services.includes('vercel') ||
+            input.services.includes('github') ||
+            input.services.includes('dns'))) {
         if (!input.teamId) {
             throw new PreflightError('Falta `--team=<teamId>`: el provision de Vercel/GitHub/DNS requiere el team del org.\n' +
                 'Pásalo como `factory provision --services=github,vercel,dns --team=team_xxx`.');
         }
-        const token = readVercelToken(envPath);
-        if (!token) {
-            // Defensive: step 2 already asserted presence, but guard the read path.
-            throw new PreflightError('No se pudo leer `VERCEL_TOKEN` de `~/.claude/.env`.\n' +
-                'Ejecuta `factory secrets <archivo>` y vuelve a intentar.');
-        }
+        const token = await readVercelToken(rail);
         await assertVercelTeamAccess(token, input.teamId, fetchImpl);
     }
     // 4. Optional neonctl — never fatal; surfaced as a warning by the caller.
@@ -330,41 +356,73 @@ export async function runProvisionPreflight(input, deps = {}) {
     return { neonctl };
 }
 /**
- * Read the VALUE of `VERCEL_TOKEN` from the rail (the team-check needs the value,
- * not just the name). Split on the FIRST `=`; strip a single matched pair of
- * surrounding quotes (the rail may store quoted values — `env-merge.ts`
- * preserves them). Returns `null` when absent/unreadable.
+ * Read the VALUE of `VERCEL_TOKEN` from the vault rail (the team-check and every
+ * Vercel call need the value, not just the name). A missing key is the resolver's
+ * `key-missing` error (it names the key); no session / no access propagate as-is.
  *
- * This is the ONE place a token VALUE is read; it is handed straight to the
- * Authorization header and never logged.
+ * The value is handed straight to an Authorization header and never logged.
  */
-export function readVercelToken(envPath = defaultEnvPath()) {
-    if (!existsSync(envPath))
-        return null;
-    let text;
-    try {
-        text = readFileSync(envPath, 'utf8');
-    }
-    catch {
-        return null;
-    }
-    for (const line of text.split('\n')) {
-        const trimmed = line.trimStart();
-        if (trimmed === '' || trimmed.startsWith('#'))
-            continue;
-        const eq = line.indexOf('=');
-        if (eq === -1)
-            continue;
-        const key = line.slice(0, eq).trim();
-        if (key !== 'VERCEL_TOKEN')
-            continue;
-        let value = line.slice(eq + 1).replace(/\s+$/, '');
-        if (value.length >= 2 &&
-            ((value.startsWith('"') && value.endsWith('"')) ||
-                (value.startsWith("'") && value.endsWith("'")))) {
-            value = value.slice(1, -1);
+export function readVercelToken(rail = defaultRail()) {
+    return rail.get('VERCEL_TOKEN');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// VAULT-002 — is this repo on the `core` profile? (the vault is not offered there)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The local wrapper that injects the vault's `local` environment into the kit's scripts
+ * (VAULT-003). The `core` profile does not ship it, so a repo without it cannot work from the
+ * vault — that is the fallback signal when there is no lockfile to read.
+ */
+export const VAULT_WRAPPER_PATH = WITH_VAULT_SCRIPT_FILE;
+/**
+ * The org vault's coordinates as the repo's brain carries them — what the wrapper reads to find
+ * the instance. Shipped by the kit (`.claude/policy/`); `factory update` brings it when missing.
+ */
+export const VAULT_POLICY_PATH = '.claude/policy/vault.json';
+/**
+ * Detect the `core` profile, where `provision` does not offer the vault (VAULT-002). One
+ * function, reused by VAULT-004's preflight:
+ *
+ *   1. A READABLE lockfile decides: `profile === 'core'` → core; `full` → not core, even if the
+ *      wrapper is missing (an outdated brain is VAULT-004's `factory update`, not a profile).
+ *   2. Only when there is no lockfile to read (absent, or present but unparseable): core when
+ *      `scripts/tools/with-vault.mjs` is absent.
+ *
+ * 🔴 NEVER by the absence of `package.json`: a `full` derivative always has one, but so can a
+ * `core` repo of another stack that happens to use Node tooling — the lockfile is the authority.
+ * `lockfile.ts` is only READ here.
+ */
+export function detectCoreProfile(rootDir) {
+    if (hasLockfile(rootDir)) {
+        try {
+            return readLockfile(rootDir).profile === 'core' ? 'lockfile' : null;
+        }
+        catch {
+            // Unreadable lockfile → no profile to read; fall through to the wrapper signal.
         }
-        return value === '' ? null : value;
     }
-    return null;
+    return existsSync(path.join(rootDir, VAULT_WRAPPER_PATH)) ? null : 'no-wrapper';
+}
+/**
+ * VAULT-004 — in a `full` repo about to get the vault, the files the vault needs locally must be
+ * on disk: the wrapper that injects it into the scripts and `vault.json`, the coordinates it
+ * reads. Without them the project would be created and `pnpm dev` would start with no secrets.
+ * The fix is `factory update` (it brings a missing kit file), or `--no-vault` to go on without.
+ *
+ * `core` never reaches the check (the vault is not offered there): detected by the ONE function
+ * {@link detectCoreProfile}, shared with VAULT-002.
+ *
+ * @throws {PreflightError} naming every missing file.
+ */
+export function assertVaultBrainPresent(rootDir) {
+    if (detectCoreProfile(rootDir) !== null)
+        return;
+    const missing = [VAULT_WRAPPER_PATH, VAULT_POLICY_PATH].filter((rel) => !existsSync(path.join(rootDir, rel)));
+    if (missing.length === 0)
+        return;
+    throw new PreflightError(`Este repo no trae lo que la bóveda necesita en local: falta ${missing
+        .map((rel) => `\`${rel}\``)
+        .join(' y ')}. No creé nada.\n` +
+        '  · Corre `factory update` para traer el cerebro al día y repite el comando.\n' +
+        '  · O sigue sin bóveda, como hasta hoy: repite el comando con `--no-vault`.');
 }