agent-trellis 0.14.1 → 0.15.0

package/dist/commands/rollback.js

@@ -8,7 +8,7 @@
  * already hold themselves to for every other kind of conflict.
  */
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { readlink, rm, symlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -63,84 +63,110 @@ async function currentLinkTarget(path) {
         return undefined;
     }
 }
-async function planOperation(homeDir, runId, op) {
+/** Probes the path's real on-disk state once, then caches it in `sim`;
+ * later ops for the same path see the simulated rewinds, not the disk. */
+async function simStateFor(path, sim) {
+    const cached = sim.get(path);
+    if (cached)
+        return cached;
+    let state;
+    // readlink first: it detects symlinks (even dangling ones) that
+    // existsSync would miss or misclassify.
+    const link = await currentLinkTarget(path);
+    if (link !== undefined) {
+        state = { kind: "symlink", target: link };
+    }
+    else if (!existsSync(path)) {
+        state = { kind: "absent" };
+    }
+    else if (statSync(path).isDirectory()) {
+        let digest;
+        try {
+            digest = directoryDigest(path);
+        }
+        catch {
+            digest = undefined;
+        }
+        state = { kind: "dir", digest };
+    }
+    else {
+        state = { kind: "file", hash: sha256(readFileSync(path, "utf-8")) };
+    }
+    sim.set(path, state);
+    return state;
+}
+async function planOperation(homeDir, runId, op, sim) {
     const runDir = join(backupsRoot(homeDir), runId);
+    const state = await simStateFor(op.path, sim);
     switch (op.kind) {
         case "file-create":
         case "file-overwrite": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            const currentHash = sha256(readFileSync(op.path, "utf-8"));
-            if (currentHash !== op.afterHash) {
+            if (state.kind !== "file" || state.hash !== op.afterHash) {
                 return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
             if (op.kind === "file-create") {
+                sim.set(op.path, { kind: "absent" });
                 return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
             }
+            sim.set(op.path, { kind: "file", hash: op.beforeHash });
             return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeFile)})` };
         }
         case "symlink-create":
         case "symlink-repair": {
-            const current = await currentLinkTarget(op.path);
-            if (current === undefined) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            if (current !== op.afterLinkTarget) {
+            if (state.kind !== "symlink" || state.target !== op.afterLinkTarget) {
                 return { action: "conflict", path: op.path, description: `${op.path} points somewhere else now — left untouched` };
             }
             if (op.kind === "symlink-create") {
+                sim.set(op.path, { kind: "absent" });
                 return { action: "restore", path: op.path, description: `remove ${op.path} (created by this run)` };
             }
+            sim.set(op.path, { kind: "symlink", target: op.beforeLinkTarget });
             return { action: "restore", path: op.path, description: `repoint ${op.path} back to ${op.beforeLinkTarget}` };
         }
         case "symlink-remove": {
-            if (existsSync(op.path)) {
+            if (state.kind !== "absent") {
                 return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "symlink", target: op.beforeLinkTarget });
             return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
         }
         // Historical `dir-remove` operations remain existence-only because they
         // predate directory manifests. New directory creates/replacements carry a
         // deterministic digest, so remote Skill rollback refuses an edited tree.
         case "dir-create": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            if (op.afterDigest !== undefined) {
-                let digest;
-                try {
-                    digest = directoryDigest(op.path);
-                }
-                catch {
-                    return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
-                }
-                if (digest !== op.afterDigest) {
-                    return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
-                }
+            if (op.afterDigest !== undefined && (state.kind !== "dir" || state.digest !== op.afterDigest)) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "absent" });
             return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
         }
         case "dir-remove": {
-            if (existsSync(op.path)) {
+            if (state.kind !== "absent") {
                 return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
             }
+            // The rewind's content comes from the beforeDir snapshot at apply
+            // time; its digest isn't recorded, so mark it unknown for any
+            // (in practice nonexistent) earlier op on the same path.
+            sim.set(op.path, { kind: "dir", digest: undefined });
             return { action: "restore", path: op.path, description: `recreate ${op.path} from its content before this run (${join(runDir, op.beforeDir)})` };
         }
         case "dir-replace": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            let digest;
-            try {
-                digest = directoryDigest(op.path);
-            }
-            catch {
-                return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
-            }
-            if (digest !== op.afterDigest) {
+            if (state.kind !== "dir" || state.digest !== op.afterDigest) {
                 return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "dir", digest: undefined });
             return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeDir)})` };
         }
     }
@@ -149,11 +175,15 @@ export async function collectRollbackPlan(homeDirInput, runIdInput) {
     const homeDir = homeDirInput ?? homedir();
     const runId = resolveRunId(homeDir, runIdInput);
     const manifest = loadManifest(homeDir, runId);
-    const items = [];
-    for (const op of manifest.operations) {
-        items.push(await planOperation(homeDir, runId, op));
+    // Plan newest-first against the simulated undo, then report in the
+    // manifest's original chronological order.
+    const sim = new Map();
+    const planned = [];
+    for (const op of [...manifest.operations].reverse()) {
+        planned.push(await planOperation(homeDir, runId, op, sim));
     }
-    return { runId, items };
+    planned.reverse();
+    return { runId, items: planned };
 }
 async function restoreOperation(homeDir, runId, op) {
     const runDir = join(backupsRoot(homeDir), runId);

package/dist/commands/skill.d.ts

@@ -49,6 +49,18 @@ export interface SkillAddPlan {
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
 export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
+/** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
+ * task 3.4): same source validation, destination is `.agents/skills/`
+ * instead of the global canonical skills dir. */
+export declare function collectSkillAddWorkspacePlan(name: string, fromPath: string, workspaceRoot: string): SkillAddPlan;
+export declare function applySkillAddWorkspacePlan(plan: SkillAddPlan, workspaceRoot: string, backup?: BackupSession): void;
+/** Same own-backup-session + cascade-sync posture as
+ * `applySkillAddWithSync`, scoped to the workspace layer. */
+export declare function applySkillAddWorkspaceWithSync(plan: SkillAddPlan, workspaceRoot: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillAddOutcome>;
 export interface SkillAddOutcome {
     plan: SkillAddPlan;
     sync?: SyncReport;
@@ -70,6 +82,8 @@ export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
+    workspace?: boolean;
+    workspaceDir?: string;
 }): Promise<{
     exitCode: number;
 }>;

package/dist/commands/skill.js

@@ -21,6 +21,7 @@ import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { remoteSkillProvenance } from "./remoteSkill.js";
 import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -114,6 +115,55 @@ export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
     mkdirSync(dest, { recursive: true });
     cpSync(plan.sourceDir, dest, { recursive: true });
 }
+/** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
+ * task 3.4): same source validation, destination is `.agents/skills/`
+ * instead of the global canonical skills dir. */
+export function collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot) {
+    const skillFile = findSkillFile(fromPath);
+    if (!skillFile) {
+        return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
+    }
+    if (!skillFile.caseCorrect) {
+        return { name, action: "invalid-source", detail: `${fromPath} has skill.md, not case-correct SKILL.md — fix the case first` };
+    }
+    const dest = join(workspaceRoot, ".agents", "skills", name);
+    switch (decideDirImport(fromPath, dest)) {
+        case "create":
+            return { name, action: "create", detail: `will copy from ${fromPath} into .agents/skills/`, sourceDir: fromPath };
+        case "already-present":
+            return { name, action: "already-present", detail: ".agents/skills/ content is already byte-identical" };
+        case "conflict":
+            return { name, action: "conflict", detail: `.agents/skills/${name}/ already exists with different content — resolve by hand` };
+    }
+}
+export function applySkillAddWorkspacePlan(plan, workspaceRoot, backup) {
+    if (plan.action !== "create" || !plan.sourceDir)
+        return;
+    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
+    if (backup) {
+        backup.createDirFromSource(dest, plan.sourceDir);
+        return;
+    }
+    mkdirSync(dest, { recursive: true });
+    cpSync(plan.sourceDir, dest, { recursive: true });
+}
+/** Same own-backup-session + cascade-sync posture as
+ * `applySkillAddWithSync`, scoped to the workspace layer. */
+export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    if (!opts.dryRun && plan.action === "create") {
+        applySkillAddWorkspacePlan(plan, workspaceRoot, session);
+    }
+    ownSession?.finalize();
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
+    let syncReport;
+    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
 /**
  * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
  * reason: a non-CLI caller needs the structured result a JSON-mode CLI
@@ -139,6 +189,27 @@ export async function applySkillAddWithSync(plan, opts = {}) {
 }
 export async function runSkillAdd(name, fromPath, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    if (opts.workspace) {
+        const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
+        if (!workspaceRoot) {
+            console.error("no .agents/ found here or above — run `trellis init --workspace` first (or pass --workspace from inside the repo)");
+            return { exitCode: 1 };
+        }
+        const plan = collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot);
+        const { sync: syncReport } = await applySkillAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
+        const failed = plan.action === "conflict" || plan.action === "invalid-source";
+        if (opts.json) {
+            console.log(JSON.stringify(syncReport ? { ...plan, workspace: workspaceRoot, sync: syncReport } : { ...plan, workspace: workspaceRoot }, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name} --workspace`);
+            console.log(`  [${plan.action}] ${plan.detail}`);
+            if (syncReport)
+                printSyncReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: failed || syncConflict ? 1 : 0 };
+    }
     const plan = collectSkillAddPlan(name, fromPath, homeDir);
     const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
     const failed = plan.action === "conflict" || plan.action === "invalid-source";

package/dist/commands/sync.d.ts

@@ -34,14 +34,29 @@ export interface RunSyncOptions {
      * does NOT finalize it — only whoever opened it does. Never a CLI
      * flag — standalone `trellis sync` always opens and finalizes its own. */
     backupSession?: BackupSession;
+    /** Force global-only behavior even inside a workspace (`--global-only`). */
+    globalOnly?: boolean;
+    /** Explicit workspace root — the test/sandbox seam. CLI discovery walks
+     * up from cwd via `findWorkspaceRoot`; this overrides it (null = none). */
+    workspaceDir?: string | null;
+    /** `--check`: compute the plan, write nothing, exit non-zero when any
+     * rendered artifact is stale or missing (CI/pre-commit freshness gate,
+     * trellis-workspace-scope design D7). Implies dry-run. */
+    check?: boolean;
 }
 export interface AgentSyncReport {
     agent: AgentId;
     present: boolean;
     items: AdapterPlanItem[];
+    /** zcode's reverse-precedence notices (workspace shadowing that zcode
+     * resolves user-level-first) — warnings, not conflicts: the write still
+     * happens. */
+    warnings?: string[];
 }
 export interface SyncReport {
     reports: AgentSyncReport[];
+    /** Workspace root when a `.agents/` layer participated in this run. */
+    workspaceRoot?: string;
 }
 export declare function collectSyncReport(opts?: RunSyncOptions): Promise<SyncReport>;
 export declare function runSync(opts?: RunSyncOptions): Promise<{
@@ -50,4 +65,4 @@ export declare function runSync(opts?: RunSyncOptions): Promise<{
 /** Exported so `onboard` prints a sync report identically to running
  * `sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export declare function printReport(report: SyncReport, dryRun: boolean): void;
+export declare function printReport(report: SyncReport, dryRun: boolean, check?: boolean): void;

package/dist/commands/sync.js

@@ -14,6 +14,9 @@ import { PiAdapter } from "../adapters/pi.js";
 import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { applyWorkspaceFiles, planWorkspaceFiles } from "../lib/workspaceFiles.js";
+import { workspacePrecedenceWarnings } from "../lib/workspaceMcp.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
@@ -30,7 +33,11 @@ function buildAdapters(homeDir, managedAgents) {
 }
 export async function collectSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const loaded = loadCanonicalSource(homeDir);
+    // Workspace participation is automatic inside a repo carrying `.agents/`
+    // and revocable via --global-only; outside any workspace (or when it
+    // resolves null) the load is byte-identical to before.
+    const workspaceDir = opts.globalOnly ? null : (opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd()));
+    const loaded = loadCanonicalSource({ homeDir, workspaceDir });
     // A single override point, not two: every downstream read of "who's
     // managed" — the adapter list built here AND each adapter's own
     // in-scope filtering via `canonical.managedAgents` — must agree, or a
@@ -39,9 +46,10 @@ export async function collectSyncReport(opts = {}) {
     const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
     // Own session only when the caller didn't share one (trellis-backup-
-    // rollback D2) — dry-run never opens or writes one, there's nothing to
-    // record.
-    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
+    // rollback D2) — dry-run/check never opens or writes one, there's
+    // nothing to record.
+    const writeMode = !opts.dryRun && !opts.check;
+    const ownSession = writeMode && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
     for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
@@ -53,6 +61,7 @@ export async function collectSyncReport(opts = {}) {
         // `trellis sync` never touches MCP, that's `trellis mcp sync`'s own
         // command, so exclude it unconditionally before any target filter.
         let items = (await adapter.plan(canonical)).filter((item) => item.kind !== "mcp");
+        let wsItems = planWorkspaceFiles(adapter.id, canonical);
         if (opts.target) {
             // CLI/option vocabulary is plural ("skills"/"instructions",
             // matching `trellis sync skills`); AdapterPlanItem.kind is singular
@@ -63,14 +72,18 @@ export async function collectSyncReport(opts = {}) {
             // sync" even with real create items pending).
             const kind = opts.target === "skills" ? "skill" : "instructions";
             items = items.filter((item) => item.kind === kind || (kind === "skill" && item.kind === "zcode-skill-control"));
+            wsItems = wsItems.filter((item) => item.kind === kind);
         }
-        if (!opts.dryRun) {
+        const allItems = [...items, ...wsItems];
+        if (writeMode) {
             await adapter.apply(items, backup);
+            applyWorkspaceFiles(adapter.id, canonical, wsItems, backup);
         }
-        reports.push({ agent: adapter.id, present: true, items });
+        const warnings = workspacePrecedenceWarnings(adapter.id, canonical);
+        reports.push({ agent: adapter.id, present: true, items: allItems, ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports };
+    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runSync(opts = {}) {
     let report;
@@ -85,22 +98,34 @@ export async function runSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report, opts.dryRun ?? false);
+        printReport(report, opts.dryRun ?? false, opts.check ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    if (opts.check) {
+        // Freshness gate: any pending write (create/remove) or conflict means
+        // the rendered artifacts are stale — exit non-zero, having written
+        // nothing.
+        const hasPending = report.reports.some((r) => r.items.some((i) => i.action !== "conflict"));
+        return { exitCode: hasPending || hasConflict ? 1 : 0 };
+    }
     return { exitCode: hasConflict ? 1 : 0 };
 }
 /** Exported so `onboard` prints a sync report identically to running
  * `sync` standalone, instead of a second, easily-drifting copy of this
  * formatting. */
-export function printReport(report, dryRun) {
+export function printReport(report, dryRun, check = false) {
     if (dryRun)
         console.log("[dry run]");
+    if (check)
+        console.log("[check]");
+    if (report.workspaceRoot) {
+        console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
+    }
     if (report.reports.length === 0) {
         console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
         return;
     }
-    for (const { agent, present, items } of report.reports) {
+    for (const { agent, present, items, warnings } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
@@ -110,12 +135,20 @@ export function printReport(report, dryRun) {
         const conflicts = items.filter((i) => i.action === "conflict");
         if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
             console.log(`✅ ${agent} — already in sync`);
-            continue;
         }
-        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
-        console.log(`${icon} ${agent} — ${created.length} created, ${removed.length} removed, ${conflicts.length} conflict(s)`);
-        for (const item of [...created, ...removed, ...conflicts]) {
-            console.log(`   - [${item.action}] ${item.description}`);
+        else {
+            const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+            console.log(`${icon} ${agent} — ${created.length} created, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+            for (const item of [...created, ...removed, ...conflicts]) {
+                console.log(`   - [${item.action}]${item.layer === "workspace" ? " (workspace)" : ""} ${item.description}`);
+                // Same as mcp.ts's printer: a conflict's remediation IS the fix —
+                // never leave the user at "left untouched" with no next step.
+                if (item.remediation)
+                    console.log(`     → ${item.remediation}`);
+            }
+        }
+        for (const warning of warnings ?? []) {
+            console.log(`   ⚠ ${warning}`);
         }
     }
 }

package/dist/core/adapter.d.ts

@@ -98,6 +98,20 @@ export interface AdapterPlanItem {
             skillsEnabled: boolean | null;
         };
     };
+    /** Set when this item renders the workspace (`.agents/`) layer rather
+     * than the global one (trellis-workspace-scope) — the command layer
+     * routes these to the workspace apply functions, never to the agent's
+     * global adapter apply. */
+    layer?: "workspace";
+    /** Only set when `layer === "workspace"`, `kind === "skill"`, and
+     * `action === "create"`: the canonical directory to copy into `target`
+     * (workspace skills are COPIED, never symlinked — rendered artifacts
+     * must be committable and Windows-safe, design D5). */
+    copyFrom?: string;
+    /** Only set when `layer === "workspace"`, `kind === "instructions"`, and
+     * `action === "create"`: the full rendered file content (managed marker
+     * header + workspace AGENTS.md body) to write at `target`. */
+    fileContent?: string;
 }
 export interface AdapterVerifyResult {
     ok: boolean;

package/dist/core/canonical.d.ts

@@ -1,40 +1,14 @@
 /**
- * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
- * parameter, no workspace merge (docs/architecture.md "Global vs.
- * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
- * canonical-source-loading/spec.md for the exact contract this implements.
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global-only by default —
+ * no working-directory consultation; a caller that explicitly discovered a
+ * workspace root (src/lib/workspace.ts `findWorkspaceRoot`) may pass it in
+ * to layer `<workspace>/.agents/` over the global source
+ * (openspec/changes/trellis-workspace-scope, design D2).
  */
 import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef, Scope } from "./types.js";
 import type { BackupSession } from "../lib/backup.js";
-/**
- * The on-disk shape for one server entry — `static_env`/`env_aliases`
- * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
- * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
- * below, and `auth`'s object form carries `client_id`/`client_secret_env`/
- * `client_name` the same way (trellis-mcp-static-env-and-disabled-servers,
- * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client,
- * oauth-client-name).
- */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
-    static_env?: Record<string, string>;
-    env_aliases?: Record<string, string>;
-    auth?: McpAuthYaml;
-};
-/** The on-disk `auth`: the `oauth` scalar exactly as before, or the object
- * form whose keys are snake_case like every other multi-word key in
- * `.trellis/*.yaml`. Values are `unknown` until `fromAuthYaml` validates
- * them — a YAML cast is optimistic, validation is this module's job. */
-type McpAuthYaml = string | {
-    kind?: unknown;
-    owner?: unknown;
-    client_id?: unknown;
-    client_secret_env?: unknown;
-    client_name?: unknown;
-};
-/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
- * `undefined` fields so the written YAML never gets a literal `null`
- * for an omitted optional. */
-export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;
+export { toServerDefYaml } from "./mcpServerDef.js";
+export type { McpServerDefYaml } from "./mcpServerDef.js";
 export type ServersYamlWriteResult = {
     ok: true;
 } | {
@@ -140,6 +114,18 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * `export` prefix of its own.
  */
 export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
+/**
+ * Options form of `loadCanonicalSource` (trellis-workspace-scope design D2).
+ * `homeDir` anchors BOTH the global canonical root and user-home semantics
+ * (secrets `env_file` `~` expansion) at all times; `workspaceDir` — a root
+ * previously discovered via `findWorkspaceRoot` — only adds the `.agents/`
+ * project layer on top, never relocates either.
+ */
+export interface LoadCanonicalOptions {
+    homeDir?: string;
+    workspaceDir?: string | null;
+}
 /** Load the global canonical source from the supplied home directory. */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
-export {};
+/** Load the global canonical source, optionally layered with an explicit workspace's `.agents/`. */
+export declare function loadCanonicalSource(options: LoadCanonicalOptions): CanonicalSource;