agent-trellis 0.4.0 → 0.6.0

package/dist/commands/onboard.js

@@ -29,8 +29,10 @@ import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
 import { collectSecretsAuditReport, printReport as printSecretsAuditReport } from "./secretsAudit.js";
 import { applyMemorySync, collectMemorySyncResult, printMemorySyncResult } from "./memory.js";
+import { collectDoctorReport, printReport as printDoctorReport, resolveKnownHostInjected } from "./doctor.js";
 import { openBackupSession } from "../lib/backup.js";
 import { confirmAndInstall } from "../lib/installAgent.js";
+import { normalizeDoctorVerdict, normalizeMcpSyncVerdict, normalizeMemorySyncVerdict, normalizeMigrateVerdict, normalizeSecretsAuditVerdict, normalizeSelfVerificationVerdict, normalizeSyncVerdict, printVerdict, } from "./onboardVerdict.js";
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
     codex: (homeDir) => codexProbe.probe(homeDir),
@@ -52,6 +54,21 @@ export async function collectOnboardSummary(homeDir = homedir()) {
 function hasContent(s) {
     return s.skillCount > 0 || s.hasRealInstructions || s.mcpServerCount > 0;
 }
+const PROGRESS_STAGES = ["migrate", "sync", "mcp sync", "memory sync", "secrets audit", "doctor"];
+/** Transient status, not part of the report — printed to stderr so
+ * `trellis onboard > report.txt` still captures exactly the report and
+ * verdict, nothing else (design.md D8). Silent for `--json` and for any
+ * non-interactive stdout, where nobody's watching a terminal march
+ * through stages in real time. */
+function shouldShowProgress(opts) {
+    return !opts.json && (opts.isTTY ?? process.stdout.isTTY === true);
+}
+function logProgress(opts, stage) {
+    if (!shouldShowProgress(opts))
+        return;
+    const index = PROGRESS_STAGES.indexOf(stage) + 1;
+    console.error(`[${index}/${PROGRESS_STAGES.length}] ${stage}`);
+}
 function agentSummaryLabel(s) {
     const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
     return `${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}, mcp: ${s.mcpServerCount}`;
@@ -243,7 +260,7 @@ export async function collectOnboardPlan(opts = {}) {
     const summary = await collectOnboardSummary(homeDir);
     const present = summary.filter((s) => s.present);
     if (present.length === 0) {
-        return { summary, installHints: { ...INSTALL_HINTS } };
+        return { summary, installHints: { ...INSTALL_HINTS }, verdict: [] };
     }
     const sourceCandidates = present.filter(hasContent);
     let source;
@@ -254,6 +271,7 @@ export async function collectOnboardPlan(opts = {}) {
             return {
                 summary,
                 refusal: `"${opts.agent}" is not one of the present agents (${present.map((s) => s.agent).join(", ")})`,
+                verdict: [],
             };
         }
         source = match.agent;
@@ -269,6 +287,7 @@ export async function collectOnboardPlan(opts = {}) {
             return {
                 summary,
                 refusal: `multiple agents detected (${sourceCandidates.map((s) => s.agent).join(", ")}) and no terminal to prompt in — pass --agent <id>`,
+                verdict: [],
             };
         }
         const prompt = opts.promptForAgent ?? promptForAgentReal;
@@ -276,7 +295,7 @@ export async function collectOnboardPlan(opts = {}) {
             source = (await prompt(sourceCandidates));
         }
         catch (err) {
-            return { summary, refusal: err instanceof Error ? err.message : String(err) };
+            return { summary, refusal: err instanceof Error ? err.message : String(err), verdict: [] };
         }
         sourceReason = "prompt";
     }
@@ -285,7 +304,7 @@ export async function collectOnboardPlan(opts = {}) {
     const alreadyManaged = readManagedYaml(homeDir);
     const managedResult = await resolveManagedAgents(opts, summary, alreadyManaged);
     if ("refusal" in managedResult) {
-        return { summary, source, sourceReason, refusal: managedResult.refusal };
+        return { summary, source, sourceReason, refusal: managedResult.refusal, verdict: [] };
     }
     const installResults = [];
     const resolvedNew = [];
@@ -307,6 +326,7 @@ export async function collectOnboardPlan(opts = {}) {
                 source,
                 sourceReason,
                 refusal: `"${agent}" is not installed — installing it requires a confirmation, which --json never prompts for. Inject a confirm handler or install ${agent} first.`,
+                verdict: [],
             };
         }
         const result = await confirmAndInstall(agent, opts.install);
@@ -323,6 +343,7 @@ export async function collectOnboardPlan(opts = {}) {
     }
     let migratePlan;
     let migrateSkipped;
+    logProgress(opts, "migrate");
     if (source) {
         const sourceSummary = summary.find((s) => s.agent === source);
         const categories = await resolveMigrateCategories(sourceSummary, opts);
@@ -341,14 +362,26 @@ export async function collectOnboardPlan(opts = {}) {
     // Neither collectSyncReport nor collectMcpSyncReport finalizes a
     // session they were handed; only this caller does, once, after both.
     const backupSession = opts.dryRun ? undefined : openBackupSession(homeDir, "onboard");
+    logProgress(opts, "sync");
     const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
+    // The self-verification re-plan (design.md D2b): immediately after a
+    // real apply, re-run the exact same plan computation, dry-run, against
+    // what was just written. A remaining "create"/"conflict" item means
+    // the write did not hold — the mechanism that actually closes the
+    // loop, since doctor (below) never reads canonical and cannot catch
+    // this even in principle. Skipped entirely on --dry-run: nothing was
+    // written, so there is nothing to verify.
+    const syncVerification = opts.dryRun ? undefined : await collectSyncReport({ homeDir, dryRun: true, managedAgents });
+    logProgress(opts, "mcp sync");
     const mcpSyncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
+    const mcpSyncVerification = opts.dryRun ? undefined : await collectMcpSyncReport({ homeDir, dryRun: true, managedAgents });
     backupSession?.finalize();
     // Independent of `managedAgents` — the shared memory server is not
     // per-agent (design.md D4, trellis-onboard-mcp-memory), unlike
     // sync/mcp-sync above. Runs unconditionally once reached; an
     // unconfigured `memory` server is a legitimate "nothing to do yet"
     // state (design.md D5), not gated on any prior step here.
+    logProgress(opts, "memory sync");
     const memorySyncResult = collectMemorySyncResult(homeDir);
     if (!opts.dryRun) {
         applyMemorySync(memorySyncResult);
@@ -356,7 +389,29 @@ export async function collectOnboardPlan(opts = {}) {
     // Read-only, no dryRun concept — same report either way, run last since
     // it audits the config mcp sync just wrote (or, on --dry-run, whatever
     // was already there before this run).
+    logProgress(opts, "secrets audit");
     const secretsAuditReport = await collectSecretsAuditReport({ homeDir, managedAgents });
+    // The broader health scan (design.md D2/D3/D4) — last, since it's the
+    // only stage whose job is to observe the result of every other one.
+    // Never --probe-mcp: the worst possible moment to start spawning every
+    // configured MCP server is a user's first-ever run of this command.
+    // Scoped to every agent, not just managedAgents — filtering here would
+    // hide exactly the finding onboarding is most likely to create (a
+    // newly-relevant agent drifting, or colliding with an unmanaged one);
+    // normalizeDoctorVerdict is what turns "unmanaged" into a warning
+    // rather than hiding it outright.
+    logProgress(opts, "doctor");
+    const doctorReport = await collectDoctorReport(homeDir, resolveKnownHostInjected({ homeDir }));
+    const verdict = [
+        ...normalizeMigrateVerdict(migratePlan),
+        ...normalizeSyncVerdict(syncReport),
+        ...normalizeSelfVerificationVerdict("sync", syncVerification?.reports),
+        ...normalizeMcpSyncVerdict(mcpSyncReport),
+        ...normalizeSelfVerificationVerdict("mcp sync", mcpSyncVerification?.reports),
+        ...normalizeMemorySyncVerdict(memorySyncResult),
+        ...normalizeSecretsAuditVerdict(secretsAuditReport),
+        ...normalizeDoctorVerdict(doctorReport, managedAgents),
+    ];
     return {
         summary,
         source,
@@ -367,27 +422,65 @@ export async function collectOnboardPlan(opts = {}) {
         migrateSkipped,
         syncReport,
         mcpSyncReport,
+        syncVerification,
+        mcpSyncVerification,
         memorySyncResult,
         secretsAuditReport,
+        doctorReport,
+        verdict,
     };
 }
+/**
+ * Declining is the default (design.md D9): "No" is the first, highlighted
+ * option, so Enter — the reflex keystroke — declines. Only ever offered
+ * on a real, raw-mode-capable terminal (`canUseInteractivePicker`, the
+ * same gate every other onboard prompt already uses); `--json` and
+ * non-interactive runs never reach this at all.
+ */
+async function offerToApply(opts) {
+    if (opts.promptToApply)
+        return opts.promptToApply();
+    if (!canUseInteractivePicker())
+        return false;
+    console.log("");
+    const choice = await runSingleSelectPicker(["No, don't apply", "Yes, apply now"]);
+    return choice === 1;
+}
 export async function runOnboard(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
     const result = await collectOnboardPlan(opts);
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
     }
     else {
         printResult(result, opts.dryRun ?? false);
+        // Always last — including on a fully clean run and on a refusal —
+        // so the terminal state of the run is never a green line from
+        // whichever stage happened to print last (spec: "Every run
+        // terminates in a verdict that matches its exit code"). A refusal
+        // never populates `result.verdict` (every early-return path sets it
+        // to `[]`), so it has to be folded in here explicitly — otherwise
+        // the verdict would print "nothing needs attention, exit code: 0"
+        // directly underneath a real refusal that returns exit code 1: the
+        // exact contradiction this whole mechanism exists to prevent, just
+        // reached from a different direction.
+        const verdictForDisplay = result.refusal ? [...result.verdict, { stage: "onboard", severity: "blocked", message: result.refusal }] : result.verdict;
+        printVerdict(verdictForDisplay, homeDir);
     }
     if (result.refusal)
         return { exitCode: 1 };
-    const memorySyncConflict = result.memorySyncResult?.configured === true && result.memorySyncResult.plan.items.some((i) => i.action === "conflict");
-    const hasConflict = (result.migratePlan?.items.some((i) => i.action === "conflict") ?? false) ||
-        (result.syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
-        (result.mcpSyncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
-        memorySyncConflict ||
-        (result.secretsAuditReport?.findings.length ?? 0) > 0;
-    return { exitCode: hasConflict ? 1 : 0 };
+    if (opts.dryRun && !opts.json) {
+        const accepted = await offerToApply(opts);
+        if (accepted) {
+            // Re-plan and apply for real rather than replaying this exact
+            // plan — the user may have changed state while reading the
+            // preview, and re-planning against current state is cheap next to
+            // applying a plan that's gone stale (design.md D9).
+            return runOnboard({ ...opts, dryRun: false });
+        }
+    }
+    const hasBlocked = result.verdict.some((item) => item.severity === "blocked");
+    return { exitCode: hasBlocked ? 1 : 0 };
 }
 function printResult(result, dryRun) {
     if (dryRun)
@@ -452,4 +545,11 @@ function printResult(result, dryRun) {
         console.log("\nsecrets audit");
         printSecretsAuditReport(result.secretsAuditReport);
     }
+    if (result.doctorReport) {
+        // Distinct from the self-verification re-plan above: this is a
+        // broader health scan across every agent, not proof that this run's
+        // own writes took effect (design.md D2b).
+        console.log("\nhealth scan (trellis doctor)");
+        printDoctorReport(result.doctorReport);
+    }
 }

package/dist/commands/onboardVerdict.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Normalizes every chained stage's own report shape into one flat list
+ * (trellis-onboard-closed-loop design.md D5) — the single source both
+ * `runOnboard`'s exit code and the terminal verdict block derive from,
+ * so the two can never disagree the way the five-clause inline boolean
+ * this replaces once could.
+ *
+ * Each normalizer reads its stage's existing report type; none of them
+ * re-implement conflict detection — they translate an already-computed
+ * verdict (a plan item's `action`, a finding being present at all) into
+ * one shared shape. A stage whose report is absent (never ran, e.g. no
+ * migration source) contributes nothing, not an error.
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId } from "../core/types.js";
+import type { MigratePlan } from "./migrate.js";
+import type { SyncReport } from "./sync.js";
+import type { McpSyncReport } from "./mcp.js";
+import type { MemorySyncResult } from "./memory.js";
+import type { SecretsAuditReport } from "./secretsAudit.js";
+import type { DoctorReport } from "./doctor.js";
+export type VerdictSeverity = "blocked" | "warning";
+export interface VerdictItem {
+    stage: string;
+    severity: VerdictSeverity;
+    message: string;
+    remediation?: string;
+    agent?: AgentId;
+}
+export declare function normalizeMigrateVerdict(plan: MigratePlan | undefined): VerdictItem[];
+export declare function normalizeSyncVerdict(report: SyncReport | undefined): VerdictItem[];
+export declare function normalizeMcpSyncVerdict(report: McpSyncReport | undefined): VerdictItem[];
+/**
+ * The self-verification re-plan (design.md D2b): a re-plan run
+ * immediately after a real apply, against the state that apply just
+ * wrote. Any remaining `"create"`/`"conflict"` item here means the
+ * write itself did not hold — distinct from, and always `blocked`
+ * regardless of what the original apply reported, because it directly
+ * contradicts this run's own claim of having written it.
+ */
+export declare function normalizeSelfVerificationVerdict(stage: "sync" | "mcp sync", reports: readonly {
+    agent: AgentId;
+    items: readonly AdapterPlanItem[];
+}[] | undefined): VerdictItem[];
+export declare function normalizeMemorySyncVerdict(result: MemorySyncResult | undefined): VerdictItem[];
+export declare function normalizeSecretsAuditVerdict(report: SecretsAuditReport | undefined): VerdictItem[];
+/**
+ * Always the last thing `printResult` prints, on every run including a
+ * fully clean one — the exact regression this change exists to fix: a
+ * run with a real early-stage conflict must not end on a later stage's
+ * unrelated success line (trellis-onboard-closed-loop spec: "Every run
+ * terminates in a verdict that matches its exit code").
+ */
+export declare function printVerdict(verdict: readonly VerdictItem[], homeDir: string): void;
+export declare function normalizeDoctorVerdict(report: DoctorReport | undefined, managedAgents: readonly AgentId[]): VerdictItem[];

package/dist/commands/onboardVerdict.js

@@ -0,0 +1,175 @@
+/**
+ * Normalizes every chained stage's own report shape into one flat list
+ * (trellis-onboard-closed-loop design.md D5) — the single source both
+ * `runOnboard`'s exit code and the terminal verdict block derive from,
+ * so the two can never disagree the way the five-clause inline boolean
+ * this replaces once could.
+ *
+ * Each normalizer reads its stage's existing report type; none of them
+ * re-implement conflict detection — they translate an already-computed
+ * verdict (a plan item's `action`, a finding being present at all) into
+ * one shared shape. A stage whose report is absent (never ran, e.g. no
+ * migration source) contributes nothing, not an error.
+ */
+function itemMessage(stage, agent, description) {
+    const item = { stage, severity: "blocked", message: description };
+    if (agent)
+        item.agent = agent;
+    return item;
+}
+/** Shared by `sync` and `mcp sync` — `AgentSyncReport` and
+ * `AgentMcpSyncReport` are structurally identical
+ * (`{ agent, present, items: AdapterPlanItem[] }`), so one function
+ * serves both rather than two copies that could drift. */
+function normalizePlanItems(stage, reports) {
+    if (!reports)
+        return [];
+    const items = [];
+    for (const report of reports) {
+        for (const item of report.items) {
+            if (item.action !== "conflict")
+                continue;
+            const verdict = itemMessage(stage, report.agent, item.description);
+            if (item.remediation)
+                verdict.remediation = item.remediation;
+            items.push(verdict);
+        }
+    }
+    return items;
+}
+export function normalizeMigrateVerdict(plan) {
+    if (!plan)
+        return [];
+    const items = [];
+    for (const item of plan.items) {
+        if (item.action !== "conflict")
+            continue;
+        const verdict = { stage: "migrate", severity: "blocked", message: item.detail };
+        if (item.remediation)
+            verdict.remediation = item.remediation;
+        items.push(verdict);
+    }
+    return items;
+}
+export function normalizeSyncVerdict(report) {
+    return normalizePlanItems("sync", report?.reports);
+}
+export function normalizeMcpSyncVerdict(report) {
+    return normalizePlanItems("mcp sync", report?.reports);
+}
+/**
+ * The self-verification re-plan (design.md D2b): a re-plan run
+ * immediately after a real apply, against the state that apply just
+ * wrote. Any remaining `"create"`/`"conflict"` item here means the
+ * write itself did not hold — distinct from, and always `blocked`
+ * regardless of what the original apply reported, because it directly
+ * contradicts this run's own claim of having written it.
+ */
+export function normalizeSelfVerificationVerdict(stage, reports) {
+    if (!reports)
+        return [];
+    const items = [];
+    for (const report of reports) {
+        for (const item of report.items) {
+            if (item.action !== "create" && item.action !== "conflict")
+                continue;
+            items.push({
+                stage: `${stage} (verify)`,
+                severity: "blocked",
+                agent: report.agent,
+                message: `expected to have written "${item.target}" but a re-plan still finds it outstanding: ${item.description}`,
+                remediation: `re-run \`trellis ${stage === "sync" ? "sync" : "mcp sync"}\` and, if this repeats, check for a filesystem permission or symlink problem at ${item.target}`,
+            });
+        }
+    }
+    return items;
+}
+export function normalizeMemorySyncVerdict(result) {
+    if (!result)
+        return [];
+    if (!result.configured) {
+        return [{ stage: "memory sync", severity: "warning", message: result.reason }];
+    }
+    const items = [];
+    for (const item of result.plan.items) {
+        if (item.action !== "conflict")
+            continue;
+        items.push({ stage: "memory sync", severity: "blocked", message: item.detail });
+    }
+    return items;
+}
+export function normalizeSecretsAuditVerdict(report) {
+    if (!report)
+        return [];
+    return report.findings.map((finding) => {
+        const item = { stage: "secrets audit", severity: "blocked", message: `${finding.file}: ${finding.detail}` };
+        if (finding.agent !== "environment")
+            item.agent = finding.agent;
+        return item;
+    });
+}
+/**
+ * A finding naming an agent outside the managed set is a `warning`, not
+ * `blocked` — onboard did not touch that agent, so its drift is not this
+ * run's failure (design.md D3). A finding with no `agent` at all (only
+ * cross-agent `"drift"`, per `src/commands/doctor.ts`'s own findings
+ * construction) is conservatively `blocked`: it inherently spans more
+ * than one agent, and there is no way to prove none of them are managed.
+ */
+/** Any path under `homeDir` prints as `~/…` rather than an absolute
+ * scratch/real path — the run's own `homeDir`, never `homedir()`, so a
+ * test's scratch home abbreviates the same way a real run does. */
+function abbreviate(text, homeDir) {
+    return text.split(homeDir).join("~");
+}
+/**
+ * Always the last thing `printResult` prints, on every run including a
+ * fully clean one — the exact regression this change exists to fix: a
+ * run with a real early-stage conflict must not end on a later stage's
+ * unrelated success line (trellis-onboard-closed-loop spec: "Every run
+ * terminates in a verdict that matches its exit code").
+ */
+export function printVerdict(verdict, homeDir) {
+    const blocked = verdict.filter((item) => item.severity === "blocked");
+    const warnings = verdict.filter((item) => item.severity === "warning");
+    console.log("");
+    console.log("verdict");
+    if (blocked.length === 0 && warnings.length === 0) {
+        console.log("✅ nothing needs attention — every stage completed cleanly and verified");
+        console.log("exit code: 0 — nothing blocked this run");
+        return;
+    }
+    if (blocked.length > 0) {
+        console.log(`❌ ${blocked.length} blocking issue(s):`);
+        for (const item of blocked) {
+            const where = item.agent ? `${item.stage}/${item.agent}` : item.stage;
+            console.log(`   - [${where}] ${abbreviate(item.message, homeDir)}`);
+            if (item.remediation)
+                console.log(`     → ${abbreviate(item.remediation, homeDir)}`);
+        }
+    }
+    if (warnings.length > 0) {
+        console.log(`⚠️  ${warnings.length} warning(s) — did not block this run:`);
+        for (const item of warnings) {
+            const where = item.agent ? `${item.stage}/${item.agent}` : item.stage;
+            console.log(`   - [${where}] ${abbreviate(item.message, homeDir)}`);
+            if (item.remediation)
+                console.log(`     → ${abbreviate(item.remediation, homeDir)}`);
+        }
+    }
+    console.log(blocked.length > 0 ? "exit code: 1 — at least one blocking issue above" : "exit code: 0 — warnings only, nothing blocked this run");
+}
+export function normalizeDoctorVerdict(report, managedAgents) {
+    if (!report)
+        return [];
+    const managed = new Set(managedAgents);
+    return report.findings.map((finding) => {
+        const concernsOnlyUnmanaged = finding.agent !== undefined && !managed.has(finding.agent);
+        const item = { stage: "doctor", severity: concernsOnlyUnmanaged ? "warning" : "blocked", message: finding.message };
+        if (finding.agent)
+            item.agent = finding.agent;
+        if (concernsOnlyUnmanaged)
+            item.remediation = `concerns "${finding.agent}", which this run does not manage — run \`trellis doctor\` directly if you want to look into it`;
+        return item;
+    });
+}

package/dist/core/adapter.d.ts

@@ -50,6 +50,13 @@ export interface AdapterPlanItem {
     /** Human-readable description of one change this adapter would make
      * ("create" / "remove") or why it refused to ("conflict"). */
     description: string;
+    /** Only set (and only meaningful) when `action === "conflict"`: the
+     * concrete next action a user can take, distinct from restating why
+     * it conflicted (`description` already does that) — surfaced in
+     * `trellis onboard`'s verdict block (trellis-onboard-closed-loop
+     * design.md D7). Optional so existing conflict sites keep compiling
+     * and rendering cleanly before each is given one. */
+    remediation?: string;
     /** What's being touched, for the collision/audit checks to reason
      * about. For `kind: "mcp"`, the config file being modified (e.g.
      * `~/.codex/config.toml`), not a per-server path — there isn't one. */

package/dist/core/canonical.d.ts

@@ -6,14 +6,16 @@
  */
 import type { CanonicalSource, McpServerDef } from "./types.js";
 /**
- * The on-disk shape for one server entry — `static_env` (snake_case, like
- * every other multi-word key across `.trellis/*.yaml`) is translated to
- * `McpServerDef.staticEnv` (camelCase) below; every other field happens
- * to already be a single word, so no server-def field needed this
- * treatment before (trellis-mcp-static-env-and-disabled-servers).
+ * The on-disk shape for one server entry — `static_env`/`env_aliases`
+ * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
+ * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
+ * below; every other field happens to already be a single word, so no
+ * server-def field needed this treatment before
+ * (trellis-mcp-static-env-and-disabled-servers, trellis-migrate-env-var-alias).
  */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv"> & {
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases"> & {
     static_env?: Record<string, string>;
+    env_aliases?: Record<string, string>;
 };
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`

package/dist/core/canonical.js

@@ -10,17 +10,24 @@ import { basename, join } from "node:path";
 import { isMap, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
 function fromServerDefYaml(def) {
-    const { static_env, ...rest } = def;
-    return static_env ? { ...rest, staticEnv: static_env } : rest;
+    const { static_env, env_aliases, ...rest } = def;
+    const out = { ...rest };
+    if (static_env)
+        out.staticEnv = static_env;
+    if (env_aliases)
+        out.envAliases = env_aliases;
+    return out;
 }
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`
  * for an omitted optional. */
 export function toServerDefYaml(def) {
-    const { staticEnv, ...rest } = def;
+    const { staticEnv, envAliases, ...rest } = def;
     const out = { ...rest };
     if (staticEnv)
         out.static_env = staticEnv;
+    if (envAliases)
+        out.env_aliases = envAliases;
     for (const key of Object.keys(out)) {
         if (out[key] === undefined)
             delete out[key];
@@ -81,8 +88,24 @@ function loadServersYaml(path) {
         servers,
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
+        gateway: fromGatewayYaml(parsed.gateway),
     };
 }
+/**
+ * A `gateway:` block with no `enabled` key reads as off, not as on — the
+ * only safe default for a field whose whole effect is to stop writing the
+ * per-server entries an agent is currently working with. Absent entirely,
+ * the field stays `undefined` so `resolveMcpPlan` can tell "never
+ * configured" from "explicitly disabled" if that ever matters.
+ */
+function fromGatewayYaml(gateway) {
+    if (!gateway)
+        return undefined;
+    const out = { enabled: gateway.enabled === true };
+    if (gateway.agents)
+        out.agents = gateway.agents;
+    return out;
+}
 /**
  * Writes or replaces one server entry in `servers.yaml`, preserving
  * every other entry's and comment's exact formatting (trellis-

package/dist/core/types.d.ts

@@ -53,6 +53,18 @@ export interface McpServerDef {
      * environment tag), not an escape hatch for real credentials.
      */
     staticEnv?: Record<string, string>;
+    /**
+     * Target env var name -> source variable name, for a reference whose
+     * key differs from the name it resolves (`OPENAPI_MCP_HEADERS:
+     * "${NOTION_OPENAPI_MCP_HEADERS}"` becomes `{ OPENAPI_MCP_HEADERS:
+     * "NOTION_OPENAPI_MCP_HEADERS" }`) — `env`'s self-referencing shape
+     * can't express a differently-named source, and treating this case as
+     * `staticEnv` silently ships the literal, unexpanded placeholder text
+     * to any consumer with no native `${VAR}` runtime of its own
+     * (trellis-migrate-env-var-alias). Resolved through the exact same
+     * mechanism as `env`, never a raw literal.
+     */
+    envAliases?: Record<string, string>;
     /**
      * Defaults to `true`. `false` keeps the definition in canonical
      * without writing it to any agent — matches a real host config's own
@@ -75,20 +87,46 @@ export interface McpServerDef {
 export interface HubConfig {
     url: string;
 }
+/**
+ * Converge an agent's MCP config onto one local stdio process Trellis
+ * itself spawns (`trellis mcp-gateway --agent <id>`), instead of writing
+ * one native entry per server.
+ *
+ * Deliberately NOT the same field as `hub`: `hub` names an HTTP endpoint
+ * the user operates somewhere else and Trellis never starts; this names a
+ * subprocess Trellis owns. Overloading one field to mean both would force
+ * every future reader to disambiguate two unrelated concepts by context
+ * (trellis-mcp-gateway-hosting design.md D5).
+ */
+export interface GatewayConfig {
+    enabled: boolean;
+    /**
+     * Which agents converge through the gateway. Omit — the expected normal
+     * case — and `enabled` applies to every managed agent; which agents
+     * converge is not a question a user should have to answer to get the
+     * feature. Present, it narrows to exactly these, leaving the rest in
+     * direct or hub mode.
+     */
+    agents?: AgentId[];
+}
 export interface McpConfig {
     servers: Record<string, McpServerDef>;
     /**
      * Server names a host environment (e.g. mirasim) is known to inject at
      * runtime. Checked against every server name Trellis would write per
-     * agent when `hub` is unset; against the single hub entry name only when
-     * `hub` is set (there's nothing else to collide) — see docs/research.md
-     * "Codex — three hard constraints" for why a same-name collision is not
-     * a soft failure on every agent.
+     * agent in direct mode; against the single converged entry name only in
+     * hub or gateway mode (there's nothing else to collide) — see
+     * docs/research.md "Codex — three hard constraints" for why a same-name
+     * collision is not a soft failure on every agent.
      */
     knownHostInjected: string[];
     /** Omit for direct mode (today's default: every agent gets all N server
      * definitions written into its native config). See `HubConfig`. */
     hub?: HubConfig;
+    /** Omit for direct mode. See `GatewayConfig`. Independent of `hub`: the
+     * two mean different things and may both be set, in which case gateway
+     * wins per agent (trellis-mcp-gateway-hosting design.md D5/D6). */
+    gateway?: GatewayConfig;
 }
 export interface SkillRef {
     name: string;