@timekast/factory 2.3.1 → 2.5.0

package/dist/lib/usage-scan.js

@@ -0,0 +1,516 @@
+/**
+ * usage-scan — engine of `factory usage`: reads REAL `usage` from the Claude Code
+ * transcripts under a projects root (default `~/.claude/projects/`) and aggregates
+ * the cuts the report renders. Graduated from `project/reports/model-usage.mjs`
+ * (the Factory-internal prototype) into a tool any developer can run in any repo.
+ *
+ * Design constraints (Encargo C brief, 2026-08-26):
+ *   · FULL sweep — discovers every project dir under the root by itself. ZERO
+ *     hardcoded repo maps (the prototype's `REPOS` map is exactly the defect
+ *     this module removes: its figures under-counted every unlisted repo).
+ *   · No repo preflight — the data source is the developer's HOME, not the cwd.
+ *   · Node builtins only. The CLI cannot assume anything about the host repo.
+ *   · Privacy: only aggregates leave this module — dates, counts, tokens, model
+ *     and agent names, repo slugs. NEVER message content, NEVER client file
+ *     paths, NEVER code fragments. (The repo slug itself identifies the client:
+ *     `anonymizeRepos` exists so a SHARED report can drop even that — opt-in,
+ *     the developer's call, never the default.)
+ *
+ * Three traps of this format — all three paid for once in the prototype, all
+ * three fixed here and pinned by tests (`cli/tests/unit/usage-scan.test.ts`):
+ *
+ * 🔴 `toolUseResult.totalTokens` is NOT the invocation total — it reports ~1% of
+ *    the real figure. Never read. Tokens always come from the transcript `usage`.
+ *
+ * 🔴 Collecting invocations from the PARENT transcript loses most of them: the
+ *    `toolUseResult` record survives for a minority (measured: 19 of 128 in a
+ *    one-day window). The subagents directory is the PRIMARY source; the parent
+ *    record only ENRICHES (lines written, authoritative agentType, duration).
+ *
+ * 🔴 The `ctx_final × tool_calls × K` estimator was RETIRED and must not return:
+ *    it inflated ~3×, non-uniformly (2.4×-4.4× depending on tool-call count), so
+ *    the bias did not cancel when comparing two models either.
+ *
+ * Plus the fine print: dedup by `msg.id|requestId` (one turn persists across
+ * several streamed lines) — but `tool_use` blocks are counted BEFORE the dedup,
+ * because the streamed lines do not repeat them (measured: 29 real tool-calls
+ * vs 3 survivors if deduped).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Agents whose output is judgment, not code: `adds/dels` are 0 by definition, so
+ * they are measured per verdict (tokens/invocation) and per review ROUND
+ * (re-spawn of the same reviewer in the same session). For an executor a
+ * re-spawn is the next batch of work, not a retry — reading it as a round is an
+ * interpretation error. Agent-name based (kit-known reviewers); foreign agent
+ * types simply do not appear in the rounds tables.
+ */
+export const REVIEWER_AGENTS = new Set([
+    'quality-engineer',
+    'architect',
+    'security-auditor',
+    'ui-critic',
+    'product-owner',
+    'project-planner',
+    'skeptical-client',
+    'fx-factory-reviewer',
+]);
+/** Stall threshold: minutes per tool-call above which the run measured a hung command. */
+const STALL_MIN_PER_TOOL = 5;
+/** A stalled invocation measured the hung command, not the model. */
+export const isStall = (r) => r.tools >= 5 && r.ms / 60000 / Math.max(r.tools, 1) > STALL_MIN_PER_TOOL;
+/**
+ * Eligible for the tokens-per-delivered-line table: only what WRITES code.
+ * Needs the parent's `toolUseResult` (source of `toolStats`). NOT the same as
+ * `isStall`: a reviewer has 0 lines by definition and is not stalled — mixing
+ * the two (as the prototype once did) dropped the whole review panel.
+ */
+export const writesCode = (r) => r.enriched && r.adds + r.dels > 0 && !isStall(r);
+/**
+ * ISO timestamp → LOCAL calendar day `YYYY-MM-DD`. The window is resolved in
+ * local time (`resolveWindow`), so each request must be dated the same way:
+ * slicing the UTC string would push every evening request (UTC-6 → after
+ * 18:00) into the next day and the last night of a month into the next month.
+ * Returns '' for an unparseable timestamp (the caller skips it).
+ */
+export const localDay = (ts) => {
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime()))
+        return '';
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
+/** Normalize a model id for display: `claude-opus-5[1m]` → `opus-5`. */
+const shortModel = (m) => (m ?? '?').replace('[1m]', '').replace('claude-', '');
+/** Sum the four real usage buckets of one `usage` object. */
+const usageTotal = (u) => (u.input_tokens ?? 0) +
+    (u.cache_creation_input_tokens ?? 0) +
+    (u.cache_read_input_tokens ?? 0) +
+    (u.output_tokens ?? 0);
+/**
+ * Cheap file pre-filter: a `.jsonl` whose last write predates the window start
+ * (with a day of slack) cannot contain in-window timestamps — appends bump
+ * mtime. Purely an optimization; correctness never depends on it.
+ */
+const mtimeBeforeWindow = (file, since) => {
+    try {
+        return statSync(file).mtimeMs < Date.parse(`${since}T00:00:00Z`) - 86_400_000;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Resolve per-slug display names from the `cwd` each transcript line carries —
+ * the slug encodes the path with `-` separators AND the segments themselves
+ * contain hyphens, so decoding the slug is ambiguous by construction; the
+ * `cwd` basename is the project's real name. Collisions qualify with parent
+ * path segments (up to 2); a slug with no observed `cwd` (or an unresolvable
+ * collision) keeps the full slug — ugly but honest, never a guess.
+ */
+function resolveRepoNames(slugs, cwdBySlug) {
+    const segs = (p) => p.split(/[\\/]/).filter(Boolean);
+    const candidate = (slug, depth) => {
+        const cwd = cwdBySlug.get(slug);
+        if (!cwd)
+            return null;
+        const s = segs(cwd);
+        return s.slice(Math.max(0, s.length - 1 - depth)).join('/');
+    };
+    const out = new Map();
+    let pending = slugs;
+    for (let depth = 0; depth <= 2 && pending.length; depth++) {
+        const byName = new Map();
+        const unresolvable = [];
+        for (const s of pending) {
+            const n = candidate(s, depth);
+            if (n === null)
+                unresolvable.push(s);
+            else
+                byName.set(n, [...(byName.get(n) ?? []), s]);
+        }
+        const next = [];
+        for (const [n, group] of byName) {
+            if (group.length === 1)
+                out.set(group[0], n);
+            else
+                next.push(...group);
+        }
+        for (const s of unresolvable)
+            out.set(s, s);
+        pending = next;
+    }
+    for (const s of pending)
+        out.set(s, s);
+    return out;
+}
+/**
+ * Index one project dir's subagent transcripts by `agentId`. They live in
+ * `<dir>/<session>/subagents/agent-<id>.jsonl` (+ `agent-<id>.meta.json` for
+ * the `agentType` — the transcript itself does not carry it). This is the
+ * PRIMARY invocation source (trap 2).
+ */
+function indexSubagents(dir, slug, window, cwdSample) {
+    const byId = new Map();
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const subs = join(dir, entry.name, 'subagents');
+        if (!existsSync(subs))
+            continue;
+        for (const f of readdirSync(subs)) {
+            const m = /^agent-(.+)\.jsonl$/.exec(f);
+            if (!m)
+                continue;
+            const file = join(subs, f);
+            if (mtimeBeforeWindow(file, window.since))
+                continue;
+            let agentType = null;
+            const metaFile = join(subs, `agent-${m[1]}.meta.json`);
+            if (existsSync(metaFile)) {
+                try {
+                    const meta = JSON.parse(readFileSync(metaFile, 'utf8'));
+                    agentType = meta.agentType ?? null;
+                }
+                catch {
+                    /* unreadable meta: the invocation still counts, without an agent name */
+                }
+            }
+            let tokens = 0;
+            let model = null;
+            let first = null;
+            let last = null;
+            let tools = 0;
+            let ctx = 0;
+            const seen = new Set();
+            let content;
+            try {
+                content = readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const line of content.split('\n')) {
+                if (!line.trim())
+                    continue;
+                let o;
+                try {
+                    o = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const ts = typeof o.timestamp === 'string' ? o.timestamp : null;
+                if (ts) {
+                    if (!first || ts < first)
+                        first = ts;
+                    if (!last || ts > last)
+                        last = ts;
+                }
+                if (!cwdSample.value && typeof o.cwd === 'string' && o.cwd)
+                    cwdSample.value = o.cwd;
+                if (o.type !== 'assistant')
+                    continue;
+                const msg = (o.message ?? {});
+                // 🔴 tool_use blocks are counted BEFORE the per-request dedup. The dedup
+                // exists so a turn streamed across several lines is not double-billed —
+                // but its tool_use blocks do NOT repeat across those lines: deduping
+                // them erased real calls (measured: 29 real vs 3 survivors), validated
+                // against the user-side tool_result count, which matched exactly.
+                if (Array.isArray(msg.content)) {
+                    tools += msg.content.filter((c) => c?.type === 'tool_use').length;
+                }
+                const u = msg.usage;
+                if (!u)
+                    continue;
+                const key = `${msg.id}|${String(o.requestId)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                model ??= shortModel(msg.model);
+                tokens += usageTotal(u);
+                // Context comes from the invocation's OWN transcript, so it never
+                // depends on the parent having kept its `toolUseResult`.
+                ctx = Math.max(ctx, (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0));
+            }
+            if (!first)
+                continue; // empty or unreadable file
+            byId.set(m[1], {
+                repo: slug, // display name resolved post-sweep (cwd basename)
+                slug,
+                date: localDay(first),
+                session: entry.name,
+                agent: agentType ?? '(sin meta)',
+                model: model ?? '?',
+                tokens,
+                ms: last && first ? Date.parse(last) - Date.parse(first) : 0,
+                tools,
+                ctx,
+                adds: 0,
+                dels: 0,
+                enriched: false,
+            });
+        }
+    }
+    return byId;
+}
+/**
+ * Sweep every project dir under `root` and return main-loop aggregates + the
+ * subagent invocation list, both windowed. `root` is a parameter (tests point
+ * it at a synthetic fixture tree); the command passes `~/.claude/projects`.
+ */
+export function scanUsage(root, window) {
+    const invocations = [];
+    const mainAgg = new Map();
+    let reposScanned = 0;
+    if (!existsSync(root))
+        return { main: [], invocations: [], reposScanned: 0 };
+    const slugs = readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    const cwdBySlug = new Map();
+    for (const slug of slugs) {
+        const dir = join(root, slug);
+        const repo = slug; // display name resolved post-sweep (cwd basename)
+        reposScanned++;
+        const cwdSample = { value: null };
+        const subs = indexSubagents(dir, slug, window, cwdSample);
+        // Dedup spans every main-loop transcript of the slug, not one file: a
+        // resumed or forked session re-persists earlier turns under the same
+        // `id|requestId` in its new file (measured ~1.1% of keys), which a
+        // per-file set would bill twice.
+        const seen = new Set();
+        for (const f of readdirSync(dir).filter((x) => x.endsWith('.jsonl'))) {
+            const file = join(dir, f);
+            if (mtimeBeforeWindow(file, window.since))
+                continue;
+            let content;
+            try {
+                content = readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const line of content.split('\n')) {
+                // Only two line families matter here; skip the rest before JSON.parse.
+                if (!line.includes('"usage"') && !line.includes('"agentType"'))
+                    continue;
+                let o;
+                try {
+                    o = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (!cwdSample.value && typeof o.cwd === 'string' && o.cwd)
+                    cwdSample.value = o.cwd;
+                const date = typeof o.timestamp === 'string' ? localDay(o.timestamp) : '';
+                if (!date || date < window.since || date > window.until)
+                    continue;
+                // The parent's `toolUseResult` ENRICHES the already-indexed invocation —
+                // it contributes what the subagent transcript does not carry: toolStats
+                // (lines written), authoritative agentType, wall-clock duration. It
+                // NEVER creates the invocation (trap 2), and its `totalTokens` field is
+                // NEVER read (trap 1 — it reports ~1% of the real total).
+                const t = o.toolUseResult;
+                if (t && typeof t === 'object' && t.agentType && t.agentId) {
+                    const rec = subs.get(t.agentId);
+                    if (rec) {
+                        rec.agent = t.agentType; // meta may be missing; this is authoritative
+                        rec.adds = t.toolStats?.linesAdded ?? 0;
+                        rec.dels = t.toolStats?.linesRemoved ?? 0;
+                        if (t.totalDurationMs)
+                            rec.ms = t.totalDurationMs;
+                        rec.enriched = true;
+                        // 🔴 `tools` and `ctx` are NOT overwritten: they already come from
+                        // the invocation's own transcript for EVERY invocation. Taking them
+                        // from here only for the enriched minority would mix two sources in
+                        // one column and make rows incomparable.
+                    }
+                }
+                if (o.type !== 'assistant')
+                    continue;
+                const msg = (o.message ?? {});
+                const u = msg.usage;
+                if (!u)
+                    continue;
+                const key = `${msg.id}|${String(o.requestId)}`; // one turn persists across lines
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const model = shortModel(msg.model);
+                const aggKey = `${slug}|${date}|${model}`;
+                const agg = mainAgg.get(aggKey) ?? { repo, slug, date, model, tokens: 0, requests: 0 };
+                agg.tokens += usageTotal(u);
+                agg.requests++;
+                mainAgg.set(aggKey, agg);
+            }
+        }
+        for (const rec of subs.values()) {
+            if (rec.date >= window.since && rec.date <= window.until)
+                invocations.push(rec);
+        }
+        if (cwdSample.value)
+            cwdBySlug.set(slug, cwdSample.value);
+    }
+    // Post-sweep: resolve display names from the observed cwd basenames and
+    // stamp them on every row (the sweep kept the slug as a placeholder).
+    const names = resolveRepoNames(slugs, cwdBySlug);
+    for (const r of invocations)
+        r.repo = names.get(r.slug) ?? r.slug;
+    const main = [...mainAgg.values()].map((r) => ({ ...r, repo: names.get(r.slug) ?? r.slug }));
+    return { main, invocations, reposScanned };
+}
+const byTokensDesc = (a, b) => b.tokens - a.tokens;
+/** Aggregate a scan into the report the renderer and `--json` consume. */
+export function aggregateUsage(scan, window, opts = {}) {
+    const repoFilter = opts.repo ?? null;
+    const agentFilter = opts.agent ?? null;
+    const mainRows = repoFilter
+        ? scan.main.filter((r) => r.repo.includes(repoFilter) || r.slug.includes(repoFilter))
+        : scan.main;
+    let subRows = repoFilter
+        ? scan.invocations.filter((r) => r.repo.includes(repoFilter) || r.slug.includes(repoFilter))
+        : scan.invocations;
+    if (agentFilter)
+        subRows = subRows.filter((r) => r.agent === agentFilter);
+    const dayMap = new Map();
+    const modelMap = new Map();
+    const repoMap = new Map();
+    const agentMap = new Map();
+    let mainTok = 0;
+    let mainRequests = 0;
+    for (const r of mainRows) {
+        mainTok += r.tokens;
+        mainRequests += r.requests;
+        const d = dayMap.get(r.date) ?? { main: 0, sub: 0 };
+        d.main += r.tokens;
+        dayMap.set(r.date, d);
+        const m = modelMap.get(r.model) ?? { main: 0, sub: 0 };
+        m.main += r.tokens;
+        modelMap.set(r.model, m);
+        const p = repoMap.get(r.repo) ?? { main: 0, sub: 0 };
+        p.main += r.tokens;
+        repoMap.set(r.repo, p);
+    }
+    let subTok = 0;
+    let unenriched = 0;
+    for (const r of subRows) {
+        subTok += r.tokens;
+        if (!r.enriched)
+            unenriched++;
+        const d = dayMap.get(r.date) ?? { main: 0, sub: 0 };
+        d.sub += r.tokens;
+        dayMap.set(r.date, d);
+        const m = modelMap.get(r.model) ?? { main: 0, sub: 0 };
+        m.sub += r.tokens;
+        modelMap.set(r.model, m);
+        const p = repoMap.get(r.repo) ?? { main: 0, sub: 0 };
+        p.sub += r.tokens;
+        repoMap.set(r.repo, p);
+        const a = agentMap.get(r.agent) ?? { invocations: 0, tokens: 0 };
+        a.invocations++;
+        a.tokens += r.tokens;
+        agentMap.set(r.agent, a);
+    }
+    // Tokens per delivered unit (writes-code agents only; stalls excluded).
+    const workMap = new Map();
+    for (const r of subRows) {
+        if (!writesCode(r))
+            continue;
+        const k = `${r.agent}|${r.model}`;
+        const v = workMap.get(k) ?? { invocations: 0, tokens: 0, lines: 0, tools: 0, minutes: 0 };
+        v.invocations++;
+        v.tokens += r.tokens;
+        v.lines += r.adds + r.dels;
+        v.tools += r.tools;
+        v.minutes += r.ms / 60000;
+        workMap.set(k, v);
+    }
+    // Reviewer cost per verdict + rounds per session.
+    const reviewMap = new Map();
+    const roundsMap = new Map();
+    for (const r of subRows) {
+        if (!REVIEWER_AGENTS.has(r.agent))
+            continue;
+        const k = `${r.agent}|${r.model}`;
+        const v = reviewMap.get(k) ?? { invocations: 0, tokens: 0, minutes: 0, tools: 0, ctx: 0 };
+        v.invocations++;
+        v.tokens += r.tokens;
+        v.minutes += r.ms / 60000;
+        v.tools += r.tools;
+        v.ctx += r.ctx;
+        reviewMap.set(k, v);
+        const rk = `${r.slug}|${r.session}|${r.agent}`;
+        roundsMap.set(rk, (roundsMap.get(rk) ?? 0) + 1);
+    }
+    const roundsByAgent = new Map();
+    for (const [k, n] of roundsMap) {
+        const agent = k.split('|').at(-1) ?? '?';
+        const v = roundsByAgent.get(agent) ?? { sessions: 0, spawns: 0 };
+        v.sessions++;
+        v.spawns += n;
+        roundsByAgent.set(agent, v);
+    }
+    let byRepo = [...repoMap.entries()]
+        .map(([repo, v]) => ({ repo, main: v.main, sub: v.sub, tokens: v.main + v.sub }))
+        .sort(byTokensDesc);
+    if (opts.anon) {
+        byRepo = byRepo.map((r, i) => ({ ...r, repo: `repo-${String(i + 1).padStart(2, '0')}` }));
+    }
+    return {
+        version: 1,
+        window,
+        // Under --anon the repo filter is masked too: echoing the substring the
+        // user typed would put the client's name back next to `repo-01`.
+        filters: {
+            repo: opts.anon && repoFilter ? '(oculto)' : repoFilter,
+            agent: agentFilter,
+            anon: Boolean(opts.anon),
+        },
+        totals: {
+            main: mainTok,
+            sub: subTok,
+            total: mainTok + subTok,
+            mainRequests,
+            invocations: subRows.length,
+            unenriched,
+            agentTypes: agentMap.size,
+            reposScanned: scan.reposScanned,
+        },
+        byDay: [...dayMap.entries()]
+            .map(([date, v]) => ({ date, main: v.main, sub: v.sub }))
+            .sort((a, b) => (a.date < b.date ? -1 : 1)),
+        byModel: [...modelMap.entries()]
+            .map(([model, v]) => ({ model, main: v.main, sub: v.sub, tokens: v.main + v.sub }))
+            .filter((m) => m.tokens > 0) // e.g. `<synthetic>` rows: requests with zero usage
+            .sort(byTokensDesc),
+        byRepo,
+        byAgent: [...agentMap.entries()]
+            .map(([agent, v]) => ({ agent, invocations: v.invocations, tokens: v.tokens }))
+            .sort(byTokensDesc),
+        delivered: [...workMap.entries()]
+            .map(([k, v]) => {
+            const [agent, model] = k.split('|');
+            return { agent, model, ...v };
+        })
+            .sort(byTokensDesc),
+        reviewCost: [...reviewMap.entries()]
+            .map(([k, v]) => {
+            const [agent, model] = k.split('|');
+            return {
+                agent,
+                model,
+                invocations: v.invocations,
+                tokens: v.tokens,
+                minutes: v.minutes,
+                tools: v.tools,
+                avgCtx: v.invocations ? Math.round(v.ctx / v.invocations) : 0,
+            };
+        })
+            .sort(byTokensDesc),
+        reviewRounds: [...roundsByAgent.entries()]
+            .map(([agent, v]) => ({ agent, sessions: v.sessions, spawns: v.spawns }))
+            .sort((a, b) => b.spawns - a.spawns),
+    };
+}

package/dist/lib/vault-adopt.js

@@ -63,9 +63,13 @@ export const RETIRED_RAIL_KEYS = [
     'BACKLOG_ADMIN_TOKEN',
     'PROPOSAL_ASSETS_R2_TOKEN',
     'NEON_ORG',
+    // Direct-operation rail tokens: no kit command reads them, and they are still never a project's.
+    'ELEVENLABS_API_KEY',
+    'AWS_BILLING_ACCESS_KEY_ID',
+    'AWS_BILLING_SECRET_ACCESS_KEY',
 ];
-/** Rail families by prefix (`CLOUDFLARE_*`, `GAMMA_*`) — same list, for the names §5 groups. */
-const RAIL_KEY_PREFIXES = ['CLOUDFLARE_', 'GAMMA_'];
+/** Rail families by prefix (`CLOUDFLARE_*`, `GAMMA_*`, `APP_STORE_CONNECT_*`) — same list, for the names §5 groups. */
+const RAIL_KEY_PREFIXES = ['CLOUDFLARE_', 'GAMMA_', 'APP_STORE_CONNECT_'];
 /** Keys the kit retired and nothing reads anymore: never imported, named "retirada". */
 export const RETIRED_UNREAD_KEYS = ['NEON_ORGANIZATION_ID'];
 /** Whether `key` is a rail key ({@link RETIRED_RAIL_KEYS}, or one of its prefixed families). */
@@ -335,6 +339,98 @@ export function describeWrite(write) {
         return `${where} (key propia del proyecto, nueva)`;
     return `${where}${renamed}`;
 }
+/**
+ * Factory#72 — the writes are `create-if-missing`, so a key the vault already holds keeps its
+ * value, and the first sync carries THAT value to the deploy. Compare it against what the plan
+ * would write, at every location a sync reads (`main`, `develop`; `local` feeds no deploy). A
+ * reference is compared by the value it resolves to inside the plan; one whose target the plan
+ * does not write is skipped (its value is whatever the vault already has there).
+ *
+ * @param existing the vault's current values per location (`formatLocation`), references expanded.
+ */
+export function vaultWriteConflicts(writes, existing, hash) {
+    const planned = (location, key, depth = 0) => {
+        const write = writes.find((w) => w.key === key && formatLocation(w.location) === formatLocation(location));
+        if (!write || depth > 3)
+            return null;
+        if (write.kind === 'value')
+            return write.value;
+        if (write.kind === 'reference')
+            return planned(write.target, write.target.key, depth + 1);
+        return null;
+    };
+    const conflicts = [];
+    for (const write of writes) {
+        if (write.location.env === VAULT_ENV_LOCAL || write.kind === 'minted-resend')
+            continue;
+        const location = formatLocation(write.location);
+        const current = existing.get(location)?.get(write.key);
+        const expected = planned(write.location, write.key);
+        if (current === undefined || expected === null || current === expected)
+            continue;
+        conflicts.push({ location, key: write.key, vault: hash(current), plan: hash(expected) });
+    }
+    return conflicts;
+}
+/**
+ * Factory#73 — a Vercel var that is ONE record for production and preview, while `develop:/`
+ * gets its own value: the preview sync would rewrite the shared record and production would end
+ * up with develop's value. A key that stays a reference to `main:/` carries the same value to
+ * both targets and is harmless.
+ */
+export function dangerousSharedTargets(shared, writes) {
+    const developOwn = new Set(writes
+        .filter((w) => w.kind === 'value' && formatLocation(w.location) === formatLocation(DEVELOP_ROOT))
+        .map((w) => w.key));
+    return [...new Set(shared)].filter((key) => developOwn.has(key)).sort();
+}
+/** The names a repo gives its sender, in order (the kit reads `EMAIL_FROM`). */
+export const SENDER_KEYS = [
+    'EMAIL_FROM',
+    'FROM_EMAIL',
+    'MAIL_FROM',
+    'RESEND_FROM',
+];
+/**
+ * Factory#74 — the repo's sender, from any of {@link SENDER_KEYS} (production → preview →
+ * local). `unknown` lists other `*FROM*` keys holding an address: a sender under a name this does
+ * not know, which must not fall back to the kit's domain in silence.
+ */
+export function adoptSender(values) {
+    const maps = [values.production, values.preview, values.local];
+    for (const key of SENDER_KEYS) {
+        for (const map of maps) {
+            const value = map.get(key);
+            if (value)
+                return { sender: value, unknown: [] };
+        }
+    }
+    const unknown = new Set();
+    for (const map of maps) {
+        for (const [key, value] of map) {
+            if (/FROM/.test(key) && value?.includes('@'))
+                unknown.add(key);
+        }
+    }
+    return { sender: null, unknown: [...unknown].sort() };
+}
+/** A key that names a database by its connection (any provider, not only Neon). */
+const DATABASE_KEY_RE = /(^|_)DATABASE_URL$|_DB_URL$|^POSTGRES_URL|^TURSO_(DATABASE_URL|AUTH_TOKEN)$/;
+/**
+ * Factory#75 — a database key whose preview value equals production's becomes a reference
+ * `develop:/ → main:/`: previews and local would write to the production database. Neon's
+ * `DATABASE_URL` is left out when Neon manages it (its branches have their own path).
+ */
+export function sharedDatabaseKeys(writes, neonManaged) {
+    return writes
+        .filter((w) => w.kind === 'reference' &&
+        formatLocation(w.location) === formatLocation(DEVELOP_ROOT) &&
+        formatLocation(w.target) === formatLocation(MAIN_ROOT) &&
+        DATABASE_KEY_RE.test(w.key) &&
+        !(neonManaged && w.key === DATABASE_URL_KEY))
+        .map((w) => w.key)
+        .sort();
+}
 /**
  * Build the entries of the plan (one per key, sorted), the confirmations the apply needs and the
  * blockers that stop it. Pure: values in, NAMES and hashes out.
@@ -947,9 +1043,11 @@ export function manualVaultProjectSteps(slug, folders) {
         'contra borrado e import.');
 }
 /**
- * Whether the vault is OFFERED in this repo — the same rule as `vault adopt` (ADOPT-001): not in
- * `core`, detected by the lockfile's `profile: 'core'` OR by the absence of the wrapper
- * (`scripts/tools/with-vault.mjs`), never by the absence of `package.json`.
+ * Whether the vault is OFFERED in this repo (what `doctor`/`status` propose): not in `core`,
+ * detected by the lockfile's `profile: 'core'` OR by the absence of the wrapper
+ * (`scripts/tools/with-vault.mjs`), never by the absence of `package.json`. Offered ≠ allowed:
+ * `vault adopt` also ACCEPTS a `core` repo that asks for it (Factory#76) — only not proposing it
+ * keeps `doctor` quiet in every `core` repo of another stack.
  */
 export function isVaultOffered(rootDir) {
     return (detectCoreProfile(rootDir) === null && existsSync(path.join(rootDir, WITH_VAULT_SCRIPT_FILE)));

package/dist/lib/vault-api.js

@@ -54,7 +54,7 @@
  */
 import { CLIError } from './cli-error.js';
 import { LOCAL_ONLY_KEYS } from './env-file.js';
-import { DEFAULT_RUNNER_OVERRIDE_KEY, RailNoSessionError, RailNotInstalledError, createExecaInfisicalRunner, loginCommand, } from './rail.js';
+import { DEFAULT_RUNNER_OVERRIDE_KEY, RailNoSessionError, RailNotInstalledError, createExecaInfisicalRunner, INFISICAL_UPGRADE_HINT, loginCommand, } from './rail.js';
 import { VAULT_CONFIG } from './vault-config.js';
 // ---------------------------------------------------------------------------
 // Layout constants (ADR-005)
@@ -414,7 +414,7 @@ async function obtainSessionToken(runner, config, timeoutMs) {
         throw new RailNoSessionError(config);
     const token = result.stdout.trim();
     if (token === '' || /\s/.test(token)) {
-        throw new VaultApiError('unrecognized', 'La bóveda devolvió una sesión que no reconozco. Actualiza `infisical` (`brew upgrade infisical`) ' +
+        throw new VaultApiError('unrecognized', `La bóveda devolvió una sesión que no reconozco. Actualiza \`infisical\` (${INFISICAL_UPGRADE_HINT}) ` +
             `y entra con \`${loginCommand(config)}\`.`);
     }
     return token;