agent-trellis 0.5.2 → 0.6.0

package/dist/commands/mcpGateway.js

@@ -0,0 +1,148 @@
+/**
+ * `trellis mcp-gateway --agent <id>` — the stdio MCP server an agent
+ * spawns in gateway mode (trellis-mcp-gateway-hosting).
+ *
+ * Not a user-facing command in the usual sense: nobody types this. An
+ * agent's own MCP client spawns it exactly the way it spawns any other
+ * stdio server, talks to it for the session, and closes the pipe on exit
+ * (design.md D2). There is no daemon, no lifecycle command, and nothing
+ * for the user to notice.
+ *
+ * This file depends on `GatewayBackend` and nothing below it — no
+ * connection, no transport, no server definition (design.md D11). That is
+ * what lets v2 point the same stdio edge at one shared service instead of
+ * an in-process backend without this file, or any agent's config,
+ * changing.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { LocalBackend } from "../lib/gatewayBackend.js";
+import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { ALL_AGENTS } from "../core/types.js";
+const CLIENT_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+const SERVER_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+export function parseMcpGatewayArgs(argv) {
+    const index = argv.indexOf("--agent");
+    if (index === -1 || index === argv.length - 1) {
+        return { error: `mcp-gateway requires --agent <${ALL_AGENTS.join("|")}>` };
+    }
+    const value = argv[index + 1];
+    if (!ALL_AGENTS.includes(value)) {
+        return { error: `unknown agent "${value}" — expected one of ${ALL_AGENTS.join(", ")}` };
+    }
+    return { agentId: value };
+}
+/**
+ * The in-scope upstream set for this agent, resolved through the very same
+ * `resolveMcpPlan` that direct mode uses — per-server `agents:` scope,
+ * `enabled: false`, host-injected collisions, literal-secret refusals and
+ * unresolved `env` names all apply here identically, because it is
+ * literally the same function (design.md D6).
+ *
+ * The one thing that must be stripped is gateway mode itself: asking
+ * `resolveMcpPlan` for this agent's plan while gateway mode is on would
+ * answer "one entry, pointing at the gateway" — the gateway being told to
+ * connect to itself. Resolving against a gateway-less view of the same
+ * canonical gives the set gateway mode replaced.
+ */
+export function resolveGatewayUpstreams(agentId, canonical) {
+    const direct = { ...canonical.mcp, gateway: undefined };
+    // The managed set is passed through unchanged, so an unmanaged agent
+    // reaches nothing. Being spawned is NOT treated as consent here, which
+    // is a deliberate divergence from `src/pi-bridge/index.ts` (which passes
+    // ALL_AGENTS on the grounds that pi loading the extension is itself the
+    // signal). The triggers differ: pi's bridge only exists on disk because
+    // Trellis symlinked it into pi's own directory while pi was managed, so
+    // its presence IS the marker. A gateway entry, by contrast, outlives
+    // un-managing — it sits in the agent's config until a later sync's
+    // ownership-gated removal clears it. Serving that stale entry would hand
+    // every server, and every secret resolved into it, to the one agent the
+    // user just said to stop involving.
+    const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    return {
+        upstreams: desired.map(({ name, def }) => ({ name, def })),
+        conflicts: conflicts.map((conflict) => conflict.message),
+    };
+}
+export async function runMcpGateway(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (err) {
+        // stderr, never stdout: stdout IS the MCP protocol stream here, and a
+        // stray line on it corrupts the agent's parser rather than informing
+        // anyone.
+        console.error(`trellis-mcp-gateway: ${err instanceof Error ? err.message : String(err)}`);
+        return { exitCode: 1 };
+    }
+    const { upstreams, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
+    for (const message of conflicts) {
+        console.error(`trellis-mcp-gateway: ${message}`);
+    }
+    const backend = opts.backendFactory
+        ? await opts.backendFactory(upstreams, homeDir)
+        : await LocalBackend.connect(upstreams, {
+            secretsPolicy: canonical.secretsPolicy,
+            clientInfo: CLIENT_INFO,
+            connectTimeoutMs,
+            // Enables silent OAuth refresh-before-connect. Never an
+            // interactive grant: that is `trellis mcp auth`'s job, and this
+            // process has no terminal to run one in (design.md D9).
+            homeDir,
+        });
+    const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await backend.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await backend.callTool(request.params.name, request.params.arguments);
+        return result;
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await waitForShutdown(backend, server);
+    return { exitCode: 0 };
+}
+/**
+ * Teardown on client disconnect — the piece neither layer below provides.
+ *
+ * `StdioServerTransport.start()` registers listeners for `'data'` and
+ * `'error'` only, so stdin reaching EOF never reaches `onclose`; and POSIX
+ * re-parents an orphan to launchd rather than killing it, while this
+ * process's own event loop is held open by every upstream it connected.
+ * Without this, each agent session would permanently leak a gateway plus
+ * its entire upstream process set (design.md D13).
+ */
+function waitForShutdown(backend, server) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const shutdown = async () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                await backend.close();
+            }
+            catch (err) {
+                console.error(`trellis-mcp-gateway: failed to close backend: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                await server.close();
+            }
+            catch {
+                // best-effort; the process is going away regardless
+            }
+            resolve();
+        };
+        process.stdin.on("end", shutdown);
+        process.stdin.on("close", shutdown);
+        for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+            process.once(signal, shutdown);
+        }
+    });
+}

package/dist/commands/migrate.d.ts

@@ -17,6 +17,10 @@ export interface MigratePlanItem {
     name: string;
     action: MigrateAction;
     detail: string;
+    /** Only set (and only meaningful) when `action === "conflict"`: the
+     * concrete next action, distinct from `detail`'s restatement of why
+     * (trellis-onboard-closed-loop design.md D7). */
+    remediation?: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;

package/dist/commands/migrate.js

@@ -44,7 +44,13 @@ function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
         case "already-present":
             return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
         case "conflict":
-            return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+            return {
+                kind: "skill",
+                name,
+                action: "conflict",
+                detail: `canonical skills/${name}/ already exists with different content — resolve by hand`,
+                remediation: `compare \`~/.trellis/skills/${name}/\` against the source agent's copy and either update canonical by hand or delete the source's copy if canonical's is the one to keep`,
+            };
     }
 }
 function planInstructions(snapshot, canonicalAgentsMd) {
@@ -58,7 +64,13 @@ function planInstructions(snapshot, canonicalAgentsMd) {
         sourceContent = readFileSync(snapshot.instructionsFile.path, "utf-8");
     }
     catch (err) {
-        return { kind: "instructions", name: "agents.md", action: "conflict", detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}` };
+        return {
+            kind: "instructions",
+            name: "agents.md",
+            action: "conflict",
+            detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: `check that ${snapshot.instructionsFile.path} exists and is readable, then re-run migrate`,
+        };
     }
     if (!existsSync(canonicalAgentsMd)) {
         return { kind: "instructions", name: "agents.md", action: "create", detail: "canonical agents.md does not exist yet", sourceContent };
@@ -70,7 +82,13 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     if (current === sourceContent) {
         return { kind: "instructions", name: "agents.md", action: "already-migrated", detail: "canonical content is byte-identical" };
     }
-    return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
+    return {
+        kind: "instructions",
+        name: "agents.md",
+        action: "conflict",
+        detail: "canonical agents.md already has different real content — resolve by hand",
+        remediation: `compare \`~/.trellis/agents.md\` against ${snapshot.instructionsFile.path} and either merge by hand or delete whichever copy you don't want to keep`,
+    };
 }
 /**
  * True when `existing` and `def` differ ONLY in which of `env`/
@@ -101,7 +119,13 @@ function planMcpServer(name, def, existing) {
     if (isSafeReclassification(existing, def)) {
         return { kind: "mcp", name, action: "reclassify", detail: "same value, only its internal classification changed — safe to update", mcpDef: def };
     }
-    return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
+    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`,
+    };
 }
 /**
  * `only` restricts which kind(s) are even considered — not a post-hoc

package/dist/commands/onboard.d.ts

@@ -18,7 +18,9 @@ import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
 import type { MemorySyncResult } from "./memory.js";
+import type { DoctorReport } from "./doctor.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
+import type { VerdictItem } from "./onboardVerdict.js";
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -64,6 +66,10 @@ export interface RunOnboardOptions {
      * answer — "skip migrate for this run" (design.md D6) — distinct from
      * `source` being unresolved at all. */
     promptForMigrateCategories?: (source: OnboardAgentSummary) => Promise<MigrateKind[]>;
+    /** Test-only: replaces the real end-of-`--dry-run` "apply now?" picker
+     * (design.md D9). `true` means "apply for real", matching what
+     * accepting the real picker's "Yes, apply now" option means. */
+    promptToApply?: () => Promise<boolean>;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -90,13 +96,41 @@ export interface OnboardResult {
     migrateSkipped?: string;
     syncReport?: SyncReport;
     mcpSyncReport?: McpSyncReport;
+    /**
+     * The self-verification re-plan (design.md D2b): a dry-run re-plan of
+     * `sync`/`mcp sync`, run immediately after their real apply, against
+     * the state that apply just wrote. Absent on `--dry-run` (nothing was
+     * written, so nothing to verify) and on every early-refusal path.
+     * Present, and empty, on a real run whose write actually held.
+     */
+    syncVerification?: SyncReport;
+    mcpSyncVerification?: McpSyncReport;
     memorySyncResult?: MemorySyncResult;
     secretsAuditReport?: SecretsAuditReport;
+    /**
+     * A broader, whole-machine health scan — the same detectors
+     * `trellis doctor` itself runs, against every agent (not scoped to
+     * `managedAgents`, design.md D3), never with MCP handshake probing
+     * (design.md D4). Complementary to, and distinct from, the
+     * write-verification above: this cannot itself prove a write took
+     * effect (it never reads canonical), only that something looks
+     * inconsistent across agents independent of this run.
+     */
+    doctorReport?: DoctorReport;
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and
      * text output both surface, so a machine caller doesn't have to
      * hardcode them a second time. */
     installHints?: Record<AgentId, string>;
+    /**
+     * Every stage's conflicts and findings, normalized to one shape
+     * (trellis-onboard-closed-loop design.md D5) — the single source
+     * `runOnboard`'s exit code and the terminal verdict block both derive
+     * from, so the two can never disagree. Always present, empty on a
+     * fully clean run (including refusal paths, where it reflects
+     * whatever partial data was collected before the refusal).
+     */
+    verdict: VerdictItem[];
 }
 export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
 export declare function runOnboard(opts?: RunOnboardOptions): Promise<{

package/dist/commands/onboard.js

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

package/dist/commands/onboardVerdict.d.ts

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