agent-trellis 0.5.2 → 0.6.2

package/dist/commands/onboard.js

@@ -22,15 +22,17 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import { ALL_AGENTS } from "../core/types.js";
-import { loadCanonicalSource } from "../core/canonical.js";
+import { loadCanonicalSource, removeServerYaml, upsertServerYaml, writeMcpModeYaml } from "../core/canonical.js";
 import { INSTALL_HINTS, collectInitReport } from "./init.js";
 import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } from "./migrate.js";
 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 { applyMemorySync, collectMemorySyncResult, printMemorySyncResult, DEFAULT_MEMORY_SERVER_DEF, MEMORY_SERVER_NAME } 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}`;
@@ -213,6 +230,120 @@ function parseManagedSelection(raw, candidates) {
     }
     return { agents: [...new Set(agents)] };
 }
+/** Comma-separated agent ids only — unlike `parseManagedSelection`, no
+ * numbered-index shorthand, since `--gateway-agents` never has a
+ * numbered list on screen to refer back to (it's flag-only, never
+ * prompted; design.md D1/D4). */
+function parseAgentIdList(raw) {
+    const tokens = raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    const agents = [];
+    for (const token of tokens) {
+        if (!ALL_AGENTS.includes(token)) {
+            return { error: `"${token}" is not a valid agent id — use one of ${ALL_AGENTS.join(", ")}` };
+        }
+        agents.push(token);
+    }
+    return [...new Set(agents)];
+}
+/**
+ * Validates `--mcp-mode`/`--hub-url`/`--gateway-agents` together, before
+ * any other work (trellis-onboard-mcp-mode design.md D4) — a bad
+ * combination refuses the whole run rather than being discovered
+ * partway through. `mode` is only set when `mcpMode` was actually
+ * given; omitted resolves to `{}`, meaning "no change requested," not
+ * an error (design.md D1) — distinct from every other field on
+ * `RunOnboardOptions`, where omission usually requires a prompt.
+ */
+function validateMcpModeOption(opts) {
+    const { mcpMode, hubUrl, gatewayAgents } = opts;
+    if (mcpMode === undefined) {
+        if (hubUrl !== undefined)
+            return { error: "--hub-url was given without --mcp-mode hub" };
+        if (gatewayAgents !== undefined)
+            return { error: "--gateway-agents was given without --mcp-mode gateway" };
+        return {};
+    }
+    if (mcpMode !== "direct" && mcpMode !== "hub" && mcpMode !== "gateway") {
+        return { error: `--mcp-mode must be one of direct, hub, gateway (got "${mcpMode}")` };
+    }
+    if (mcpMode !== "hub" && hubUrl !== undefined) {
+        return { error: "--hub-url was given without --mcp-mode hub" };
+    }
+    if (mcpMode !== "gateway" && gatewayAgents !== undefined) {
+        return { error: "--gateway-agents was given without --mcp-mode gateway" };
+    }
+    if (mcpMode === "direct")
+        return { mode: { kind: "direct" } };
+    if (mcpMode === "hub") {
+        if (!hubUrl)
+            return { error: "--mcp-mode hub requires --hub-url <url>" };
+        return { mode: { kind: "hub", url: hubUrl } };
+    }
+    // mcpMode === "gateway"
+    if (gatewayAgents === undefined)
+        return { mode: { kind: "gateway" } };
+    const agents = parseAgentIdList(gatewayAgents);
+    if ("error" in agents)
+        return agents;
+    return { mode: { kind: "gateway", agents } };
+}
+/** Same "omitted means no change requested" posture as
+ * `validateMcpModeOption` (design.md D12). */
+function validateMemoryOption(memory) {
+    if (memory === undefined)
+        return {};
+    if (memory !== "on" && memory !== "off")
+        return { error: `--memory must be "on" or "off" (got "${memory}")` };
+    return { value: memory };
+}
+function mcpModeValueOf(mcp) {
+    if (mcp.gateway?.enabled)
+        return "gateway";
+    if (mcp.hub)
+        return "hub";
+    return "direct";
+}
+function resolveMcpModeChange(mode, currentValue) {
+    if (!mode)
+        return { current: currentValue, previous: currentValue, changed: false };
+    return { current: mode.kind, previous: currentValue, changed: mode.kind !== currentValue, write: mode };
+}
+/**
+ * `value === "on"` against an already-host-injected `"memory"` refuses
+ * outright rather than writing a definition `mcp sync` would refuse to
+ * propagate to any agent a moment later (design.md D10) — the same fact
+ * `schema/servers.example.yaml`'s own comment already explains to a
+ * human reading it by hand.
+ */
+function resolveMemoryToggle(value, configuredBefore, knownHostInjected) {
+    const previous = configuredBefore ? "on" : "off";
+    if (value === undefined)
+        return { current: previous, previous, changed: false };
+    if (value === "on") {
+        if (configuredBefore)
+            return { current: "on", previous, changed: false };
+        if (knownHostInjected.includes(MEMORY_SERVER_NAME)) {
+            return {
+                refusal: `refusing to enable the memory server: "${MEMORY_SERVER_NAME}" is already listed in known_host_injected — a host on this machine is presumed to already inject its own memory connector under that name, so a static definition here would only collide the next time \`mcp sync\` runs`,
+            };
+        }
+        return { current: "on", previous, changed: true };
+    }
+    // value === "off"
+    if (!configuredBefore)
+        return { current: "off", previous, changed: false };
+    return { current: "off", previous, changed: true };
+}
+function mcpModeStatusLine(mode) {
+    if (!mode.changed)
+        return `mcp mode: ${mode.current} (unchanged) — pass --mcp-mode direct|hub|gateway to change`;
+    return `mcp mode: ${mode.current} (changed from ${mode.previous})`;
+}
+function memoryStatusLine(memory) {
+    if (!memory.changed)
+        return `memory: ${memory.current} (unchanged) — pass --memory ${memory.current === "on" ? "off" : "on"} to change`;
+    return `memory: ${memory.current} (changed from ${memory.previous})`;
+}
 async function resolveManagedAgents(opts, summary, alreadyManaged) {
     if (opts.manage !== undefined) {
         const parsed = parseManagedSelection(opts.manage, summary);
@@ -243,7 +374,21 @@ 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: [] };
+    }
+    // Validated up front, before any of this run's own writes (managed.yaml
+    // included) — a bad `--mcp-mode`/`--hub-url`/`--gateway-agents`/
+    // `--memory` combination refuses the whole run cleanly rather than
+    // being discovered partway through (design.md D4). The parsed results
+    // are reused later, once managed-set resolution has run (design.md
+    // D5/D11).
+    const mcpModeValidation = validateMcpModeOption(opts);
+    if ("error" in mcpModeValidation) {
+        return { summary, refusal: mcpModeValidation.error, verdict: [] };
+    }
+    const memoryValidation = validateMemoryOption(opts.memory);
+    if ("error" in memoryValidation) {
+        return { summary, refusal: memoryValidation.error, verdict: [] };
     }
     const sourceCandidates = present.filter(hasContent);
     let source;
@@ -254,6 +399,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 +415,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 +423,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 +432,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 +454,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);
@@ -321,8 +469,37 @@ export async function collectOnboardPlan(opts = {}) {
     if (!opts.dryRun) {
         writeManagedYaml(homeDir, managedAgents);
     }
+    // MCP mode + memory-server resolution (design.md D5/D11) — grouped
+    // with managed-set above as "how is this machine configured"
+    // decisions resolved once per run, ahead of migrate/sync/mcp-sync/
+    // memory-sync below, which act on the result. Both flags were already
+    // validated before managed-set was even touched; omitting either
+    // resolves to "no change requested" here too (design.md D1/D12) — no
+    // writer call at all, on either a first run or a later one.
+    const canonicalForModeAndMemory = loadCanonicalSource(homeDir);
+    const mcpModeResolution = resolveMcpModeChange(mcpModeValidation.mode, mcpModeValueOf(canonicalForModeAndMemory.mcp));
+    const mcpMode = { current: mcpModeResolution.current, previous: mcpModeResolution.previous, changed: mcpModeResolution.changed };
+    const serversYamlPath = join(homeDir, ".trellis", "mcp", "servers.yaml");
+    if (mcpModeResolution.write && !opts.dryRun) {
+        writeMcpModeYaml(serversYamlPath, mcpModeResolution.write);
+    }
+    const memoryConfiguredBefore = canonicalForModeAndMemory.mcp.servers[MEMORY_SERVER_NAME] !== undefined;
+    const memoryResolution = resolveMemoryToggle(memoryValidation.value, memoryConfiguredBefore, canonicalForModeAndMemory.mcp.knownHostInjected);
+    if ("refusal" in memoryResolution) {
+        return { summary, source, sourceReason, managedAgents, mcpMode, refusal: memoryResolution.refusal, verdict: [] };
+    }
+    const memory = { current: memoryResolution.current, previous: memoryResolution.previous, changed: memoryResolution.changed };
+    if (memory.changed && !opts.dryRun) {
+        if (memory.current === "on") {
+            upsertServerYaml(serversYamlPath, MEMORY_SERVER_NAME, DEFAULT_MEMORY_SERVER_DEF);
+        }
+        else {
+            removeServerYaml(serversYamlPath, MEMORY_SERVER_NAME);
+        }
+    }
     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 +518,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 +545,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,29 +578,69 @@ export async function collectOnboardPlan(opts = {}) {
         migrateSkipped,
         syncReport,
         mcpSyncReport,
+        syncVerification,
+        mcpSyncVerification,
         memorySyncResult,
         secretsAuditReport,
+        doctorReport,
+        mcpMode,
+        memory,
+        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);
+        printResult(result, opts.dryRun ?? false, shouldShowProgress(opts));
+        // 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) {
+function printResult(result, dryRun, showStatusLine) {
     if (dryRun)
         console.log("[dry run]");
     const present = result.summary.filter((s) => s.present);
@@ -424,6 +675,17 @@ function printResult(result, dryRun) {
                 : `${install.agent} has no npm package to install (see \`trellis init\`'s install hint) — left out of this run's managed set.`);
     }
     console.log(`Managed agents: ${result.managedAgents && result.managedAgents.length > 0 ? result.managedAgents.join(", ") : "(none)"}`);
+    // Informational only, never a prompt (design.md D6/D12,
+    // trellis-onboard-mcp-mode) — this is what keeps `--mcp-mode`/
+    // `--memory` discoverable without costing every run a keystroke.
+    // Suppressed under `--json` and non-TTY, same gate stage progress
+    // already uses.
+    if (showStatusLine && result.mcpMode) {
+        console.log(mcpModeStatusLine(result.mcpMode));
+    }
+    if (showStatusLine && result.memory) {
+        console.log(memoryStatusLine(result.memory));
+    }
     // Reuse `migrate`/`sync`'s own printing verbatim (including the
     // "nothing to migrate" / "already in sync" cases) rather than a second,
     // easily-drifting copy of this formatting. `dryRun: false` here since
@@ -452,4 +714,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;
+    });
+}