agent-trellis 0.6.3 → 0.7.0

package/dist/adapters/mcpPlan.d.ts

@@ -45,6 +45,21 @@ export interface McpPlanResult {
     desired: DesiredMcpEntry[];
     conflicts: McpConflict[];
 }
+/** Which field on `McpServerDef` a literal-secret match came from —
+ * `migrate`'s extraction path (trellis-migrate-extract-static-env-secrets
+ * design.md D1) needs this to decide whether a natural variable name
+ * exists to extract to: only `staticEnv` has one (its own dict key).
+ * A match in any other field still just refuses, unchanged. */
+export type LiteralSecretField = "command" | "url" | "args" | "headers" | "staticEnv";
+export interface LiteralSecretMatch {
+    label: string;
+    field: LiteralSecretField;
+    /** The dict key the match came from, only set for `staticEnv`/`headers`
+     * (the only two `Record<string, string>` fields) — `migrate`'s
+     * extraction path uses this as the variable name to extract to when
+     * `field === "staticEnv"` (its own key is already a natural name). */
+    key?: string;
+}
 /**
  * Exported so `migrate`'s own read path (`src/commands/migrate.ts`) can
  * apply the identical check on the way *into* canonical, not just on the
@@ -59,6 +74,10 @@ export interface McpPlanResult {
  * read, diffed, and committed as plain text. One shared implementation,
  * not two that can drift, for the same reason `mcpConnect.ts`/
  * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ *
+ * Scanning order is `command, url, args, headers, staticEnv` — a def
+ * matching in more than one field returns whichever is found first, same
+ * as before this function reported a field at all.
  */
-export declare function findLiteralSecret(def: McpServerDef): string | undefined;
+export declare function findLiteralSecret(def: McpServerDef): LiteralSecretMatch | undefined;
 export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): McpPlanResult;

package/dist/adapters/mcpPlan.js

@@ -71,13 +71,23 @@ const DANGEROUS_LITERAL_PATTERNS = [
  * read, diffed, and committed as plain text. One shared implementation,
  * not two that can drift, for the same reason `mcpConnect.ts`/
  * `mcpToolRegistry.ts` are shared between pi-bridge and the gateway.
+ *
+ * Scanning order is `command, url, args, headers, staticEnv` — a def
+ * matching in more than one field returns whichever is found first, same
+ * as before this function reported a field at all.
  */
 export function findLiteralSecret(def) {
-    const candidates = [def.command, def.url, ...(def.args ?? []), ...Object.values(def.headers ?? {}), ...Object.values(def.staticEnv ?? {})].filter((v) => typeof v === "string");
-    for (const candidate of candidates) {
+    const candidates = [
+        ...(def.command !== undefined ? [{ value: def.command, field: "command" }] : []),
+        ...(def.url !== undefined ? [{ value: def.url, field: "url" }] : []),
+        ...(def.args ?? []).map((value) => ({ value, field: "args" })),
+        ...Object.entries(def.headers ?? {}).map(([key, value]) => ({ value, field: "headers", key })),
+        ...Object.entries(def.staticEnv ?? {}).map(([key, value]) => ({ value, field: "staticEnv", key })),
+    ];
+    for (const { value, field, key } of candidates) {
         for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
-            if (pattern.test(candidate)) {
-                return label;
+            if (pattern.test(value)) {
+                return { label, field, key };
             }
         }
     }
@@ -149,11 +159,23 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts.push({ name, message: collisionMessage(name, agentId), remediation: collisionRemediation(name) });
             continue;
         }
-        const secretLabel = findLiteralSecret(def);
-        if (secretLabel) {
+        // Only `staticEnv` is refused here: it's the one shape a real
+        // credential is meant to leave via `env`/`env_vars`, proven to
+        // resolve back to a real value for every consumer (pi-bridge,
+        // claude-code, codex, kiro) — a literal surviving there means
+        // something bypassed `migrate`'s own extraction (a hand-edited
+        // servers.yaml, most likely) and must still be refused outright. A
+        // match in `command`/`url`/`args`/`headers` is accepted and written
+        // as ordinary literal config instead (trellis-migrate-extract-static-env-secrets
+        // design.md D11) — none of those fields has a `${VAR}` resolution
+        // mechanism proven across every consumer, so a fake reference there
+        // would be strictly worse than the literal it replaced; `secrets
+        // audit` keeps flagging canonical itself so this isn't silent.
+        const secretMatch = findLiteralSecret(def);
+        if (secretMatch?.field === "staticEnv") {
             conflicts.push({
                 name,
-                message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+                message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretMatch.label}) — configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
                 remediation: `replace the literal value in servers.yaml with a \`\${VAR_NAME}\` reference and put the real value wherever secrets.policy.yaml resolves it from`,
             });
             continue;

package/dist/cli.js

@@ -160,6 +160,15 @@ async function main(argv) {
         process.exitCode = 1;
         return;
     }
+    // `--help`/`-h` anywhere in a subcommand's own args short-circuits before
+    // any parsing or real action — a typo'd or exploratory flag (e.g. `mcp
+    // sync --help`) must never fall through to actually running the command
+    // it was asking about (real incident: `--help` isn't a flag any branch
+    // recognizes, so it silently ran a real, non-dry-run `mcp sync`).
+    if (rest.includes("--help") || rest.includes("-h")) {
+        printUsage();
+        return;
+    }
     if (command === "onboard") {
         const agentIndex = rest.indexOf("--agent");
         const agent = agentIndex >= 0 ? rest[agentIndex + 1] : undefined;

package/dist/commands/migrate.d.ts

@@ -5,7 +5,7 @@
  * plan-then-apply split every adapter already uses.
  */
 import type { AgentId, McpServerDef } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict" | "extract-secret";
 /** Internal kind naming, unchanged since before `--only` existed
  * (trellis-migrate-category-selection design.md D2) — the CLI-facing
  * flag value is the plural `"skills"`, mapped to this singular `"skill"`
@@ -24,8 +24,27 @@ export interface MigratePlanItem {
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;
-    /** Only set when kind === "mcp" && action === "create". */
+    /** Only set when kind === "mcp" && (action === "create" || "reclassify"
+     * || "extract-secret"). For "extract-secret" this is already the SAFE
+     * def — the flagged staticEnv value moved to a name-only `env` entry —
+     * never the literal (trellis-migrate-extract-static-env-secrets
+     * design.md D7). */
     mcpDef?: McpServerDef;
+    /** Only set when action === "extract-secret" — the variable name being
+     * extracted and the resolved path its real value will be written to.
+     * Deliberately never the real value itself, which never rides on this
+     * object at all (design.md D9); `applyMigratePlan` re-reads it fresh
+     * from the source agent at apply time. */
+    extractVarName?: string;
+    extractTargetPath?: string;
+    /** Only set when action === "extract-secret" and differs from
+     * `extractVarName` — the ORIGINAL `staticEnv` dict key in the source
+     * def, needed at apply time to know which key to read/remove there.
+     * `extractVarName` (design.md D11's `TRELLIS_<SERVER>_<KEY>` scheme) is
+     * a different, synthesized name — the two only coincide for an
+     * already-migrated server extracted before this naming scheme existed,
+     * which never reaches this action at all (already-migrated instead). */
+    extractSourceKey?: string;
 }
 export interface MigratePlan {
     agent: AgentId;

package/dist/commands/migrate.js

@@ -15,9 +15,34 @@ import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
 import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { findLiteralSecret } from "../adapters/mcpPlan.js";
-import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
+import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
+/** Where a `staticEnv` literal secret's real value goes when
+ * `secrets.policy.yaml` doesn't already have its own `env_file`
+ * (trellis-migrate-extract-static-env-secrets design.md D3) — a sibling
+ * of `servers.yaml`, so "the mcp stuff" stays one directory rather than
+ * a second, disconnected location. `~`-form for what gets written into
+ * `secrets.policy.yaml` itself (portable across machines); resolved form
+ * for real file I/O. */
+const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+function defaultLocalSecretsEnvFilePath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "servers.local.env");
+}
+/** Picks the rc file `ensureShellEnvSource` writes its one pointer block
+ * into, from `$SHELL` — zsh and bash are the only shells Trellis's own
+ * dev/CI machines and this feature's real-machine dogfooding have ever
+ * exercised; anything else falls back to `.profile`, the POSIX-sh default
+ * every shell still sources one way or another. */
+function defaultShellRcPath(homeDir) {
+    const shell = process.env.SHELL ?? "";
+    if (shell.includes("zsh"))
+        return join(homeDir, ".zshrc");
+    if (shell.includes("bash"))
+        return join(homeDir, ".bash_profile");
+    return join(homeDir, ".profile");
+}
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
     codex: (homeDir) => codexProbe.probe(homeDir),
@@ -110,24 +135,119 @@ export function isSafeReclassification(existing, def) {
         return false;
     return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
 }
-function planMcpServer(name, def, existing) {
-    // Checked first, before any comparison against `existing`: a source
-    // agent's real config holding a literal credential must never reach
-    // canonical at all, regardless of whether canonical already has
-    // something for this name. `resolveMcpPlan`'s own guard only protects
-    // the sync-OUT boundary (canonical -> agent) — this is the matching
-    // guard for the migrate-IN boundary (agent -> canonical), the gap a
-    // real `mcp-router` token in a real `kiro` config exposed.
-    const secretLabel = findLiteralSecret(def);
-    if (secretLabel) {
+/** Moves `sourceKey` out of `staticEnv` into a name-only `env` reference
+ * under `varName` — the def this produces never holds the literal that
+ * triggered extraction (trellis-migrate-extract-static-env-secrets
+ * design.md D7), safe to upsert into canonical or appear in any output.
+ * `sourceKey` and `varName` differ under D11's `TRELLIS_<SERVER>_<KEY>`
+ * naming scheme — the source dict key is not, in general, the name the
+ * value ends up referenced by. */
+function extractedMcpDef(def, sourceKey, varName) {
+    const remainingStaticEnv = { ...(def.staticEnv ?? {}) };
+    delete remainingStaticEnv[sourceKey];
+    const result = { ...def, env: [...(def.env ?? []), varName] };
+    if (Object.keys(remainingStaticEnv).length > 0) {
+        result.staticEnv = remainingStaticEnv;
+    }
+    else {
+        delete result.staticEnv;
+    }
+    return result;
+}
+/** Uppercase, non-alphanumeric runs collapsed to a single `_`, no leading
+ * or trailing `_` — the one sanitization every synthesized name piece
+ * shares (design.md D11), so `mcp-router` becomes `MCP_ROUTER` and a
+ * header key like `X-Api-Key` becomes `X_API_KEY`. */
+function sanitizeEnvNamePart(s) {
+    return s.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "X";
+}
+/** `TRELLIS_<SERVER>_<KEY>` — the project-wide prefix rules out a
+ * collision with anything already in the user's own environment or
+ * another tool's convention; the server-name segment rules out two
+ * Trellis-managed servers colliding with each other over the same key
+ * (design.md D11). Deliberately never the bare source key alone (what
+ * the code shipped with initially, and what an already-extracted server
+ * predating this scheme still uses — `planStaticEnvExtraction`'s own
+ * value-based lookup is what keeps recognizing those, not this
+ * function). */
+function synthesizeVarName(serverName, key) {
+    return `TRELLIS_${sanitizeEnvNamePart(serverName)}_${sanitizeEnvNamePart(key)}`;
+}
+/**
+ * Only reached when `findLiteralSecret` matched inside `staticEnv` —
+ * `key` is that field's own dict key (design.md D1). Reads the target
+ * local-secrets file read-only to decide the outcome; never writes
+ * anything itself (planning stays dry-run-safe) and never puts the real
+ * value on the returned item (design.md D9) — only used here, in memory,
+ * to compare against what's already on disk.
+ *
+ * The variable name a *new* extraction is filed under is synthesized
+ * (design.md D11's `TRELLIS_<SERVER>_<KEY>`, not the bare `key`) — but an
+ * already-extracted server may have been extracted before this scheme
+ * existed, under the bare key or any other name. Rather than hardcoding
+ * "the old scheme was the bare key", this looks up `existing.env` by
+ * VALUE: any name already in canonical's `env` list whose local-secrets
+ * value already matches `realValue` means this server was already
+ * extracted, under whatever name that was, and must keep using it — not
+ * get a second, newly-synthesized reference alongside the first.
+ */
+function planStaticEnvExtraction(name, def, existing, homeDir, policy, key) {
+    const realValue = def.staticEnv[key];
+    const targetPath = policy.envFile ?? defaultLocalSecretsEnvFilePath(homeDir);
+    const localSecrets = existsSync(targetPath) ? parseDotenv(readFileSync(targetPath, "utf-8")) : {};
+    const priorName = existing?.env?.find((n) => Object.hasOwn(localSecrets, n) && localSecrets[n] === realValue);
+    const varName = priorName ?? synthesizeVarName(name, key);
+    const safeDef = extractedMcpDef(def, key, varName);
+    const alreadyInSecretsFile = Object.hasOwn(localSecrets, varName);
+    if (priorName === undefined && alreadyInSecretsFile && localSecrets[varName] !== realValue) {
         return {
             kind: "mcp",
             name,
             action: "conflict",
-            detail: `refusing to import MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — canonical must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
-            remediation: `move the real value in the source agent's own config to an environment variable (or your secrets manager), leaving only a name behind, then re-run migrate — canonical never accepts a literal credential, even briefly`,
+            detail: `refusing to extract MCP server "${name}"'s "${varName}": ${targetPath} already has a different value for this name — resolve by hand`,
+            remediation: `compare the source agent's current value for "${varName}" against the value already in ${targetPath} and update whichever one is stale, then re-run migrate`,
         };
     }
+    if (alreadyInSecretsFile && existing !== undefined && deepEqual(existing, safeDef)) {
+        return { kind: "mcp", name, action: "already-migrated", detail: `already extracted — "${varName}" is referenced from servers.yaml and its real value is already in ${targetPath}` };
+    }
+    if (existing !== undefined && !deepEqual(existing, safeDef) && !isSafeReclassification(existing, safeDef)) {
+        return {
+            kind: "mcp",
+            name,
+            action: "conflict",
+            detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand`,
+            remediation: `compare the source agent's own definition for "${name}" against \`~/.trellis/mcp/servers.yaml\` and update canonical by hand if the source's is the one to keep`,
+        };
+    }
+    return {
+        kind: "mcp",
+        name,
+        action: "extract-secret",
+        detail: `will extract "${key}" to ${targetPath} as "${varName}", referencing it from servers.yaml instead of holding the literal value`,
+        mcpDef: safeDef,
+        extractVarName: varName,
+        extractTargetPath: targetPath,
+        extractSourceKey: key,
+    };
+}
+function planMcpServer(name, def, existing, homeDir, policy) {
+    // A `staticEnv` match is extracted (trellis-migrate-extract-static-env-secrets):
+    // its own dict key is a natural variable name, and `env`/`env_vars` is
+    // the one shape proven to resolve back to a real value for every
+    // consumer (pi-bridge, claude-code, codex, kiro). A literal anywhere
+    // else (`command`/`url`/`args`/`headers`) has either no natural name to
+    // extract to, or no `${VAR}` resolution mechanism proven across every
+    // consumer — a fake reference there would be strictly worse than the
+    // literal it replaced (an agent silently failing to connect instead of
+    // the source agent's own working config). Accepted as ordinary literal
+    // config instead (design.md D11), same as if no match were found at
+    // all; `secrets audit` keeps flagging canonical itself so this isn't
+    // silent.
+    const secretMatch = findLiteralSecret(def);
+    if (secretMatch?.field === "staticEnv") {
+        return planStaticEnvExtraction(name, def, existing, homeDir, policy, secretMatch.key);
+    }
     if (existing === undefined) {
         return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
     }
@@ -176,10 +296,10 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
     if (wants("mcp")) {
         const reader = MCP_READERS[agent];
         if (reader) {
-            const canonicalServers = loadCanonicalSource(homeDir).mcp.servers;
+            const canonical = loadCanonicalSource(homeDir);
             const { entries, unsupported } = reader(homeDir);
             for (const { name, def } of entries) {
-                items.push(planMcpServer(name, def, canonicalServers[name]));
+                items.push(planMcpServer(name, def, canonical.mcp.servers[name], homeDir, canonical.secretsPolicy));
             }
             for (const { name, reason } of unsupported) {
                 items.push({ kind: "mcp", name, action: "skip-unsupported", detail: reason });
@@ -188,10 +308,32 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
     }
     return { agent, present: true, items };
 }
+/**
+ * Re-reads the source agent's real MCP entries at apply time to recover
+ * `sourceKey`'s current value — deliberately not carried on the plan item
+ * itself (design.md D9), so it never rides through a `--json`/`--dry-run`
+ * plan object a caller might log or serialize. A cheap, synchronous
+ * re-read (the same `MCP_READERS` function `collectMigratePlan` already
+ * called), not a second network/probe round-trip. `sourceKey` (the
+ * source's own dict key) and `varName` (the synthesized name it's
+ * written under, design.md D11) are looked up and written under
+ * separately — they are not, in general, the same string.
+ */
+function applyStaticEnvExtraction(agent, serverName, sourceKey, varName, targetPath, homeDir) {
+    const reader = MCP_READERS[agent];
+    const realValue = reader?.(homeDir).entries.find((e) => e.name === serverName)?.def.staticEnv?.[sourceKey];
+    if (realValue === undefined)
+        return; // source changed between plan and apply; nothing left to extract
+    if (targetPath === defaultLocalSecretsEnvFilePath(homeDir)) {
+        ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env");
+    }
+    writeLocalSecretValue(targetPath, varName, realValue);
+    writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE });
+}
 export function applyMigratePlan(plan, homeDir = homedir()) {
     const canonicalRoot = join(homeDir, ".trellis");
     for (const item of plan.items) {
-        if (item.action !== "create" && item.action !== "reclassify")
+        if (item.action !== "create" && item.action !== "reclassify" && item.action !== "extract-secret")
             continue;
         if (item.kind === "skill" && item.sourceDir) {
             const dest = join(canonicalRoot, "skills", item.name);
@@ -204,8 +346,19 @@ export function applyMigratePlan(plan, homeDir = homedir()) {
         }
         else if (item.kind === "mcp" && item.mcpDef) {
             upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef);
+            if (item.action === "extract-secret" && item.extractVarName && item.extractTargetPath && item.extractSourceKey) {
+                applyStaticEnvExtraction(plan.agent, item.name, item.extractSourceKey, item.extractVarName, item.extractTargetPath, homeDir);
+            }
         }
     }
+    // Runs every real (non-dry-run) migrate invocation, not just the one that
+    // performed a fresh extraction — a machine that already extracted a
+    // secret before this shell-wiring existed gets fixed the next time
+    // migrate runs at all, not only on its next brand-new extraction.
+    const envFile = loadCanonicalSource(homeDir).secretsPolicy.envFile;
+    if (envFile) {
+        ensureShellEnvSource(defaultShellRcPath(homeDir), envFile);
+    }
 }
 const ONLY_VALUES = ["skills", "instructions", "mcp"];
 function isMigrateOnlyValue(value) {

package/dist/commands/onboard.js

@@ -69,9 +69,13 @@ function logProgress(opts, stage) {
     const index = PROGRESS_STAGES.indexOf(stage) + 1;
     console.error(`[${index}/${PROGRESS_STAGES.length}] ${stage}`);
 }
+/** A count only, never the full skill name list — with 30+ skills this
+ * used to render as one unreadable, wrapping wall of text per row
+ * (found via a real mirasim terminal session). The full names are still
+ * available from `trellis doctor`/`--json`; a picker row's job is to
+ * let you tell agents apart at a glance, not enumerate everything. */
 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}`;
+    return `${s.agent} — ${s.skillCount} skill(s), instructions: ${s.hasRealInstructions ? "yes" : "no"}, mcp: ${s.mcpServerCount}`;
 }
 /** Numbered-typing fallback (trellis-onboard-interactive-picker design.md
  * D2) — used only when the terminal can't support the raw-mode picker

package/dist/commands/onboardVerdict.js

@@ -42,12 +42,25 @@ export function normalizeMigrateVerdict(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);
+        if (item.action === "conflict") {
+            const verdict = { stage: "migrate", severity: "blocked", message: item.detail };
+            if (item.remediation)
+                verdict.remediation = item.remediation;
+            items.push(verdict);
+        }
+        else if (item.action === "extract-secret") {
+            // The run succeeded — never `blocked` — but stands as a standing
+            // reminder, not a silent success: migrate never writes to the
+            // source agent's own file (design.md D2), so it still holds the
+            // real value in plaintext forever, independent of this extraction
+            // (trellis-migrate-extract-static-env-secrets design.md D8).
+            items.push({
+                stage: "migrate",
+                severity: "warning",
+                message: item.detail,
+                remediation: `the source agent's own configuration for "${item.name}" was not modified and may still hold "${item.extractVarName}"'s real value in plaintext — clean it up by hand if you want it gone from there too`,
+            });
+        }
     }
     return items;
 }
@@ -103,7 +116,7 @@ export function normalizeSecretsAuditVerdict(report) {
         return [];
     return report.findings.map((finding) => {
         const item = { stage: "secrets audit", severity: "blocked", message: `${finding.file}: ${finding.detail}` };
-        if (finding.agent !== "environment")
+        if (finding.agent !== "environment" && finding.agent !== "canonical")
             item.agent = finding.agent;
         return item;
     });

package/dist/commands/secretsAudit.d.ts

@@ -1,15 +1,23 @@
 /**
  * `trellis secrets audit` — reads every present, MCP-capable agent's real
- * config file (never the canonical source) and checks it against
- * `CanonicalSource.secretsPolicy`: a literal-value scan against
- * `rejectPatterns`, and a declared-env-var-name check against
- * `allowedVars`. Also checks, agent-agnostically, whether every env var
- * name declared across canonical `mcp.servers[*].env` actually resolves
- * to a value via the same `resolveSecretEnv` the pi bridge uses
- * (trellis-secrets-env-management) — authoritative for pi, a best-effort
- * proxy for the other three (design.md D3 in that change). Read-only —
- * never writes anything. Fails non-zero on any finding
- * (trellis-secrets-audit-p3).
+ * config file and checks it against `CanonicalSource.secretsPolicy`: a
+ * literal-value scan against `rejectPatterns`, and a declared-env-var-name
+ * check against `allowedVars`. Also checks, agent-agnostically, whether
+ * every env var name declared across canonical `mcp.servers[*].env`
+ * actually resolves to a value via the same `resolveSecretEnv` the pi
+ * bridge uses (trellis-secrets-env-management) — authoritative for pi, a
+ * best-effort proxy for the other three (design.md D3 in that change).
+ *
+ * Also scans canonical's own `mcp/servers.yaml` for the reject-pattern
+ * literal-value check (trellis-migrate-extract-static-env-secrets design.md
+ * D11): a literal in `command`/`url`/`args`/`headers` is now accepted into
+ * canonical by `migrate` rather than refused (no natural name to extract
+ * to, or no `${VAR}` resolution proven for every consumer), so canonical
+ * is no longer guaranteed clean by construction the way it used to be —
+ * this keeps that acceptance from being silent. Never the
+ * unexpected-var-name check, which is about agent-native serialized
+ * `env`/`env_vars` syntax specifically. Read-only — never writes
+ * anything. Fails non-zero on any finding (trellis-secrets-audit-p3).
  */
 import type { AgentId } from "../core/types.js";
 export interface RunSecretsAuditOptions {
@@ -23,8 +31,9 @@ export interface RunSecretsAuditOptions {
 }
 export interface SecretsFinding {
     /** "environment" for `missing-env-value` — that check isn't scoped to
-     * any single agent's config file (see module doc comment). */
-    agent: AgentId | "environment";
+     * any single agent's config file. "canonical" for a literal found in
+     * `~/.trellis/mcp/servers.yaml` itself (see module doc comment). */
+    agent: AgentId | "environment" | "canonical";
     file: string;
     kind: "literal-secret" | "unexpected-var-name" | "missing-env-value";
     detail: string;

package/dist/commands/secretsAudit.js

@@ -1,15 +1,23 @@
 /**
  * `trellis secrets audit` — reads every present, MCP-capable agent's real
- * config file (never the canonical source) and checks it against
- * `CanonicalSource.secretsPolicy`: a literal-value scan against
- * `rejectPatterns`, and a declared-env-var-name check against
- * `allowedVars`. Also checks, agent-agnostically, whether every env var
- * name declared across canonical `mcp.servers[*].env` actually resolves
- * to a value via the same `resolveSecretEnv` the pi bridge uses
- * (trellis-secrets-env-management) — authoritative for pi, a best-effort
- * proxy for the other three (design.md D3 in that change). Read-only —
- * never writes anything. Fails non-zero on any finding
- * (trellis-secrets-audit-p3).
+ * config file and checks it against `CanonicalSource.secretsPolicy`: a
+ * literal-value scan against `rejectPatterns`, and a declared-env-var-name
+ * check against `allowedVars`. Also checks, agent-agnostically, whether
+ * every env var name declared across canonical `mcp.servers[*].env`
+ * actually resolves to a value via the same `resolveSecretEnv` the pi
+ * bridge uses (trellis-secrets-env-management) — authoritative for pi, a
+ * best-effort proxy for the other three (design.md D3 in that change).
+ *
+ * Also scans canonical's own `mcp/servers.yaml` for the reject-pattern
+ * literal-value check (trellis-migrate-extract-static-env-secrets design.md
+ * D11): a literal in `command`/`url`/`args`/`headers` is now accepted into
+ * canonical by `migrate` rather than refused (no natural name to extract
+ * to, or no `${VAR}` resolution proven for every consumer), so canonical
+ * is no longer guaranteed clean by construction the way it used to be —
+ * this keeps that acceptance from being silent. Never the
+ * unexpected-var-name check, which is about agent-native serialized
+ * `env`/`env_vars` syntax specifically. Read-only — never writes
+ * anything. Fails non-zero on any finding (trellis-secrets-audit-p3).
  */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -57,6 +65,26 @@ function findMissingEnvValues(servers, policy) {
         detail: `"${name}" is declared by a canonical MCP server's env but has no resolvable value`,
     }));
 }
+/**
+ * Reject-pattern-only scan of canonical's own `mcp/servers.yaml` (design.md
+ * D11) — no `unexpected-var-name` check here, that one is specifically
+ * about names extracted from an agent's own serialized `env`/`env_vars`
+ * syntax, not canonical's `env:` name list (which holding a name matching
+ * a reject pattern would be an absurd false positive, not a real finding).
+ */
+function auditCanonicalServersYaml(homeDir, policy) {
+    const file = join(homeDir, ".trellis", "mcp", "servers.yaml");
+    if (!existsSync(file))
+        return [];
+    const content = readFileSync(file, "utf-8");
+    const findings = [];
+    for (const pattern of policy.rejectPatterns) {
+        if (pattern.test(content)) {
+            findings.push({ agent: "canonical", file, kind: "literal-secret", detail: `matches reject pattern ${pattern}` });
+        }
+    }
+    return findings;
+}
 function auditFile(agent, file, content, policy, extractNames) {
     const findings = [];
     for (const pattern of policy.rejectPatterns) {
@@ -88,6 +116,7 @@ export async function collectSecretsAuditReport(opts = {}) {
         findings.push(...auditFile(agent.id, file, content, canonical.secretsPolicy, agent.extractNames));
     }
     findings.push(...findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
+    findings.push(...auditCanonicalServersYaml(homeDir, canonical.secretsPolicy));
     return { findings };
 }
 export async function runSecretsAudit(opts = {}) {

package/dist/core/canonical.d.ts

@@ -57,6 +57,52 @@ export type McpMode = {
  * (design.md D3) — never left for the caller to remember.
  */
 export declare function writeMcpModeYaml(path: string, mode: McpMode): ServersYamlWriteResult;
+export type SecretsPolicyWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D6) — the
+ * missing writer for `secrets.policy.yaml`, mirroring `writeMcpModeYaml`'s
+ * `Document`-based, comment-preserving mechanism. Sets `env_file` only
+ * when it is not already set — an already-configured value is a
+ * deliberate prior choice (design.md D3) and `resolveSecretEnv` treats
+ * `env_file` as the sole source once set, so silently repointing it
+ * would orphan every name already resolving from the old file. Appends
+ * `varName` to `allowed_vars` only if not already present (dedup, same
+ * "already there is a no-op" rule every other Trellis writer follows).
+ */
+export declare function writeSecretsPolicyExtraction(path: string, extraction: {
+    varName: string;
+    envFilePath: string;
+}): SecretsPolicyWriteResult;
+/**
+ * Ensures one exact line is present in a `.gitignore` file, creating the
+ * file if it doesn't exist yet — idempotent (a no-op if the line is
+ * already there), never disturbing any other line
+ * (trellis-migrate-extract-static-env-secrets design.md D5). Called
+ * lazily, immediately before the first real write to the local secrets
+ * file migrate's static-env extraction produces — never from `trellis
+ * init`'s own bootstrap, so a machine that never extracts a secret never
+ * gains this file at all.
+ */
+export declare function ensureGitignoreEntry(gitignorePath: string, line: string): void;
+/**
+ * Ensures a shell rc file sources the local secrets env file on every new
+ * shell — one generic pointer block, appended once, idempotent (detected
+ * by its own marker comment, never duplicated). Deliberately never writes
+ * a literal secret value into the rc file: the block only names the path
+ * to the real `NAME=value` file migrate's extraction already writes and
+ * protects — adding a new variable later means editing that one file, the
+ * rc file never needs a second edit (trellis-migrate-extract-static-env-secrets
+ * design.md D10). `set -a`/`set +a` auto-exports the plain dotenv-format
+ * lines `parseDotenv` already expects, so that format never needs an
+ * `export` prefix of its own.
+ */
+export declare function ensureShellEnvSource(rcPath: string, envFilePath: string): void;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use

package/dist/core/canonical.js

@@ -4,10 +4,10 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
-import { isMap, parse as parseYaml, parseDocument } from "yaml";
+import { basename, dirname, join } from "node:path";
+import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
 function fromServerDefYaml(def) {
     const { static_env, env_aliases, ...rest } = def;
@@ -126,8 +126,14 @@ function fromGatewayYaml(gateway) {
  * one-line, local fix — it never touches any sibling entry's own style,
  * so a file someone deliberately kept flow-style elsewhere is untouched.
  */
+/** Handles both a map (`servers: {}`) and a sequence (`allowed_vars: []`)
+ * — `trellis init`'s starter files use flow style for both kinds of
+ * still-empty collection, and inserting into either one via `Document`
+ * methods keeps rendering it as flow otherwise (same real bug this
+ * function was first written to fix, just a second collection type
+ * hitting it — trellis-migrate-extract-static-env-secrets). */
 function forceBlockStyle(node) {
-    if (isMap(node)) {
+    if (isMap(node) || isSeq(node)) {
         node.flow = false;
     }
 }
@@ -222,6 +228,84 @@ function loadSecretsPolicyYaml(path, homeDir) {
         envFile: parsed.env_file ? parsed.env_file.replace(/^~(?=$|\/)/, homeDir) : undefined,
     };
 }
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D6) — the
+ * missing writer for `secrets.policy.yaml`, mirroring `writeMcpModeYaml`'s
+ * `Document`-based, comment-preserving mechanism. Sets `env_file` only
+ * when it is not already set — an already-configured value is a
+ * deliberate prior choice (design.md D3) and `resolveSecretEnv` treats
+ * `env_file` as the sole source once set, so silently repointing it
+ * would orphan every name already resolving from the old file. Appends
+ * `varName` to `allowed_vars` only if not already present (dedup, same
+ * "already there is a no-op" rule every other Trellis writer follows).
+ */
+export function writeSecretsPolicyExtraction(path, extraction) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (doc.get("env_file") === undefined) {
+        doc.set("env_file", extraction.envFilePath);
+    }
+    // `.get()` returns the raw Seq node for a collection, not a plain
+    // array — `.toJS()` on the whole document is the reliable way to read
+    // a fully-unwrapped value back out before deciding whether to append.
+    const currentAllowedVars = (doc.toJS().allowed_vars ?? []);
+    if (!currentAllowedVars.includes(extraction.varName)) {
+        doc.set("allowed_vars", [...currentAllowedVars, extraction.varName]);
+        forceBlockStyle(doc.get("allowed_vars", true));
+    }
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
+/**
+ * Ensures one exact line is present in a `.gitignore` file, creating the
+ * file if it doesn't exist yet — idempotent (a no-op if the line is
+ * already there), never disturbing any other line
+ * (trellis-migrate-extract-static-env-secrets design.md D5). Called
+ * lazily, immediately before the first real write to the local secrets
+ * file migrate's static-env extraction produces — never from `trellis
+ * init`'s own bootstrap, so a machine that never extracts a secret never
+ * gains this file at all.
+ */
+export function ensureGitignoreEntry(gitignorePath, line) {
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    const lines = existing.split("\n").map((l) => l.trim());
+    if (lines.includes(line))
+        return;
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    writeFileSync(gitignorePath, `${existing}${separator}${line}\n`);
+}
+const SHELL_ENV_SOURCE_MARKER = "# >>> trellis mcp secrets >>>";
+const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
+/**
+ * Ensures a shell rc file sources the local secrets env file on every new
+ * shell — one generic pointer block, appended once, idempotent (detected
+ * by its own marker comment, never duplicated). Deliberately never writes
+ * a literal secret value into the rc file: the block only names the path
+ * to the real `NAME=value` file migrate's extraction already writes and
+ * protects — adding a new variable later means editing that one file, the
+ * rc file never needs a second edit (trellis-migrate-extract-static-env-secrets
+ * design.md D10). `set -a`/`set +a` auto-exports the plain dotenv-format
+ * lines `parseDotenv` already expects, so that format never needs an
+ * `export` prefix of its own.
+ */
+export function ensureShellEnvSource(rcPath, envFilePath) {
+    const existing = existsSync(rcPath) ? readFileSync(rcPath, "utf-8") : "";
+    if (existing.includes(SHELL_ENV_SOURCE_MARKER))
+        return;
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    const block = `${SHELL_ENV_SOURCE_MARKER}\nif [ -f "${envFilePath}" ]; then\n  set -a\n  source "${envFilePath}"\n  set +a\nfi\n${SHELL_ENV_SOURCE_END_MARKER}\n`;
+    mkdirSync(dirname(rcPath), { recursive: true });
+    writeFileSync(rcPath, `${existing}${separator}${block}`);
+}
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
  * all four agents," the default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */

package/dist/lib/secretEnv.d.ts

@@ -17,3 +17,19 @@ export declare function parseDotenv(content: string): Record<string, string>;
  * reads `process.env` directly, identical to every pre-existing caller.
  */
 export declare function resolveSecretEnv(names: string[], policy: SecretsPolicy): Record<string, string | undefined>;
+export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict";
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D4) — appends
+ * one `NAME=value` line to a dotenv-format file in exactly the shape
+ * `parseDotenv` above already reads, creating the file (and its parent
+ * directory) if neither exists yet. Idempotent, the same three-way
+ * split every other Trellis writer uses: the name is absent (create),
+ * already present with the identical value (no-op — re-running migrate
+ * must not duplicate the line), or already present with a *different*
+ * value (conflict, left untouched — the file may hold a value the user
+ * already rotated by hand since the last run; silently overwriting it
+ * would be exactly the kind of value-clobbering this whole feature
+ * exists to prevent, just relocated to a new file).
+ */
+export declare function writeLocalSecretValue(path: string, name: string, value: string): WriteLocalSecretOutcome;

package/dist/lib/secretEnv.js

@@ -8,7 +8,8 @@
  * dotenv library's quoting/escaping/interpolation rules are more than
  * this narrow need requires (design.md D4).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
 const LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
 export function parseDotenv(content) {
     const result = {};
@@ -44,3 +45,28 @@ export function resolveSecretEnv(names, policy) {
     }
     return result;
 }
+/**
+ * `trellis migrate`'s static-env secret extraction
+ * (trellis-migrate-extract-static-env-secrets design.md D4) — appends
+ * one `NAME=value` line to a dotenv-format file in exactly the shape
+ * `parseDotenv` above already reads, creating the file (and its parent
+ * directory) if neither exists yet. Idempotent, the same three-way
+ * split every other Trellis writer uses: the name is absent (create),
+ * already present with the identical value (no-op — re-running migrate
+ * must not duplicate the line), or already present with a *different*
+ * value (conflict, left untouched — the file may hold a value the user
+ * already rotated by hand since the last run; silently overwriting it
+ * would be exactly the kind of value-clobbering this whole feature
+ * exists to prevent, just relocated to a new file).
+ */
+export function writeLocalSecretValue(path, name, value) {
+    const existingContent = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const existing = parseDotenv(existingContent);
+    if (Object.hasOwn(existing, name)) {
+        return existing[name] === value ? "already-present" : "conflict";
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const separator = existingContent.length > 0 && !existingContent.endsWith("\n") ? "\n" : "";
+    appendFileSync(path, `${separator}${name}=${value}\n`);
+    return "created";
+}

package/dist/lib/terminalPicker.d.ts

@@ -28,6 +28,27 @@ export declare function canUseInteractivePicker(streams?: PickerStreams): boolea
 export declare function nextIndex(current: number, delta: number, length: number): number;
 /** Pure single-index toggle — exported for direct unit testing. */
 export declare function toggled(checked: readonly boolean[], index: number): boolean[];
+/** A row's *visible* width, excluding the color codes wrapped around it —
+ * they add characters that occupy zero terminal columns. Needed to
+ * compute how many physical lines a row actually wraps to (see
+ * `physicalLineCount`); counting `row.length` directly would overcount
+ * and under-clear on the next redraw. */
+export declare function visibleWidth(row: string): number;
+/**
+ * How many physical terminal lines one logical row occupies once the
+ * terminal wraps it — `Math.ceil(visibleWidth / columns)`, at least 1.
+ * `clearLines`/`moveCursorUp` need this, not `rows.length`: a picker
+ * item whose rendered text is longer than the terminal is wide (a long
+ * agent summary, a narrow terminal, or both) wraps onto more than one
+ * physical line, and erasing/moving by the *logical* row count instead
+ * leaves the wrapped remainder of the previous frame on screen — found
+ * via a real mirasim terminal session where a (much longer,
+ * pre-truncation) row's wrapped tail was never cleared, so every redraw
+ * appended a new, only-partially-overwritten copy instead of replacing
+ * the old one.
+ */
+export declare function physicalLineCount(row: string, columns: number): number;
+export declare function totalPhysicalLines(rows: readonly string[], columns: number): number;
 /**
  * Single-select: Up/Down/j/k moves the highlight, Enter confirms. Resolves
  * the confirmed index, or `null` on Ctrl+C cancel. Caller (onboard.ts)

package/dist/lib/terminalPicker.js

@@ -40,6 +40,45 @@ const ESC = "\u001b";
 const CTRL_C = "\u0003";
 const HIDE_CURSOR = `${ESC}[?25l`;
 const SHOW_CURSOR = `${ESC}[?25h`;
+const ANSI_ESCAPE_RE = /\x1b\[[0-9;]*m/g;
+/** A row's *visible* width, excluding the color codes wrapped around it —
+ * they add characters that occupy zero terminal columns. Needed to
+ * compute how many physical lines a row actually wraps to (see
+ * `physicalLineCount`); counting `row.length` directly would overcount
+ * and under-clear on the next redraw. */
+export function visibleWidth(row) {
+    return row.replace(ANSI_ESCAPE_RE, "").length;
+}
+/**
+ * How many physical terminal lines one logical row occupies once the
+ * terminal wraps it — `Math.ceil(visibleWidth / columns)`, at least 1.
+ * `clearLines`/`moveCursorUp` need this, not `rows.length`: a picker
+ * item whose rendered text is longer than the terminal is wide (a long
+ * agent summary, a narrow terminal, or both) wraps onto more than one
+ * physical line, and erasing/moving by the *logical* row count instead
+ * leaves the wrapped remainder of the previous frame on screen — found
+ * via a real mirasim terminal session where a (much longer,
+ * pre-truncation) row's wrapped tail was never cleared, so every redraw
+ * appended a new, only-partially-overwritten copy instead of replacing
+ * the old one.
+ */
+export function physicalLineCount(row, columns) {
+    if (columns <= 0)
+        return 1;
+    return Math.max(1, Math.ceil(visibleWidth(row) / columns));
+}
+export function totalPhysicalLines(rows, columns) {
+    return rows.reduce((sum, row) => sum + physicalLineCount(row, columns), 0);
+}
+/** `output.columns` only exists on a real TTY; test-injected plain
+ * streams (`PickerStreams`) have none. Defaulting to 80 — the standard
+ * terminal width, and this project's own test fixtures — keeps the
+ * wrap-aware math above exercised (and testable) even without a real
+ * terminal, rather than silently reverting to "assume no row ever wraps"
+ * for every non-TTY stream. */
+function columnsOf(output) {
+    return output.columns ?? 80;
+}
 /** Parses one raw input chunk into a single logical key — arrow escape
  * sequences, j/k, space, enter, or Ctrl+C. Anything else is ignored. */
 function parseKey(chunk) {
@@ -92,16 +131,30 @@ function clearLines(output, lines) {
     }
     moveCursorUp(output, lines - 1);
 }
-function renderRows(output, rows, previousRowCount) {
-    if (previousRowCount > 0) {
-        clearLines(output, previousRowCount);
+/**
+ * `previousPhysicalLines` must be the actual on-screen line count the
+ * *previous* call to this function produced (`totalPhysicalLines` of
+ * that frame's rows), not `rows.length` — see `physicalLineCount`'s doc
+ * comment for why a wrapped row makes those two numbers diverge.
+ */
+function renderRows(output, rows, previousPhysicalLines) {
+    if (previousPhysicalLines > 0) {
+        clearLines(output, previousPhysicalLines);
     }
     for (const row of rows) {
         output.write(`${row}\n`);
     }
 }
+/**
+ * A real foreground color (bold cyan), not just reverse video —
+ * differentiating the highlighted row must not depend on a host
+ * terminal correctly inverting fore/background, which a real mirasim
+ * terminal session showed no visible effect from at all. The `>`/`  `
+ * marker stays regardless, as a plain-text fallback for a host that
+ * strips color entirely.
+ */
 function highlightRow(text, isHighlighted) {
-    return isHighlighted ? `> ${ESC}[7m${text}${ESC}[0m` : `  ${text}`;
+    return isHighlighted ? `> ${ESC}[1;36m${text}${ESC}[0m` : `  ${text}`;
 }
 /**
  * Single-select: Up/Down/j/k moves the highlight, Enter confirms. Resolves
@@ -115,11 +168,12 @@ export async function runSingleSelectPicker(items, streams = defaultStreams()) {
     return withRawMode(streams, () => {
         return new Promise((resolve) => {
             let highlighted = 0;
-            let rowCount = 0;
+            let physicalLines = 0;
+            const columns = columnsOf(output);
             const draw = () => {
                 const rows = items.map((label, i) => highlightRow(label, i === highlighted));
-                renderRows(output, rows, rowCount);
-                rowCount = rows.length;
+                renderRows(output, rows, physicalLines);
+                physicalLines = totalPhysicalLines(rows, columns);
             };
             draw();
             const onData = (chunk) => {
@@ -157,11 +211,12 @@ export async function runMultiSelectPicker(items, initiallyChecked, streams = de
         return new Promise((resolve) => {
             let highlighted = 0;
             let checked = [...initiallyChecked];
-            let rowCount = 0;
+            let physicalLines = 0;
+            const columns = columnsOf(output);
             const draw = () => {
                 const rows = items.map((label, i) => highlightRow(`[${checked[i] ? "x" : " "}] ${label}`, i === highlighted));
-                renderRows(output, rows, rowCount);
-                rowCount = rows.length;
+                renderRows(output, rows, physicalLines);
+                physicalLines = totalPhysicalLines(rows, columns);
             };
             draw();
             const onData = (chunk) => {

package/dist/pi-bridge/bundle.js

@@ -55,7 +55,7 @@ var require_identity = __commonJS({
     var isMap2 = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === MAP;
     var isPair = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === PAIR;
     var isScalar = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === SCALAR;
-    var isSeq = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === SEQ;
+    var isSeq2 = (node2) => !!node2 && typeof node2 === "object" && node2[NODE_TYPE] === SEQ;
     function isCollection(node2) {
       if (node2 && typeof node2 === "object")
         switch (node2[NODE_TYPE]) {
@@ -92,7 +92,7 @@ var require_identity = __commonJS({
     exports.isNode = isNode;
     exports.isPair = isPair;
     exports.isScalar = isScalar;
-    exports.isSeq = isSeq;
+    exports.isSeq = isSeq2;
   }
 });
 
@@ -15140,9 +15140,9 @@ import { homedir as homedir2 } from "node:os";
 
 // src/core/canonical.ts
 var import_yaml = __toESM(require_dist(), 1);
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 // src/core/types.ts
 var ALL_AGENTS = [
@@ -15329,7 +15329,7 @@ function codexBearerTokenEnvVar(def) {
 }
 
 // src/lib/secretEnv.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "node:fs";
 var LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
 function parseDotenv(content) {
   const result = {};
@@ -15379,13 +15379,17 @@ var DANGEROUS_LITERAL_PATTERNS = [
   { label: "mcp-router token (mcpr_)", pattern: /mcpr_/ }
 ];
 function findLiteralSecret(def) {
-  const candidates = [def.command, def.url, ...def.args ?? [], ...Object.values(def.headers ?? {}), ...Object.values(def.staticEnv ?? {})].filter(
-    (v) => typeof v === "string"
-  );
-  for (const candidate of candidates) {
+  const candidates = [
+    ...def.command !== void 0 ? [{ value: def.command, field: "command" }] : [],
+    ...def.url !== void 0 ? [{ value: def.url, field: "url" }] : [],
+    ...(def.args ?? []).map((value) => ({ value, field: "args" })),
+    ...Object.entries(def.headers ?? {}).map(([key, value]) => ({ value, field: "headers", key })),
+    ...Object.entries(def.staticEnv ?? {}).map(([key, value]) => ({ value, field: "staticEnv", key }))
+  ];
+  for (const { value, field, key } of candidates) {
     for (const { label, pattern } of DANGEROUS_LITERAL_PATTERNS) {
-      if (pattern.test(candidate)) {
-        return label;
+      if (pattern.test(value)) {
+        return { label, field, key };
       }
     }
   }
@@ -15432,11 +15436,11 @@ function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
       conflicts.push({ name, message: collisionMessage(name, agentId), remediation: collisionRemediation(name) });
       continue;
     }
-    const secretLabel = findLiteralSecret(def);
-    if (secretLabel) {
+    const secretMatch = findLiteralSecret(def);
+    if (secretMatch?.field === "staticEnv") {
       conflicts.push({
         name,
-        message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) \u2014 configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+        message: `refusing to write MCP server "${name}": a value matches a known-dangerous literal pattern (${secretMatch.label}) \u2014 configs must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
         remediation: `replace the literal value in servers.yaml with a \`\${VAR_NAME}\` reference and put the real value wherever secrets.policy.yaml resolves it from`
       });
       continue;

package/docs/getting-started.md

@@ -288,6 +288,81 @@ Two known fidelity limits, named rather than silently worked around:
   server was hand-authored with some other shape, it migrates whatever
   is actually there, same as any other field.
 
+**A real credential value found in a source agent's config is extracted,
+not just refused.** If a source agent stores a real credential as a
+literal (not a `${VAR}` reference) under a server's `staticEnv`-shaped
+field — the exact real case this project hit: kiro's own `mcp-router`
+entry had its token hardcoded — `migrate` moves the real value to
+`~/.trellis/mcp/servers.local.env` (a sibling of `servers.yaml`,
+automatically `.gitignore`d — never something you need to protect by
+hand), references it from canonical as `${THE_NAME}` instead of the
+literal, and adds the name to `secrets.policy.yaml`'s `allowed_vars`. If
+`secrets.policy.yaml` already has its own `env_file` configured, the
+value goes there instead, respecting your existing setup rather than
+creating a second file.
+
+```
+$ trellis migrate --from kiro --only mcp
+migrate --from kiro
+  [extract-secret] mcp server "mcp-router" — will extract "MCPR_TOKEN" to
+  ~/.trellis/mcp/servers.local.env as "TRELLIS_MCP_ROUTER_MCPR_TOKEN",
+  referencing it from servers.yaml instead of holding the literal value
+```
+
+The name it's extracted under is `TRELLIS_<SERVER>_<KEY>`, never the
+bare source key alone — a project-wide prefix rules out colliding with
+anything already in your own environment, and the server-name segment
+rules out two Trellis-managed servers colliding with each other over
+the same key. A server extracted before this naming scheme existed
+keeps working under its original name — recognized by the value it
+resolves to, not by re-deriving today's name and expecting an exact
+match, so it's never silently re-extracted under a second name.
+
+**The source agent's own file is never touched** — kiro's real
+`~/.kiro/settings/mcp.json` keeps its literal value exactly as it was,
+forever; `trellis secrets audit` will keep flagging that file on every
+future run, which is correct and expected — cleaning it up by hand is
+your call, not something this command does for you.
+
+**A credential found anywhere *other* than `staticEnv`** (a server's
+`command`, `url`, `args`, or `headers`) **is accepted as ordinary
+literal config, not refused and not extracted.** Neither a natural
+variable name (staticEnv's own dict key provides one; these fields
+don't) nor a proven `${VAR}` resolution mechanism exists for these
+fields across every consumer (pi-bridge, claude-code, codex, kiro) —
+faking a reference would produce a config that looks safe but silently
+fails to connect for at least some of them, worse than the literal it
+replaced. `trellis secrets audit` also scans canonical's own
+`mcp/servers.yaml` for this case (`agent: "canonical"` in its findings),
+so accepting the literal is never silent either.
+
+**The `${VAR}` reference `mcp sync` writes into an agent's native config
+only works once that name is actually in the environment that agent's
+own process reads from** — extraction alone doesn't get you there, it
+just gets the real value out of canonical. So `migrate` also ensures
+your shell rc (`~/.zshrc`/`~/.bash_profile`/`~/.profile`, picked from
+`$SHELL`) sources `servers.local.env`, appending one generic,
+idempotent block — never a literal secret line:
+
+```
+# >>> trellis mcp secrets >>>
+if [ -f "~/.trellis/mcp/servers.local.env" ]; then
+  set -a
+  source "~/.trellis/mcp/servers.local.env"
+  set +a
+fi
+# <<< trellis mcp secrets <<<
+```
+
+Adding another secret later only ever means editing
+`servers.local.env` — the rc file never needs a second edit. This runs
+on every real `migrate` invocation whenever `secrets.policy.yaml` has an
+`env_file`, not just the run that performed the extraction, so a machine
+that already extracted a secret before this existed gets wired the next
+time `migrate` runs at all. A new shell (or restarting the agent
+process) is what actually picks up the newly-exported variable — this
+only ensures the rc file is ready to hand it over.
+
 ## Starting from nothing
 
 Skip migrate. Edit `~/.trellis/agents.md` and add skills under

package/docs/roadmap.md

@@ -954,6 +954,7 @@ tests passing.
 | P21 | ✅ MCP gateway hosting: collapses each agent's MCP config to ONE native stdio entry (`trellis mcp-gateway --agent <id>`) that Trellis itself spawns — no Docker, no daemon, no lifecycle command. Four third-party gateways were evaluated and excluded on hard constraints (MetaMCP is Docker-only; mcp-local-hub is Windows-only today; `@samanhappy/mcphub` is a 43-dependency authenticated web product with no importable SDK surface; `@pcandido/mcphub` has correct OAuth but zero `${VAR}` expansion in its stdio `env`, verified by inspecting what a spawned child actually received — adopting it would mean plaintext secrets or a second resolution path outside `secrets audit`). Built instead on `pi-bridge`'s already-proven connect logic, extracted to `src/lib/mcpConnect.ts`, behind a `GatewayBackend` seam so the confirmed next step — one shared service for all agents, with the per-session process becoming a thin MCP-over-Unix-socket client — is a substitution at one construction site, with every agent's written config identical either way. Includes Trellis's own OAuth client (RFC 8414/9728 discovery, RFC 7591 DCR, RFC 7636 PKCE S256, refresh), tested against a hand-built Authorization Server that *enforces* those RFCs rather than rubber-stamping them; tokens live 0600 one-file-per-server outside canonical, never the OS keychain (macOS `security add-generic-password` measurably fails exit 152/154 with no GUI session — the gateway's exact context). Two bugs the design caught before shipping: the MCP SDK's stdio transport reports no EOF, so without explicit teardown every agent session would leak a gateway plus its whole upstream process set; and concurrent OAuth refresh silently kills a rotated refresh token, so it is serialized by a per-server lock. Remaining: the shared service itself (v2) | P2 |
 | P22 | ✅ Onboard closed loop: onboard used to stop the moment files were written, never checking whether any of it took effect, and never telling the user how the run went — a real run with a genuine sync conflict still ended its printed output on a later stage's unrelated green line. Two distinct fixes, not one: a **self-verification re-plan** (the mechanism that actually closes the loop) runs `sync`/`mcp sync` a second time, dry-run, immediately after their real apply, and treats anything still outstanding as its own blocking finding — `trellis doctor` was tried first and rejected for this job, since its six detectors compare agents against each other and never read canonical, so they cannot prove a write took effect even in principle. Doctor still runs, last, as a secondary whole-machine health scan (never `--probe-mcp` — the worst moment to spawn every configured MCP server is a user's first run of this command), with findings on an unmanaged agent demoted to a warning rather than hidden. Every stage's conflicts and findings normalize into one `VerdictItem[]`, printed as a terminal verdict block that is always the last thing on screen and always agrees with the exit code, each blocking item carrying a concrete remediation instead of a restatement of the problem. Also adds stage progress to stderr (never stdout, so `onboard > report.txt` stays exactly the report) and, on a real terminal, a `--dry-run` that ends by offering to apply (declining is the default; accepting re-plans against current state rather than replaying a now-stale preview) | P0 |
 | P23 | ✅ Onboard MCP mode + memory toggle: closes the last hand-editing gap — turning on gateway or hub mode, or the shared memory server, meant directly editing `~/.trellis/mcp/servers.yaml`'s top-level `hub`/`gateway` keys or its commented-out `memory:` example, since no command wrote them (`trellis mcp add`'s flags are all per-server). New `writeMcpModeYaml` in `src/core/canonical.ts` (`Document`-based, mirrors `upsertServerYaml`'s comment-preserving edit) plus `trellis onboard --mcp-mode direct\|hub\|gateway` (`--hub-url`, `--gateway-agents`) and `--memory on\|off` close it. Both follow onboard's existing managed-set idempotency shape rather than a new one: read current state first, omitting the flag always preserves it untouched with zero prompting — identical on a first run (nothing configured) and a later one (something already is), which is the actual point: one command for both, not a setup path and a separate reconfigure path. Deliberately flag-only, never an interactive picker (a mode change reroutes every managed agent's MCP transport at once — too wide a blast radius for Enter-mashing through a prompt sequence to trigger by accident); a one-line, non-prompting status line on a real terminal keeps the flags discoverable anyway. `--memory on` refuses outright if `"memory"` is already in `known_host_injected`, rather than writing a definition the very next `mcp sync` would refuse to propagate to any agent. Because mode/memory resolution runs before onboard's existing `mcp sync`/`memory sync` stages in the same chain, `trellis onboard --memory on` enables the server, syncs it to every managed agent, and populates it from canonical `memories/*.md` — all in one run | P17, P21, P22 |
+| P24 | ✅ Migrate static-env secret extraction: found via real-machine dogfooding — kiro's own real `mcp-router` server had its token hardcoded as a literal (not a `${VAR}` reference), which the existing literal-secret guard correctly refused to import, but the only path forward was three manual hand-edits across two files. A `staticEnv` match specifically (its own dict key is already a natural variable name) is now extracted automatically instead of refused: the real value moves to `~/.trellis/mcp/servers.local.env` (a sibling of `servers.yaml`, or an already-configured `secrets.policy.yaml` `env_file` if one exists — respecting a prior explicit choice rather than repointing it), canonical gets a `${NAME}` reference, `secrets.policy.yaml` gains the name in `allowed_vars`, and `~/.trellis/.gitignore` is ensured to protect the new file, all ensured lazily at the moment of the first real write, never as unconditional `init` bootstrap. `migrate` still never writes to the source agent's own file — kiro's real config keeps its literal forever, and `secrets audit` correctly keeps flagging it; extraction normalizes to a `warning` in onboard's verdict, not `blocked`, with a remediation naming that the source was left untouched. A literal found anywhere other than `staticEnv` (`command`/`url`/`args`/`headers` — no natural name to extract to) still refuses exactly as before. `findLiteralSecret` (`src/adapters/mcpPlan.ts`) now reports which field and dict key a match came from, closing a previously-undocumented spec gap for the unaffected refusal path in the same change. Also found via the same dogfooding, one commit later: extraction alone doesn't make the `${VAR}` reference `mcp sync` writes into an agent's native config actually resolve — that only happens once the name is in the environment that agent's own runtime reads from, which `servers.local.env` alone never reaches. `ensureShellEnvSource` (mirrors `ensureGitignoreEntry`'s idempotent marker-block shape) now appends one generic `set -a; source ...; set +a` pointer block to the user's shell rc (`~/.zshrc`/`~/.bash_profile`/`~/.profile` by `$SHELL`) — never a literal secret line — every real `migrate` run whenever `env_file` is set, retroactively wiring a machine that extracted before this existed. Separately, fixed a real incident this surfaced: no subcommand branch in `src/cli.ts` recognized `--help`/`-h`, so a stray `--help` silently ran the real command instead of printing usage — now short-circuits to usage text before any parsing, for every command. One more round: real-machine research (`mcpConnect.ts`, `jsonMcp.ts`, `tomlSection.ts`) found no `${VAR}` resolution mechanism proven across every consumer for `command`/`url`/`args`, and `headers` unverified for claude-code/kiro specifically — so `command`/`url`/`args`/`headers` literals are now *accepted* into canonical as ordinary config (both at `migrate`'s import boundary and `resolveMcpPlan`'s sync-out boundary), never refused and never faked into an unresolvable reference; `secrets audit` now also scans canonical's own `servers.yaml` for this (`agent: "canonical"`) so it's never silent. `staticEnv` extractions are now named `TRELLIS_<SERVER>_<KEY>` rather than the bare source key, to rule out cross-server or ambient-environment collisions — an already-extracted server (this project's own real `mcp-router`) is recognized as already-migrated by the *value* an existing reference resolves to, not by re-deriving today's naming scheme, so it keeps working under its original bare name without being renamed or re-extracted | P16, P18 |
 
 **Cross-machine / cloud sharing — confirmed future direction, not yet
 scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "A single source of capability for every coding agent — skills, MCP, subagents, memory, and secret policy, adapted natively into Claude Code, Codex, Kiro, and pi.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -28,7 +28,8 @@
     "typecheck": "tsc --noEmit",
     "pretest": "node scripts/build-pi-bridge.mjs",
     "test": "tsx --test \"test/unit/**/*.test.ts\"",
-    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+    "verify-pack": "node scripts/verify-pack.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test && npm run verify-pack"
   },
   "engines": {
     "node": ">=20"