@timekast/factory 1.22.0 → 1.23.0

package/dist/commands/add.js

@@ -36,11 +36,11 @@ import { applyPlan, defaultBackupDir, validateStagedManifest } from '../lib/atom
 import { CLIError } from '../lib/cli-error.js';
 import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
 import { hasLockfile, writeInitialLockfile } from '../lib/lockfile.js';
-import { detectProfile, emptyShippedE2EPort, insertFactoryUpdateScript, } from '../lib/package-json.js';
+import { detectProfile, maintainKitScripts } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { detectRepo } from '../lib/repo-detection.js';
 import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
-import { runUpdate } from './update.js';
+import { reportPkgMutations, runUpdate } from './update.js';
 /** Message shown when `add` runs outside any git repo context. */
 const NO_REPO_MESSAGE = 'No hay repositorio git aquí. Ejecuta `git init` primero, o usa `factory new` para crear un proyecto desde cero.';
 /** Parse `add`'s argv slice into flags. Unknown flags are ignored here. */
@@ -160,19 +160,38 @@ export async function runAdd(flags = { core: false, full: false }) {
     // installed). We NEVER create a package.json in a non-Node repo.
     const pkgPath = path.join(root, 'package.json');
     let scriptAction = 'none';
+    // What the maintenance actually MOVED in this repo's package.json, reported below with the very
+    // function `update` reports from. Empty until proven otherwise, so a repo without package.json
+    // (or with an invalid one) says nothing rather than claiming a no-op.
+    let pkgMutations = { inserted: [], retired: [], e2ePortEmptied: false };
     if (existsSync(pkgPath)) {
         try {
-            scriptAction = insertFactoryUpdateScript(pkgPath).action;
-            // Same maintenance `update` does: a repo that adopts the brain now gets the shipped
-            // `ports.e2e: 3006` emptied here, instead of waiting for a later `factory update`.
-            // Conditional — a port the dev chose is never touched.
-            emptyShippedE2EPort(pkgPath);
+            // The SAME maintenance `update` does, and now literally the same function
+            // (`maintainKitScripts`) rather than a hand-copied subset of it. The subset was the bug:
+            // this call site inserted the aliases and emptied the port but never retired anything, so
+            // a legacy repo adopting the brain while `scripts/tools/e2e-direct.ts` was still on disk
+            // got `test:e2e:direct` / `test:e2e:ui` — the two runner bypasses — WRITTEN by the tool
+            // that exists to retire them.
+            const maintenance = maintainKitScripts(pkgPath);
+            scriptAction = maintenance.insert.action;
+            // 🔴 The other half of that same defect: this call site read `insert.action` and threw the
+            // rest away, so the removals happened in silence. `removeRetiredScripts` is explicit about
+            // why that is not acceptable — "a dev who used one of these daily must be told it went, and
+            // by name" — and `update` already tells them. `add` does now too, with the same sentences.
+            pkgMutations = {
+                // Deliberately not `maintenance.inserted`: on a first install the alias is NEW, not "put
+                // back", and this command announces it in its own words three lines below.
+                inserted: [],
+                retired: maintenance.retired,
+                e2ePortEmptied: maintenance.portAction === 'emptied',
+            };
         }
         catch {
             scriptAction = 'none'; // invalid package.json — skip the alias, brain still installed
         }
     }
     console.log(`\n✔ Cerebro \`${profile}\` v${version} instalado. Lockfile escrito en \`.timekast/lockfile.json\`.`);
+    reportPkgMutations(pkgMutations);
     if (scriptAction === 'added' || scriptAction === 'already-correct') {
         console.log('Para actualizar: `pnpm factory:update` (alias de `npx @timekast/factory update`).');
     }

package/dist/commands/provision.js

@@ -25,7 +25,7 @@ import { execa } from 'execa';
 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, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, } from '../lib/cloudflare-api.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 { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
 import { defaultEnvPath, readEnvKeyNames, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
@@ -885,7 +885,10 @@ export async function provisionVercel(rootDir, state, teamId, deps = {}) {
     // re-points the PRODUCTION WEBAUTHN_RP_ID too (`updateDomainEnv`, BOOT-004).
     // MFA_ENCRYPTION_KEY is minted independently per env (base64url) so a derivative
     // with MFA enabled never boots broken (P-1).
-    const rpDomains = provisionDomains(state.projectName);
+    // From the state when it already has one (DOM-001): re-deriving the host of an
+    // existing project would move its rpID to another zone, and a passkey dies with
+    // its rpID. A first provision has no `dns` yet → falls back to the current zone.
+    const rpDomains = existingProvisionDomains(state.projectName, state.dns);
     const plan = buildEnvPlan({
         mainDatabaseUrl: neonSecrets.mainPooled,
         developDatabaseUrl: neonSecrets.developPooled,
@@ -1931,17 +1934,20 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
     }
     else {
         const cfToken = await resolveDnsToken(route, envPath, deps.headless ?? false);
-        const zoneName = apexZoneOf(domain);
         const cloudflareDeps = { fetchImpl };
         let zoneId;
         try {
-            zoneId = await resolveZoneIdForName(zoneName, cfToken, cloudflareDeps);
+            // The client's domain, whose shape we do NOT control: `resolveZoneIdForDomain`
+            // asks Cloudflare which candidate is a real zone instead of assuming the last
+            // two labels (DOM-002) — `app.miapp.com.mx` belongs to `miapp.com.mx`, and
+            // guessing `com.mx` used to fail the whole step.
+            zoneId = await resolveZoneIdForDomain(domain, cfToken, cloudflareDeps);
         }
         catch (error) {
             if (error instanceof CloudflareApiError) {
-                throw cloudflareErrorToCliError(error, `resolver la zona \`${zoneName}\``);
+                throw cloudflareErrorToCliError(error, `resolver la zona de \`${domain}\``);
             }
-            throw error; // resolveZoneIdForName's own CLIError (zone not found) propagates.
+            throw error; // resolveZoneIdForDomain's own CLIError (no candidate) propagates.
         }
         resendDns = { zoneId, token: cfToken };
         try {
@@ -2012,7 +2018,10 @@ export async function provisionClientDomain(rootDir, state, teamId, domain, deps
  * detach failed (the interim is still live — its CNAME must keep resolving).
  */
 async function retireInterimDomain(projectId, token, teamId, state, deps, fetchImpl) {
-    const interim = provisionDomains(state.projectName).prod;
+    // From the STATE, not from the slug: a project provisioned before DOM-001 lives on
+    // `timekast.mx`, and retiring a `.com` host it never had would report success while
+    // the real interim stayed live.
+    const interim = existingProvisionDomains(state.projectName, state.dns).prod;
     let approved = deps.preConfirmed === true;
     if (!approved) {
         if (deps.headless) {
@@ -2044,10 +2053,17 @@ async function retireInterimDomain(projectId, token, teamId, state, deps, fetchI
     await deleteInterimCname(interim, deps.envPath ?? defaultEnvPath(), fetchImpl);
 }
 /**
- * Delete the interim CNAME (`{slug}.timekast.mx`) from the org Cloudflare zone
+ * Delete the interim CNAME (`{slug}.<org zone>`) from the org Cloudflare zone
  * after Vercel detached the domain (BOOT-007). Without this, the record stays
  * orphaned: it keeps resolving to `cname.vercel-dns.com` while no Vercel project
- * answers for the host → a 404 forever, dead weight in the `timekast.mx` zone.
+ * answers for the host → a 404 forever, dead weight in the org zone.
+ *
+ * 🔴 The zone is derived from the domain being retired ({@link apexZoneOf}), NOT
+ * from {@link TIMEKAST_ZONE_NAME} (DOM-001). A project provisioned before that
+ * change lives on `timekast.mx`, which stays live; resolving the fixed CURRENT
+ * zone would look the record up in `timekast.com`, not find it there, and report a
+ * clean retire while the real record stayed orphaned in `.mx` forever. The domain
+ * arrives from the provision state, so it is always the zone the record is in.
  *
  * Runs ONLY inside the already-confirmed retire block (a declined prompt never
  * reaches here). Best-effort by design (issue §4 + §8): EVERY failure — missing
@@ -2060,9 +2076,10 @@ async function retireInterimDomain(projectId, token, teamId, state, deps, fetchI
  * touched: only the prod interim name is looked up.
  */
 async function deleteInterimCname(interim, envPath, fetchImpl) {
+    const zoneName = apexZoneOf(interim);
     const warnRetryable = (reason) => {
         console.warn(`⚠ No se pudo borrar el CNAME interino \`${interim}\` en Cloudflare (${reason}).\n` +
-            `  El registro queda en la zona \`${TIMEKAST_ZONE_NAME}\`; bórralo a mano o reintenta. El paso NO falla por esto.`);
+            `  El registro queda en la zona \`${zoneName}\`; bórralo a mano o reintenta. El paso NO falla por esto.`);
     };
     const cloudflareToken = readCloudflareApiKey(envPath);
     if (!cloudflareToken) {
@@ -2071,7 +2088,7 @@ async function deleteInterimCname(interim, envPath, fetchImpl) {
     }
     const cloudflareDeps = { fetchImpl };
     try {
-        const zoneId = await resolveZoneId(cloudflareToken, cloudflareDeps);
+        const zoneId = await resolveZoneIdForName(zoneName, cloudflareToken, cloudflareDeps);
         const record = await findCnameRecord(zoneId, interim, cloudflareToken, cloudflareDeps);
         // Same outcome narration as the Vercel retire above (no-echo — only the
         // domain NAME prints; the token never crosses this boundary).
@@ -2330,10 +2347,21 @@ async function adoptGithub(slug, deps) {
     }
 }
 /**
- * Reconstruct the interim domains' DNS presence (read-only). The domain NAMES are
- * always derivable from the slug (never `unknown`); this only CONFIRMS the CNAMEs
- * exist (a missing/unauthorized Cloudflare token logs a notice and continues — the
- * domains are still recorded by name). Returns the `{ dev, prod }` names regardless.
+ * Reconstruct the interim domains (read-only) — DISCOVERED, not assumed (DOM-002).
+ *
+ * `--adopt` is the rescue path: the stack exists but its provision state is gone,
+ * so this rebuilds it by asking each provider. For domains it used to SKIP the
+ * asking and derive the names from the slug, which was harmless while one org zone
+ * existed. It stopped being harmless when the org moved to `timekast.com` and
+ * `timekast.mx` stayed live: adopting a project born on `.mx` would have written a
+ * `.com` host it never had — and since every other path (retire, destroy, the
+ * WebAuthn rpID) now reads the state, the wrong host would enter poisoned at the
+ * source, through the very door DOM-001 closed from the other side.
+ *
+ * So it probes the org zones in order and keeps the one whose CNAMEs actually
+ * exist. Deriving from the slug survives only as the LAST resort — no token, no
+ * zone reachable, or a project whose CNAMEs are genuinely absent — where naming a
+ * domain by convention is all anyone can do, and the narration says so.
  */
 async function adoptDns(slug, deps) {
     const domains = provisionDomains(slug);
@@ -2343,20 +2371,43 @@ async function adoptDns(slug, deps) {
             'confirmar sus CNAMEs (es read-only; corre `factory secrets <archivo>` si quieres la verificación).');
         return domains;
     }
-    try {
-        const cfDeps = { fetchImpl: deps.fetchImpl };
-        const zoneId = await resolveZoneId(cfToken, cfDeps);
-        for (const name of [domains.dev, domains.prod]) {
-            const record = await findCnameRecord(zoneId, name, cfToken, cfDeps);
-            console.log(record
-                ? `  ✔ CNAME ${name} encontrado (${record.content})`
-                : `  · CNAME ${name} no encontrado (lo registro por nombre igual)`);
+    const cfDeps = { fetchImpl: deps.fetchImpl };
+    for (const zone of ORG_ZONE_NAMES) {
+        const candidate = { dev: `${slug}-dev.${zone}`, prod: `${slug}.${zone}` };
+        let zoneId;
+        try {
+            zoneId = await resolveZoneIdForName(zone, cfToken, cfDeps);
+        }
+        catch {
+            // Zone out of the token's scope or gone: not this one, try the next.
+            continue;
+        }
+        try {
+            const found = [];
+            for (const name of [candidate.dev, candidate.prod]) {
+                const record = await findCnameRecord(zoneId, name, cfToken, cfDeps);
+                if (record) {
+                    found.push(name);
+                    console.log(`  ✔ CNAME ${name} encontrado (${record.content})`);
+                }
+            }
+            // EITHER domain is enough to place the project: a half-retired stack (prod
+            // interim already retired, dev still up) still belongs to this zone.
+            if (found.length > 0) {
+                if (zone !== TIMEKAST_ZONE_NAME) {
+                    console.log(`  ℹ El proyecto vive en la zona \`${zone}\` (anterior a la mudanza del org) — ` +
+                        'registro sus dominios ahí, no en la zona actual.');
+                }
+                return candidate;
+            }
+        }
+        catch {
+            // A read-only DNS check failure must never fail the adopt (issue §4).
+            console.warn(`⚠ No se pudo verificar los CNAMEs en \`${zone}\` (read-only) — continúo.`);
         }
     }
-    catch {
-        // A read-only DNS check failure must never fail the adopt (issue §4).
-        console.warn(`⚠ No se pudo verificar los CNAMEs en Cloudflare (read-only) — continúo.`);
-    }
+    console.log(`  · Sin CNAMEs en ninguna zona del org (${ORG_ZONE_NAMES.join(', ')}) — ` +
+        'registro los dominios por nombre en la zona actual.');
     return domains;
 }
 /** Print the reconstructed adopt state in plain es-MX (the non-`--json` narration). */
@@ -2790,7 +2841,11 @@ async function teardownProviders(target, deps) {
     //    domain configured → nothing to remove; a single provider failure continues).
     const vercelToken = readVercelToken(deps.envPath);
     const cfToken = readCloudflareApiKey(deps.envPath);
-    let zoneId = null;
+    // Cached PER ZONE, not one id for the whole loop (DOM-002). A project's domains
+    // can span zones — the org interim and the client's own — and a single cached id
+    // made the second domain get looked up inside the first one's zone, so its CNAME
+    // was never found and stayed behind. Keyed by domain→zone-id, resolved on demand.
+    const zoneIdByDomain = new Map();
     for (const domain of target.domains) {
         // The domain is registered in the state, so there IS a resource to remove. If
         // a prerequisite is missing (FIX 3: e.g. `scope` null on an adopted stack, or
@@ -2829,10 +2884,12 @@ async function teardownProviders(target, deps) {
         }
         else {
             try {
-                if (zoneId === null) {
-                    zoneId = await resolveZoneIdForName(apexZoneOf(domain), cfToken, {
+                let zoneId = zoneIdByDomain.get(domain);
+                if (zoneId === undefined) {
+                    zoneId = await resolveZoneIdForDomain(domain, cfToken, {
                         fetchImpl: deps.fetchImpl,
                     });
+                    zoneIdByDomain.set(domain, zoneId);
                 }
                 outcomes.push(await destroyCloudflareRecord(domain, zoneId, cfToken, deps.fetchImpl));
             }
@@ -3091,7 +3148,9 @@ export async function runProvision(flags) {
             if (steps.length > 0)
                 printPlan(result);
             if (hasDomain) {
-                const interim = provisionDomains(projectName).prod;
+                // Same rule as the real retire (DOM-001): the plan must print the interim the
+                // project ACTUALLY has, not one re-derived in the current org zone.
+                const interim = existingProvisionDomains(projectName, state?.dns).prod;
                 printClientDomainPlan(flags.domain, interim, flags.dns, flags.confirm);
             }
         }

package/dist/commands/update.js

@@ -45,7 +45,7 @@ import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE,
 import { decideCommit } from '../lib/commit-decision.js';
 import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
-import { detectProfile, emptyShippedE2EPort, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
+import { detectProfile, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
 import { hasProvisionState } from '../lib/provision-state.js';
@@ -104,6 +104,140 @@ function hashDiskPaths(rootDir, paths) {
     }
     return map;
 }
+/** Unchanged lines kept around each change in the `[3] Ver diff` view. */
+const DIFF_CONTEXT_LINES = 3;
+/**
+ * Ceiling on how many diff lines `[3] Ver diff` prints. The point of the view is that a
+ * 6000-line file stops being dumped twice; a pathological conflict where almost every line
+ * differs must not reintroduce that, so the render stops here and says how much it cut.
+ */
+const DIFF_MAX_LINES = 200;
+/**
+ * Ceiling on the LCS table (rows × columns) the line matcher may allocate. Past it the two
+ * sides are reported as a block replacement instead — coarser, but bounded. The printed
+ * output is capped by {@link DIFF_MAX_LINES} either way.
+ */
+const DIFF_MAX_LCS_CELLS = 250_000;
+/** Marker printed where unchanged lines were skipped between two hunks. */
+const DIFF_ELLIPSIS = '  …';
+/** Split into lines with CRLF normalized and no phantom trailing empty line. */
+function splitLines(text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * Longest-common-subsequence ops for two SMALL line arrays. Only ever called on the
+ * differing middle after the common prefix/suffix is trimmed, and only when the table fits
+ * under {@link DIFF_MAX_LCS_CELLS} — so the quadratic table stays bounded by construction.
+ */
+function lcsOps(a, b) {
+    const cols = b.length + 1;
+    const table = new Uint32Array((a.length + 1) * cols);
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i * cols + j] =
+                a[i] === b[j]
+                    ? table[(i + 1) * cols + (j + 1)] + 1
+                    : Math.max(table[(i + 1) * cols + j], table[i * cols + (j + 1)]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            ops.push({ sign: ' ', text: a[i] });
+            i++;
+            j++;
+        }
+        else if (table[(i + 1) * cols + j] >= table[i * cols + (j + 1)]) {
+            ops.push({ sign: '-', text: a[i++] });
+        }
+        else {
+            ops.push({ sign: '+', text: b[j++] });
+        }
+    }
+    while (i < a.length)
+        ops.push({ sign: '-', text: a[i++] });
+    while (j < b.length)
+        ops.push({ sign: '+', text: b[j++] });
+    return ops;
+}
+/** Full op list for two files: common prefix + matched middle + common suffix. */
+function diffLines(a, b) {
+    const max = Math.min(a.length, b.length);
+    let prefix = 0;
+    while (prefix < max && a[prefix] === b[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < max - prefix && a[a.length - 1 - suffix] === b[b.length - 1 - suffix])
+        suffix++;
+    const midA = a.slice(prefix, a.length - suffix);
+    const midB = b.slice(prefix, b.length - suffix);
+    const middle = midA.length * midB.length <= DIFF_MAX_LCS_CELLS
+        ? lcsOps(midA, midB)
+        : [
+            ...midA.map((text) => ({ sign: '-', text })),
+            ...midB.map((text) => ({ sign: '+', text })),
+        ];
+    return [
+        ...a.slice(0, prefix).map((text) => ({ sign: ' ', text })),
+        ...middle,
+        ...a.slice(a.length - suffix).map((text) => ({ sign: ' ', text })),
+    ];
+}
+/**
+ * Render what CHANGED between the local file and the Factory's, not both files. The old
+ * view dumped each side whole, so for the e2e runner (~6000 lines) it was unreadable and
+ * nobody used it — everyone answered "take the Factory's" blind, which is how local work
+ * disappeared without anyone reading it first.
+ *
+ * `-` is the local line, `+` the Factory's, with {@link DIFF_CONTEXT_LINES} of context around
+ * each change and `…` where unchanged stretches were skipped. Exported so the CLI suite can
+ * assert the bound directly (no file is ever printed whole).
+ */
+export function renderConflictDiff(local, incoming) {
+    const ops = diffLines(splitLines(local), splitLines(incoming));
+    const keep = new Array(ops.length).fill(false);
+    let added = 0;
+    let removed = 0;
+    ops.forEach((op, idx) => {
+        if (op.sign === ' ')
+            return;
+        if (op.sign === '+')
+            added++;
+        else
+            removed++;
+        const from = Math.max(0, idx - DIFF_CONTEXT_LINES);
+        const to = Math.min(ops.length - 1, idx + DIFF_CONTEXT_LINES);
+        for (let k = from; k <= to; k++)
+            keep[k] = true;
+    });
+    if (added === 0 && removed === 0) {
+        return 'Sin diferencias de contenido: solo cambió el formato (fin de línea o espacios al final).';
+    }
+    const out = [];
+    let cut = 0;
+    let skipping = false;
+    for (let idx = 0; idx < ops.length; idx++) {
+        if (!keep[idx]) {
+            if (!skipping && out.length > 0)
+                out.push(DIFF_ELLIPSIS);
+            skipping = true;
+            continue;
+        }
+        skipping = false;
+        if (out.length >= DIFF_MAX_LINES) {
+            cut++;
+            continue;
+        }
+        out.push(`${ops[idx].sign} ${ops[idx].text}`);
+    }
+    const tail = `(${removed} línea(s) tuya(s) reemplazada(s), ${added} del Factory${cut > 0 ? `; ${cut} línea(s) de diff no mostradas` : ''})`;
+    return `${out.join('\n')}\n${tail}`;
+}
 /** Resolve a single conflict via prompt — NO default option (design §7.3). */
 async function resolveConflict(conflict, stagedDir, rootDir) {
     for (;;) {
@@ -126,7 +260,8 @@ async function resolveConflict(conflict, stagedDir, rootDir) {
         if (choice === 'diff') {
             const local = readFileSync(path.join(rootDir, conflict.path), 'utf8');
             const incoming = readFileSync(path.join(stagedDir, conflict.path), 'utf8');
-            console.log(`\n--- local (${conflict.path}) ---\n${local}\n--- Factory ---\n${incoming}\n`);
+            console.log(`\n--- diff de ${conflict.path} — «-» lo tuyo, «+» lo del Factory ---\n` +
+                `${renderConflictDiff(local, incoming)}\n`);
             continue;
         }
         return choice;
@@ -262,9 +397,12 @@ async function runResume(rootDir, flags) {
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
     // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
-    maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
     await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes], flags);
     rmSync(state.stagedDir, { recursive: true, force: true });
+    // A resumed update maintains package.json exactly like a normal one, so it owes the dev the
+    // same account of what it moved there (`BND-004`).
+    reportPkgMutations(pkgMutations);
     console.log('✔ `update` retomado y completado.');
     // A resumed update that succeeds completed the setup → show the end-pointer
     // (PVSKILL-002 §8 edge: `--resume` SÍ lo muestra). Suppressed only in headless
@@ -309,9 +447,14 @@ function warnOnScriptConflict(action, _pkgPath) {
  * pre-commit hook could reformat the freshly-installed kit files.
  */
 function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
-    maintainDerivedPkg(rootDir, agentKitVersion);
+    const pkgMutations = maintainDerivedPkg(rootDir, agentKitVersion);
     syncDerivedGitattributes(rootDir, stagedDir);
     syncDerivedPrettierignore(rootDir, stagedDir);
+    return pkgMutations;
+}
+/** A run that mutated nothing (no package.json, or the maintenance failed and warned). */
+function emptyPkgMutations() {
+    return { inserted: [], retired: [], e2ePortEmptied: false };
 }
 /**
  * Maintain the derived project's package.json: ensure the `factory:*` scripts
@@ -322,25 +465,37 @@ function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
  * package.json). `factoryVersion` (the frozen birth stamp) and `version` (the app
  * semver) are untouched. No-op (not an error) when the repo has no package.json
  * (a non-Node derivative).
+ *
+ * Returns what it MUTATED, so the closing summary can name it (`BND-004`). Every one of these
+ * edits used to happen in silence, in both directions: aliases appearing, aliases disappearing,
+ * a port emptied — the same failure mode the whole epic exists to close.
  */
 function maintainDerivedPkg(rootDir, agentKitVersion) {
     const pkgPath = path.join(rootDir, 'package.json');
     if (!existsSync(pkgPath))
-        return;
+        return emptyPkgMutations();
     // Tolerant (mirrors `add`): a malformed package.json must NOT throw AFTER the
     // brain was already applied + the lockfile written — the install succeeded; the
     // script/version mirror is best-effort. Warn and move on.
     try {
-        warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
+        // The kit-owned maintenance itself — insertion, retirement, port — lives in ONE place
+        // (`maintainKitScripts`), with the order and the reconciliation argued there. `add` performs
+        // the same maintenance on the same kind of repo and used to replicate only half of it; a
+        // shared function is what keeps a third caller from diverging again.
+        const maintenance = maintainKitScripts(pkgPath);
+        warnOnScriptConflict(maintenance.insert.action, pkgPath);
+        // Update-only: `add` installs a brain without an `agentKitVersion` to mirror yet.
         setAgentKitVersion(pkgPath, agentKitVersion);
-        // Retire the E2E port the kit used to ship (`ports.e2e: 3006`) so the runner that just
-        // arrived via `scripts/**` can derive one per checkout. Conditional and silent: it only
-        // ever touches that exact value, so a dev-chosen port survives every update untouched.
-        emptyShippedE2EPort(pkgPath);
+        return {
+            inserted: maintenance.inserted,
+            retired: maintenance.retired,
+            e2ePortEmptied: maintenance.portAction === 'emptied',
+        };
     }
     catch {
         console.warn('Aviso: no se pudo actualizar package.json (¿JSON inválido?); el cerebro se instaló igual. ' +
             'Corrige package.json y vuelve a correr `factory update` para sincronizar agentKitVersion.');
+        return emptyPkgMutations();
     }
 }
 /**
@@ -400,6 +555,14 @@ function syncDerivedPrettierignore(rootDir, stagedDir) {
         console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
     }
 }
+/**
+ * The kit's own test folder. It stopped shipping to derivatives (`BND-003`): those tests
+ * validate KIT tooling, and inside a derivative they ran against a `src/` that may have
+ * diverged. Named here because the closing summary has to tell a derivative that edited one
+ * of them that it is now theirs alone — the kit no longer tracks it, so nothing will ever
+ * update it again. Trailing slash so the prefix match cannot catch a sibling path.
+ */
+const KIT_TESTS_DIR = 'scripts/tools/__tests__/';
 /** Exit code of `--dry-run` when the preview found conflicts (0 = none). Lets a
  * non-interactive caller (the GUI) branch on the result instead of clobbering. */
 const DRY_RUN_CONFLICTS_EXIT = 2;
@@ -412,7 +575,9 @@ const DRY_RUN_CONFLICTS_EXIT = 2;
  */
 function reportDryRun(diff, manifest) {
     console.log(`\n🔍 Vista previa de update a v${manifest.version} — no se modificó nada:`);
-    reportSummary(diff, manifest);
+    // Nothing was applied: no conflict was resolved (so nothing was overwritten) and the
+    // package.json maintenance never ran (so nothing moved there either).
+    reportSummary(diff, manifest, [], emptyPkgMutations());
     if (diff.conflicts.length > 0) {
         console.log('\nArchivos en conflicto (los modificaste tú y el Factory también los cambió):');
         for (const c of diff.conflicts)
@@ -420,18 +585,81 @@ function reportDryRun(diff, manifest) {
         console.log('\nPara resolverlos, corre `factory update` (sin `--dry-run`): pregunta archivo por archivo.');
     }
 }
-/** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
-function reportSummary(diff, manifest) {
+/**
+ * Name what the update did to `package.json` — in BOTH directions (`BND-004`).
+ *
+ * Only real mutations print, and each one exactly once: an alias that was already correct, a
+ * retired key the dev had pointed somewhere of their own (preserved, not removed), a port they
+ * chose, a second run over an already-empty port — all silent, because they are no-ops. That is
+ * what keeps this reportable instead of a log of everything the update looked at, and what makes
+ * it idempotent: the run after this one says nothing.
+ *
+ * A `conflict` (a divergent `factory:update`) is NOT here: it has its own existing warning
+ * (`warnOnScriptConflict`), and it is not an insertion — nothing changed.
+ *
+ * EXPORTED because `add` performs the SAME maintenance (`maintainKitScripts`) on the same kind of
+ * repo, and used to consume only `insert.action` — so a legacy repo adopting the brain had its
+ * `test:e2e:direct` / `test:e2e:ui` removed and its `ports.e2e` emptied in silence, which is the
+ * exact defect this function exists to close on the other command. One report, two callers: a
+ * second copy of these sentences would drift the day one of them is reworded.
+ */
+export function reportPkgMutations(m) {
+    if (m.inserted.length > 0) {
+        console.log(`\nRepuestos en \`package.json\` — faltaban o apuntaban a un comando viejo del kit: ${m.inserted.join(', ')}.`);
+    }
+    if (m.retired.length > 0) {
+        console.log(`\nRetirados de \`package.json\`: ${m.retired.join(', ')}.`);
+        console.log('  Ese atajo se retiró; el flujo con guard es `pnpm test:e2e` (pasa por el runner, que arma su base de datos desechable).');
+    }
+    if (m.e2ePortEmptied) {
+        console.log('\nSe vació el valor de `ports.e2e` en `package.json` — el puerto que shippeaba el kit (la clave se conserva).');
+        console.log('  El runner de E2E deriva ahora un puerto de la ruta de este checkout, así dos copias del repo corren su suite a la vez. ' +
+            'Pon un número ahí para fijar uno.');
+    }
+}
+/**
+ * Print the deletes + kept-retired (design §7.6 — visible) + what got OVERWRITTEN over local
+ * work + what moved in `package.json` + a one-line summary.
+ *
+ * `overwrittenLocal` is the list of conflicts resolved as "take the Factory's": the only
+ * files in the run that HAD local changes and lost them. A file the dev never touched is not
+ * in it — this is not a log of everything the update wrote, it is the short list where a
+ * `git diff` right now still shows what was there. That is the whole recovery story: the
+ * three derivatives measured with drift had their work committed, so git already covers
+ * getting it back; what was missing was anyone finding out it went (`BND-002 §1`).
+ */
+function reportSummary(diff, manifest, overwrittenLocal, pkgMutations) {
+    reportPkgMutations(pkgMutations);
     if (diff.deleteSilent.length > 0) {
         console.log('\nArchivos retirados por el Factory en esta versión:');
         for (const e of diff.deleteSilent)
             console.log(`  Archivos retirados: ${e.path}`);
     }
-    if (diff.keptRetiredLocal.length > 0) {
+    // Kept-retired files are split in two, because the kit's own tests need a different
+    // sentence: they are not "a file you edited that the kit dropped", they are a test of the
+    // KIT's tooling now stranded inside your repo, running on every `pnpm test` against a
+    // `src/` the kit no longer knows (`BND-003 §6`).
+    const orphanKitTests = diff.keptRetiredLocal.filter((e) => e.path.startsWith(KIT_TESTS_DIR));
+    const keptOther = diff.keptRetiredLocal.filter((e) => !e.path.startsWith(KIT_TESTS_DIR));
+    if (keptOther.length > 0) {
         console.log('\nConservados con tus cambios — ya no los gestiona el Factory:');
-        for (const e of diff.keptRetiredLocal)
+        for (const e of keptOther)
             console.log(`  Conservado (editado localmente): ${e.path}`);
     }
+    if (orphanKitTests.length > 0) {
+        console.log('\nTests del kit que editaste y quedaron huérfanos — ya no los gestiona el Factory:');
+        for (const e of orphanKitTests)
+            console.log(`  Huérfano (test del kit, editado por ti): ${e.path}`);
+        console.log('  El kit dejó de shippear sus propios tests: probaban herramientas del kit contra un ' +
+            '`src/` que tu proyecto pudo haber cambiado. Los tuyos siguen corriendo en tu `pnpm test`; ' +
+            'mantenerlos (o borrarlos) ya es decisión tuya.');
+    }
+    if (overwrittenLocal.length > 0) {
+        console.log('\nSobrescritos con la versión del Factory — tenías cambios locales ahí:');
+        for (const p of overwrittenLocal)
+            console.log(`  Sobrescrito (tenía cambios locales): ${p}`);
+        console.log('  Para ver qué había, corre `git diff` sobre esas rutas antes de commitear el update.');
+    }
     const unchanged = diff.unchanged.length > 0 ? ` (${diff.unchanged.length} sin cambios)` : '';
     const kept = diff.keptRetiredLocal.length > 0 ? `, ${diff.keptRetiredLocal.length} conservados` : '';
     console.log(`\n✔ update a v${manifest.version} (perfil ${manifest.profile}): ${diff.add.length} agregados, ` +
@@ -615,9 +843,12 @@ export async function runUpdate(flags, deps = {}) {
         // update uses `stampBirth` alone, so a prior `beta` is cleared by omission.
         writeLockfile(rootDir, flags.beta ? stampBeta(oldLock, manifest) : stampBirth(oldLock, manifest));
         clearUpdateState(rootDir);
-        maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+        const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
         await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes], flags);
-        reportSummary(diff, manifest);
+        // `theirsConflicts` IS the overwritten-local list: same source whether the dev answered
+        // the prompt, passed `--theirs-all`, or ran headless — there is no second path. The
+        // package.json mutations ride the SAME closing summary, not three loose notices.
+        reportSummary(diff, manifest, theirsConflicts, pkgMutations);
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
         // `--verify`/`--resume` short-circuit above (verify NEVER prints), an error path
         // throws earlier, and headless `--yes` is suppressed (CI noise).
@@ -716,7 +947,8 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     // the just-installed files) PLUS the birth stamp. A legacy auto-register is the
     // first sync this repo records, so the birth seal = the manifest's version.
     writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
-    maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+    reportPkgMutations(pkgMutations);
     if (claudeMdExists) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
             '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');

package/dist/lib/cloudflare-api.js

@@ -4,14 +4,17 @@
  * A THIN, reusable Cloudflare client that mirrors the proven fetch shape of
  * `vercel-env.ts` (`Authorization: Bearer ${token}` + a single central URL
  * builder + an injectable `fetchImpl` seam). Its scope is DNS-ONLY: it resolves
- * the `timekast.mx` zone id, looks up an existing CNAME, creates one
+ * the org zone id, looks up an existing CNAME, creates one
  * (`proxied: false` so Vercel's own TLS terminates the domain), and PATCHes an
  * existing record that was manually left `proxied: true` back to `false`.
  *
  * 🔴 Scope contract (issue §4 + the frozen plan): the token handed in here is the
- * shared org Cloudflare token from the rail, minted SCOPED to the `timekast.mx` zone
- * with DNS-edit only — never an account-wide token (a DNS-write leak over `timekast.mx` could
- * repoint records, intercept MX, or mint certs). A 403 from any call therefore
+ * shared org Cloudflare token from the rail, minted SCOPED to the org zones with
+ * DNS-edit only — never an account-wide token (a DNS-write leak over an org zone could
+ * repoint records, intercept MX, or mint certs). Since DOM-001 the org zone is
+ * `timekast.com`, but `timekast.mx` stays live with already-provisioned projects on
+ * it, so the token must be scoped to BOTH: the retire/destroy paths reach into
+ * whichever zone the project's own domain belongs to. A 403 from any call therefore
  * means "the token is out of scope for this zone" and the caller maps it to an
  * actionable `CLIError` (issue §8 Gherkin) — it NEVER deletes a record to recover.
  *
@@ -31,14 +34,28 @@
 import { CLIError } from './cli-error.js';
 /** Base URL of the Cloudflare REST API v4 (named constant — never an inline literal). */
 export const CLOUDFLARE_API_BASE = 'https://api.cloudflare.com/client/v4';
-/** The org DNS zone every provisioned interim domain lives under (issue §4). */
-export const TIMEKAST_ZONE_NAME = 'timekast.mx';
+/**
+ * The org DNS zone every NEWLY provisioned interim domain lives under (issue §4).
+ *
+ * DOM-001 moved it from `timekast.mx` to `timekast.com`. `timekast.mx` was NOT
+ * retired — it redirects to `.com` and keeps serving the projects already
+ * provisioned under it. So this constant is the default for what is BORN from now
+ * on, never an assumption about where an EXISTING project lives: any path that
+ * touches an already-provisioned domain derives its zone from that domain
+ * ({@link apexZoneOf}), not from here.
+ */
+export const TIMEKAST_ZONE_NAME = 'timekast.com';
 /** CNAME target for a Vercel-hosted domain — Vercel's edge resolves it (issue §6). */
 export const CNAME_VERCEL_TARGET = 'cname.vercel-dns.com';
 /**
- * Build the two interim domains for a slug (issue §4):
- *   - dev:  `{slug}-dev.timekast.mx`  → tracks the `develop` branch (preview)
- *   - prod: `{slug}.timekast.mx`      → production
+ * Build the two interim domains for a slug (issue §4), under the CURRENT
+ * {@link TIMEKAST_ZONE_NAME} — i.e. what a NEW project gets:
+ *   - dev:  `{slug}-dev.timekast.com`  → tracks the `develop` branch (preview)
+ *   - prod: `{slug}.timekast.com`      → production
+ *
+ * 🔴 Never call this to re-derive the domains of an ALREADY provisioned project:
+ * one born before DOM-001 lives on `timekast.mx` and this would hand back the
+ * wrong host. Read those from the provision state instead.
  *
  * Lives HERE (next to {@link TIMEKAST_ZONE_NAME}) so BOTH `provision.ts` (which
  * creates these) and `provision-state.ts` (whose `--destroy` target re-derives the
@@ -51,6 +68,37 @@ export function provisionDomains(slug) {
         prod: `${slug}.${TIMEKAST_ZONE_NAME}`,
     };
 }
+/**
+ * Every org zone a project may already live in, CURRENT FIRST (DOM-002).
+ *
+ * `timekast.mx` is not dead weight: it kept serving every project provisioned
+ * before the org moved to `.com`, so a rescue path that reconstructs a project's
+ * domains has to look there too. Ordered so the current zone always wins a tie —
+ * a name that somehow exists in both resolves to where new projects are born.
+ *
+ * A future move appends here; nothing else needs to learn about it.
+ */
+export const ORG_ZONE_NAMES = [TIMEKAST_ZONE_NAME, 'timekast.mx'];
+/**
+ * The interim domains of an ALREADY provisioned project — the counterpart of
+ * {@link provisionDomains}, which is for what is BORN now (DOM-001).
+ *
+ * Reads what the provision state recorded and only falls back to deriving from the
+ * CURRENT org zone when the state has nothing. That order is the whole point: a
+ * project provisioned before the org moved to `timekast.com` lives on
+ * `timekast.mx`, which stays live, so re-deriving its host from the slug would
+ * hand back a domain that never existed — and the caller would retire, tear down
+ * or gate a passkey on the wrong host, silently.
+ *
+ * The dev fallback follows the PROD domain's zone (not the current constant) so a
+ * state written before `devDomain` existed still resolves inside its own zone.
+ */
+export function existingProvisionDomains(slug, dns) {
+    const fallback = provisionDomains(slug);
+    const prod = dns?.domain ?? fallback.prod;
+    const dev = dns?.devDomain ?? `${slug}-dev.${apexZoneOf(prod)}`;
+    return { dev, prod };
+}
 /** Timeout (ms) for every Cloudflare REST call — a dead network must not hang provision. */
 const CLOUDFLARE_API_TIMEOUT_MS = 30_000;
 /** A non-2xx (or `success: false`) response from the Cloudflare REST API. */
@@ -126,10 +174,14 @@ async function cloudflareApi(method, pathname, token, deps, body, query) {
 /**
  * Resolve the zone id for {@link TIMEKAST_ZONE_NAME} via `GET /zones?name=`.
  *
- * The scoped shared org token can only see the `timekast.mx` zone, so the lookup
- * returns exactly that zone (or nothing). An empty result means the zone is not
- * visible to this token — either the token is out of scope or the zone id rotated
- * (issue §8). Either way it is a clear, actionable failure, never a silent skip.
+ * The scoped shared org token sees the org zones only, so the lookup returns
+ * exactly that zone (or nothing). An empty result means the zone is not visible to
+ * this token — either the token is out of scope or the zone id rotated (issue §8).
+ * Either way it is a clear, actionable failure, never a silent skip.
+ *
+ * Use ONLY for what is born now (the current org zone). For a domain that already
+ * exists, resolve its own zone with {@link resolveZoneIdForName} + {@link apexZoneOf}
+ * — a project provisioned before DOM-001 lives on `timekast.mx`, not here.
  *
  * @throws {CloudflareApiError} on any non-2xx / `success: false`.
  * @throws {CLIError} when the zone is not found with this token (issue §8).
@@ -139,8 +191,10 @@ export async function resolveZoneId(token, deps = {}) {
 }
 /**
  * Resolve the Cloudflare zone id for an ARBITRARY zone name via `GET /zones?name=`
- * (PROV-006). The interim flow targets `timekast.mx` ({@link resolveZoneId} is the
- * fixed-name shortcut); the client-domain flow targets the client's own apex zone,
+ * (PROV-006). The interim-CREATION flow targets the current org zone
+ * ({@link resolveZoneId} is the fixed-name shortcut), and the interim-RETIRE flow
+ * targets whichever org zone the existing domain belongs to (DOM-001 — it may be
+ * `timekast.mx`); the client-domain flow targets the client's own apex zone,
  * which may sit under the org token (`--dns=org`) or the client's own token
  * (`--dns=cliente-cf`). The zone name passed here is the registrable apex derived
  * from the client domain (`app.miapp.com` → `miapp.com`); a subdomain CNAME is
@@ -166,8 +220,12 @@ export async function resolveZoneIdForName(zoneName, token, deps = {}) {
  * Cloudflare zone is the apex (`miapp.com`); a CNAME for a subdomain
  * (`app.miapp.com`) lives INSIDE that zone, so the zone lookup must use the apex,
  * not the full host. This takes the LAST TWO labels (`a.b.miapp.com` → `miapp.com`).
- * Multi-part public suffixes (`co.uk`) are out of scope for the interim flow; the
- * `--dns=registrar` path sidesteps zone resolution entirely (manual records).
+ *
+ * ⚠️ A GUESS, and a wrong one under a multi-part public suffix: `app.miapp.com.mx`
+ * yields `com.mx`, which is nobody's zone. Prefer {@link resolveZoneIdForDomain},
+ * which asks Cloudflare instead of guessing (DOM-002). This stays exported because
+ * it is the right answer for a name already known to sit in a second-level zone
+ * (the org's own domains) and because it seeds the candidate list.
  */
 export function apexZoneOf(domain) {
     const labels = domain.split('.').filter(Boolean);
@@ -175,6 +233,56 @@ export function apexZoneOf(domain) {
         return labels.join('.');
     return labels.slice(-2).join('.');
 }
+/**
+ * The zone-name candidates for a domain, MOST SPECIFIC FIRST (DOM-002).
+ *
+ * `app.miapp.com.mx` → `['app.miapp.com.mx', 'miapp.com.mx', 'com.mx']`. Walking
+ * this order and keeping the first that EXISTS is what makes a `.com.mx` client
+ * resolve correctly without shipping a public-suffix list: the registry of what is
+ * a real zone is Cloudflare's, not a table we would have to keep current.
+ *
+ * Stops at two labels — a single label is never a zone anyone owns here.
+ */
+export function zoneCandidatesOf(domain) {
+    const labels = domain.split('.').filter(Boolean);
+    const candidates = [];
+    for (let i = 0; i <= labels.length - 2; i++) {
+        candidates.push(labels.slice(i).join('.'));
+    }
+    return candidates;
+}
+/**
+ * Resolve the Cloudflare zone id that actually CONTAINS `domain` (DOM-002), by
+ * trying {@link zoneCandidatesOf} most-specific-first and returning the first hit.
+ *
+ * Replaces `resolveZoneIdForName(apexZoneOf(domain))` wherever the domain is a
+ * client's and its shape is not known in advance. Costs one extra lookup only when
+ * the first guess misses, and the miss is exactly the case that used to fail:
+ * `app.miapp.com.mx` asks for `miapp.com.mx` before ever considering `com.mx`.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` that is not a
+ *   plain "not found" — a 403 must surface as an out-of-scope token, never be
+ *   swallowed as "try the next candidate".
+ * @throws {CLIError} when NO candidate is visible to this token.
+ */
+export async function resolveZoneIdForDomain(domain, token, deps = {}) {
+    const candidates = zoneCandidatesOf(domain);
+    for (const candidate of candidates) {
+        try {
+            return await resolveZoneIdForName(candidate, token, deps);
+        }
+        catch (error) {
+            // Only "this zone is not visible" is a reason to try the next candidate.
+            // An API-level failure (403 out-of-scope, 5xx) propagates untouched.
+            if (error instanceof CloudflareApiError)
+                throw error;
+        }
+    }
+    throw new CLIError(`No se encontró en Cloudflare ninguna zona que contenga \`${domain}\` con el token usado.\n` +
+        `Se probó: ${candidates.join(', ')}.\n` +
+        'Verifica que el token esté scopeado a la zona (DNS-edit) y reintenta con `--resume`; ' +
+        'si usas `--dns=cliente-cf`, confirma que la API key del cliente cubre esa zona.');
+}
 /**
  * Find an existing CNAME record for `name` in the zone (issue §8 idempotency).
  * Returns the record when present (so the caller can detect a `proxied: true`

package/dist/lib/constants.js

@@ -170,20 +170,20 @@ export const GENERATOR_SCRIPTS = [
     },
 ];
 /**
- * Kit-local E2E debugging aliases — raw Playwright, but through the wrapper that arms the
- * `server-only` / `client-only` compile-guard stub (`scripts/tools/e2e-direct.ts`).
+ * The RETIRED E2E debugging aliases, and the values the kit shipped for them.
  *
- * `pnpm test:e2e` gets the stub from `e2e-runner.ts`; these two used to shell `playwright
- * test` straight from `package.json` and therefore did not, so a spec that transitively
- * reached a server-guarded module died at load with `No tests found` — but only here, never
- * under the full runner.
+ * 🔴 NOTHING INSERTS THESE ANY MORE. They were the raw-Playwright entry points, last shipped
+ * as a wrapper that armed the `server-only` / `client-only` compile-guard stub
+ * (`scripts/tools/e2e-direct.ts`). Both the aliases and that wrapper were retired: they
+ * bypassed the E2E runner by design, which is what made them the visible path to running the
+ * suite against whatever database `.env.local` names. The kit no longer ships the file, so
+ * `kitLocalScripts` no longer offers the aliases — the insertion branch was removed rather
+ * than left dormant behind a gate that only opens in a derivative which kept its own copy of
+ * the wrapper (exactly the repo that most needed them gone).
  *
- * FILE-GATED, exactly like `GENERATOR_SCRIPTS`: the alias is only ensured when the wrapper
- * it shells actually exists in the repo, so a `core`/non-Factory derivative never receives a
- * script pointing at a file it lacks. Both gate on the SAME file (one wrapper, two entry
- * points — `--ui` is just an argument forwarded to Playwright). Insert-if-missing; a dev's
- * own value is never overwritten, and the previously-shipped raw commands self-heal through
- * `OBSOLETE_SCRIPT_CMDS` below.
+ * What these constants are FOR now: naming the values `RETIRED_SCRIPT_CMDS` matches when it
+ * deletes the entries from a derivative's `package.json`. `E2E_DIRECT_SCRIPT_FILE` survives
+ * as the file those commands shelled, which is what makes the commands themselves readable.
  */
 export const E2E_DIRECT_SCRIPT_FILE = 'scripts/tools/e2e-direct.ts';
 export const E2E_DIRECT_SCRIPT_NAME = 'test:e2e:direct';
@@ -258,10 +258,12 @@ export const OBSOLETE_SCRIPT_CMDS = {
     [GENERATE_REFERENCE_NAME]: [
         GENERATOR_SCRIPTS.map((g) => `node ${g.file.replace(/\.ts$/, '.mjs')}`).join(' && '),
     ],
-    // The raw Playwright invocations the kit shipped before `e2e-direct.ts` existed. They run,
-    // which is what makes them worth healing: they simply run WITHOUT the compile-guard stub,
-    // so the failure they produce is a spec reporting `No tests found` rather than an error a
-    // dev can act on. A derivative that pointed either alias somewhere of its own keeps it.
+    // The raw Playwright invocations the kit shipped before `e2e-direct.ts` existed. These two
+    // are NOT healed any more — their script is retired, not obsolete, so nothing offers them
+    // for insertion. They stay registered here because `RETIRED_SCRIPT_CMDS` reuses the list
+    // (rather than restating it) as "every value the kit ever shipped for this key", which is
+    // what the removal matches on. A derivative that pointed either alias somewhere of its own
+    // keeps it, there as here.
     [E2E_DIRECT_SCRIPT_NAME]: ['playwright test'],
     [E2E_UI_SCRIPT_NAME]: ['playwright test --ui'],
     // Every heap ceiling the kit shipped for the dev server before the current one. Listed as
@@ -269,3 +271,29 @@ export const OBSOLETE_SCRIPT_CMDS = {
     // appended a flag of its own, or picked a ceiling the kit never shipped, is left alone.
     [DEV_NEXT_SCRIPT_NAME]: DEV_NEXT_OBSOLETE_HEAPS_MB.map((mb) => `NODE_OPTIONS='--max-old-space-size=${mb}' next dev --turbopack`),
 };
+/**
+ * Update-time RETIREMENT registry: kit-owned scripts the kit no longer ships at all, and every
+ * value it ever shipped for them. `removeRetiredScripts` deletes the entry when the value on
+ * disk is one of these, and leaves it alone when it is not.
+ *
+ * The distinction from `OBSOLETE_SCRIPT_CMDS` above is the destination, not the discipline:
+ * obsolete = the script still exists, its invocation changed → HEAL to the current command;
+ * retired = the script is gone → REMOVE the entry, because the file it shells was deleted from
+ * the kit and the alias would be dangling on arrival.
+ *
+ * `test:e2e:direct` / `test:e2e:ui` were the raw-Playwright debugging entry points. They bypass
+ * the E2E runner by design, which is exactly what made them the visible path to running the
+ * suite against whatever database `.env.local` names — the failure this retirement is part of
+ * closing. The values listed are the wrapper command the kit shipped last PLUS the historic raw
+ * ones already registered above (reused, not restated: in the measured fleet 6 of 8 repos carry
+ * the raw form and only one the wrapper, so matching only the current value would leave the more
+ * dangerous shape in place almost everywhere). Anything else in that key is the dev's own and is
+ * preserved — same rule as everywhere else in this file.
+ */
+export const RETIRED_SCRIPT_CMDS = {
+    [E2E_DIRECT_SCRIPT_NAME]: [
+        E2E_DIRECT_SCRIPT_CMD,
+        ...(OBSOLETE_SCRIPT_CMDS[E2E_DIRECT_SCRIPT_NAME] ?? []),
+    ],
+    [E2E_UI_SCRIPT_NAME]: [E2E_UI_SCRIPT_CMD, ...(OBSOLETE_SCRIPT_CMDS[E2E_UI_SCRIPT_NAME] ?? [])],
+};

package/dist/lib/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, E2E_DIRECT_SCRIPT_CMD, E2E_DIRECT_SCRIPT_FILE, E2E_DIRECT_SCRIPT_NAME, E2E_UI_SCRIPT_CMD, E2E_UI_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -63,14 +63,19 @@ export function parsePackageJson(raw) {
  * each if missing and NEVER overwriting a divergent value (§7.4). Shared by
  * `applyPackageJsonEdits` (the `new` flow) and `insertFactoryUpdateScript`
  * (the `update` flow). Returns whether anything changed (so the caller writes
- * only on a real edit) + the result for the primary `factory:update` script
- * (which drives the install messaging).
+ * only on a real edit), the result for the primary `factory:update` script
+ * (which drives the install messaging), and the per-script detail.
+ *
+ * The per-script results were computed here all along and then dropped on the floor at the end
+ * of each loop turn — only `factory:update` survived. Keeping them is what lets `update` name
+ * the aliases it put back instead of moving a dev's `package.json` in silence (`BND-004`).
  */
 function ensureFactoryScripts(pkg, extraScripts = {}) {
     const scripts = pkg.scripts ?? {};
     pkg.scripts = scripts;
     let changed = false;
     let primary = { action: 'already-correct' };
+    const perScript = {};
     for (const [name, cmd] of Object.entries({ ...FACTORY_SCRIPTS, ...extraScripts })) {
         const existing = scripts[name];
         let result;
@@ -93,10 +98,11 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
         else {
             result = { action: 'conflict', existingValue: existing };
         }
+        perScript[name] = result;
         if (name === UPDATE_SCRIPT_NAME)
             primary = result;
     }
-    return { changed, primary };
+    return { changed, primary, perScript };
 }
 /**
  * The kit-local scripts to ensure for THIS repo, each file-gated so a
@@ -110,14 +116,22 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
  *   tracked set on `update`/`beta`, so an existing derivative self-heals the
  *   aliases without the dev hand-editing `package.json`.
  * - `generate:reference` — the aggregate that runs the whole set in one command.
- * - `test:e2e:direct` / `test:e2e:ui` — the two raw-Playwright debugging entry
- *   points, routed through the wrapper that arms the compile-guard stub. Both
- *   gate on that one wrapper file.
  * - `dev:next` — the dev server the launcher shells, whose heap ceiling the kit
  *   owns. Gated on the launcher (`dev.mjs`), which is what invokes it.
  *
  * Insert-if-missing for all: a dev's own value for any of these is never
  * overwritten (see `ensureFactoryScripts`).
+ *
+ * 🔴 WHAT IS DELIBERATELY NOT HERE: `test:e2e:direct` / `test:e2e:ui`. They used to be
+ * inserted from this function, file-gated on `scripts/tools/e2e-direct.ts` — a file the kit
+ * NO LONGER SHIPS. The gate was therefore shut everywhere except in a derivative that kept
+ * an edited copy of the wrapper, which is precisely the repo where the two runner bypasses
+ * had to go: `maintainKitScripts` inserted them and `removeRetiredScripts` took them away
+ * again inside the same pass. Insertion for a deleted file is not a dormant branch, it is a
+ * live one aimed at nothing, so it is gone. THE RETIREMENT STAYS: `RETIRED_SCRIPT_CMDS` (and
+ * the `OBSOLETE_SCRIPT_CMDS` entries it reuses) is what removes those aliases from the
+ * derivatives that still carry them in their `package.json`, and it decides from the VALUE,
+ * never from a file gate.
  */
 export function kitLocalScripts(rootDir) {
     const has = (relPath) => existsSync(path.join(rootDir, relPath));
@@ -132,10 +146,6 @@ export function kitLocalScripts(rootDir) {
     }
     if (has(GENERATE_REFERENCE_GATE_FILE))
         scripts[GENERATE_REFERENCE_NAME] = GENERATE_REFERENCE_CMD;
-    if (has(E2E_DIRECT_SCRIPT_FILE)) {
-        scripts[E2E_DIRECT_SCRIPT_NAME] = E2E_DIRECT_SCRIPT_CMD;
-        scripts[E2E_UI_SCRIPT_NAME] = E2E_UI_SCRIPT_CMD;
-    }
     if (has(DEV_NEXT_GATE_FILE))
         scripts[DEV_NEXT_SCRIPT_NAME] = DEV_NEXT_SCRIPT_CMD;
     return scripts;
@@ -196,17 +206,18 @@ export function applyPackageJsonEdits(raw, name, extraScripts = {}) {
  * present (correct or divergent) the file is left byte-identical.
  *
  * @param pkgPath Absolute path to the derived project's `package.json`.
- * @returns The result for the primary `factory:update` script (+ existing value on conflict).
+ * @returns The result for the primary `factory:update` script (+ existing value on conflict),
+ *          widened with `perScript` — what happened to every other alias in the same pass.
  */
 export function insertFactoryUpdateScript(pkgPath) {
     const raw = readFileSync(pkgPath, 'utf8');
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
-    const { changed, primary } = ensureFactoryScripts(pkg, kitLocalScripts(path.dirname(pkgPath)));
+    const { changed, primary, perScript } = ensureFactoryScripts(pkg, kitLocalScripts(path.dirname(pkgPath)));
     if (changed) {
         writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
     }
-    return primary;
+    return { ...primary, perScript };
 }
 /**
  * Retire the E2E port the kit used to ship in a derivative's `package.json`: KEEP the key,
@@ -266,6 +277,116 @@ export function emptyShippedE2EPort(pkgPath) {
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
     return 'emptied';
 }
+/**
+ * Retire the kit-owned scripts the kit no longer ships (`RETIRED_SCRIPT_CMDS`) from a
+ * derivative's `package.json`: REMOVE the entry outright when its value is one the kit shipped,
+ * leave it untouched when it is not.
+ *
+ * WHY REMOVE RATHER THAN EMPTY. This is the deliberate contrast with `emptyShippedE2EPort`
+ * below, whose docstring argues for keeping the key: there, `"e2e": null` is a SIGNAL the runner
+ * reads, so the key is the contract and only the value retires. Here nothing reads the key — the
+ * script's whole purpose was to shell a file that no longer exists — so an emptied entry would
+ * be an alias that fails on invocation instead of one that is honestly gone. Same discipline
+ * (exact match, kit values only, idempotent), different mechanism.
+ *
+ * WHY IT IS NOT FILE-GATED. `kitLocalScripts` gates the INSERTION of these aliases on
+ * `scripts/tools/e2e-direct.ts` being present, and `update` deletes that file before it reaches
+ * this code — so a gate here would be false exactly when the removal is needed, and the primitive
+ * would never fire on anyone. It runs unconditionally and decides from the VALUE alone.
+ *
+ * WHY IT RETURNS THE DETAIL. A dev who used one of these daily must be told it went, and by
+ * name. This function only produces the fact; wiring it into the update's closing summary is
+ * `BND-004`'s job. Being born with the right return shape is what keeps that from being a
+ * second edit to this function — the defect `ensureFactoryScripts` has today, where the per-key
+ * result is computed and then thrown away.
+ *
+ * Surgical like the rest of this module: reads, deletes only those keys, re-serializes with the
+ * original indentation + trailing newline, and writes ONLY when something was actually removed.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ * @returns What happened to each retired key — the input `BND-004` reports from.
+ */
+export function removeRetiredScripts(pkgPath) {
+    const raw = readFileSync(pkgPath, 'utf8');
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    const scripts = pkg.scripts;
+    const report = {};
+    // No `scripts` block at all (a non-Node-ish package.json): nothing to retire, nothing written.
+    if (!scripts) {
+        for (const name of Object.keys(RETIRED_SCRIPT_CMDS))
+            report[name] = 'absent';
+        return report;
+    }
+    let changed = false;
+    for (const [name, shippedValues] of Object.entries(RETIRED_SCRIPT_CMDS)) {
+        const existing = scripts[name];
+        if (existing === undefined) {
+            report[name] = 'absent';
+        }
+        else if (shippedValues.includes(existing)) {
+            delete scripts[name];
+            changed = true;
+            report[name] = 'removed';
+        }
+        else {
+            report[name] = 'preserved';
+        }
+    }
+    if (changed) {
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    }
+    return report;
+}
+/**
+ * The kit-owned maintenance of a derivative's `package.json`, in the ONE order that is correct.
+ *
+ * 🔴 WHY THIS IS A SHARED FUNCTION AND NOT A SEQUENCE OF CALLS AT EACH SITE. `update` and `add`
+ * both perform this maintenance on a repo that already exists, and `add` only replicated half of
+ * it: it inserted the aliases and emptied the port, and never retired anything. In a legacy repo
+ * that adopts the brain with `factory add` while `scripts/tools/e2e-direct.ts` is still on disk,
+ * `kitLocalScripts` opens its file gate and WRITES `test:e2e:direct` / `test:e2e:ui` — the two
+ * aliases that bypass the E2E runner, reinstalled by the very tool that came to retire them. The
+ * comment at that call site said "same maintenance `update` does"; the code did not, and nothing
+ * could tell. A third caller tomorrow would diverge the same way.
+ *
+ * ORDER MATTERS — the retirement runs AFTER the insertion, and it is the cheap half of the
+ * invariant. `kitLocalScripts` no longer knows how to insert the retired aliases at all (its
+ * docstring says why), so today no key can be added and removed in one pass; keeping the
+ * retirement last is what makes that stay true if a future retired script is also insertable —
+ * retiring first would let the insertion put it straight back.
+ *
+ * RECONCILED BEFORE RETURNING, so a caller's summary cannot contradict itself when a key IS both
+ * inserted and removed in the same run:
+ *   · added → removed                 : never existed for the dev, still does not → report NEITHER.
+ *   · healed/already-correct → removed: they had it, now it is gone              → report RETIRED.
+ *   · inserted and not removed        :                                          → report INSERTED.
+ *
+ * (The first line is unreachable with the CURRENT registries — nothing is both insertable and
+ * retired — which is the point: it is the reconciliation that keeps the two directions from ever
+ * contradicting each other, not a branch anybody is expected to hit today.)
+ *
+ * Every primitive it calls re-reads the file, so each step sees what the previous one wrote.
+ * Throws what they throw (a `CLIError` on invalid JSON) — the caller decides how tolerant to be.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ */
+export function maintainKitScripts(pkgPath) {
+    const insert = insertFactoryUpdateScript(pkgPath);
+    const retiredReport = removeRetiredScripts(pkgPath);
+    // Retire the E2E port the kit used to ship (`ports.e2e: 3006`) so the runner that arrives via
+    // `scripts/**` can derive one per checkout. Conditional: it only ever touches that exact
+    // value, so a dev-chosen port survives untouched.
+    const portAction = emptyShippedE2EPort(pkgPath);
+    const removedKeys = new Set(Object.entries(retiredReport)
+        .filter(([, action]) => action === 'removed')
+        .map(([name]) => name));
+    const inserted = Object.entries(insert.perScript)
+        .filter(([name, r]) => (r.action === 'added' || r.action === 'healed') && !removedKeys.has(name))
+        .map(([name]) => name);
+    const retired = [...removedKeys].filter((name) => insert.perScript[name]?.action !== 'added');
+    return { insert, retiredReport, portAction, inserted, retired };
+}
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the
  * installed brain version, mirroring the lockfile's `version`. The Factory's own

package/dist/lib/provision-state.js

@@ -34,7 +34,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { provisionDomains } from './cloudflare-api.js';
+import { existingProvisionDomains } from './cloudflare-api.js';
 import { TIMEKAST_DIR } from './constants.js';
 /**
  * Directory (repo-root relative) the provision state lives in. This is the SAME
@@ -367,14 +367,16 @@ export function readDestroyTarget(rootDir) {
             'Bórralo o reconstrúyelo con `--adopt`.');
     }
     const lifecycle = step.lifecycle === 'ephemeral' ? 'ephemeral' : 'live';
-    // The `dns` block now records the interim DEV domain (`{slug}-dev.timekast.mx`)
-    // alongside prod, but it stays derivable from the slug. Prefer the persisted value
-    // and fall back to deriving it (state files written before `devDomain` existed) so
-    // `--destroy` tears down the dev CNAME instead of orphaning it. Gated on `dns` being
-    // present (no DNS step → no dev domain to remove); passed through the same
-    // `realDomain` shape guard as every other low-trust domain field.
+    // The `dns` block now records the interim DEV domain (`{slug}-dev.<org zone>`)
+    // alongside prod, but it stays derivable. Prefer the persisted value and fall back
+    // to deriving it (state files written before `devDomain` existed) so `--destroy`
+    // tears down the dev CNAME instead of orphaning it. The fallback derives inside the
+    // PROD domain's own zone (`existingProvisionDomains`, DOM-001) — a project born
+    // before the org moved to `timekast.com` must not have a `.com` dev host invented
+    // for it. Gated on `dns` being present (no DNS step → no dev domain to remove);
+    // passed through the same `realDomain` shape guard as every other low-trust field.
     const devDomain = step.dns
-        ? realDomain(step.dns.devDomain ?? provisionDomains(step.projectName).dev)
+        ? realDomain(existingProvisionDomains(step.projectName, step.dns).dev)
         : null;
     const domains = [
         realDomain(step.dns?.domain),

package/package.json

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