agent-trellis 0.2.0 → 0.3.0

package/dist/core/canonical.d.ts

@@ -4,7 +4,31 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { CanonicalSource } from "./types.js";
+import type { CanonicalSource, McpServerDef } from "./types.js";
+/**
+ * The on-disk shape for one server entry — `static_env` (snake_case, like
+ * every other multi-word key across `.trellis/*.yaml`) is translated to
+ * `McpServerDef.staticEnv` (camelCase) below; every other field happens
+ * to already be a single word, so no server-def field needed this
+ * treatment before (trellis-mcp-static-env-and-disabled-servers).
+ */
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv"> & {
+    static_env?: Record<string, string>;
+};
+/** 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 type ServersYamlWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use
@@ -14,3 +38,4 @@ import type { CanonicalSource } from "./types.js";
  * parameter does not weaken.
  */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
+export {};

package/dist/core/canonical.js

@@ -4,11 +4,29 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { isMap, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
+function fromServerDefYaml(def) {
+    const { static_env, ...rest } = def;
+    return static_env ? { ...rest, staticEnv: static_env } : rest;
+}
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written YAML never gets a literal `null`
+ * for an omitted optional. */
+export function toServerDefYaml(def) {
+    const { staticEnv, ...rest } = def;
+    const out = { ...rest };
+    if (staticEnv)
+        out.static_env = staticEnv;
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
 }
@@ -58,12 +76,72 @@ function loadServersYaml(path) {
         return { servers: {}, knownHostInjected: [] };
     }
     const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
     return {
-        servers: parsed.servers ?? {},
+        servers,
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
     };
 }
+/**
+ * Writes or replaces one server entry in `servers.yaml`, preserving
+ * every other entry's and comment's exact formatting (trellis-
+ * canonical-cli-crud design.md D3) — a `Document`-based edit
+ * (`setIn`), never `parse` + rebuild + `stringify`, which would
+ * re-serialize the whole file and lose anything hand-authored outside
+ * the touched entry. Refuses (no write) if the file doesn't exist yet
+ * (run `trellis init` first) or fails to parse.
+ */
+/**
+ * `trellis init`'s starter `servers.yaml` writes `servers: {}` — an empty
+ * flow-style map, since there's nothing to indent yet. `Document#setIn`
+ * inserting into an *existing* flow map keeps rendering it as flow, so
+ * the first `mcp add`/`migrate --only mcp` onto a fresh file — and every
+ * one after it — would render as one unreadable line (found via actually
+ * running the CLI against a fresh `init`, not by inspection). Forcing the
+ * touched map, and the newly-set entry's own map, to block style is a
+ * one-line, local fix — it never touches any sibling entry's own style,
+ * so a file someone deliberately kept flow-style elsewhere is untouched.
+ */
+function forceBlockStyle(node) {
+    if (isMap(node)) {
+        node.flow = false;
+    }
+}
+export function upsertServerYaml(path, name, def) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.setIn(["servers", name], toServerDefYaml(def));
+    forceBlockStyle(doc.get("servers", true));
+    forceBlockStyle(doc.getIn(["servers", name], true));
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export function removeServerYaml(path, name) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.deleteIn(["servers", name]);
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
 function loadSecretsPolicyYaml(path, homeDir) {
     if (!existsSync(path)) {
         return { allowedVars: [], rejectPatterns: [] };

package/dist/core/types.d.ts

@@ -44,6 +44,23 @@ export interface McpServerDef {
      * docs/research.md "Secrets" and schema/secrets.policy.example.yaml.
      */
     env?: string[];
+    /**
+     * Literal, non-secret values written into the agent's config verbatim
+     * — distinct from `env`'s names-only, resolved-at-runtime contract.
+     * Still scanned against `reject_patterns` like every other literal
+     * field (trellis-mcp-static-env-and-disabled-servers design.md D2):
+     * this is for values that were never secrets (an email address, an
+     * environment tag), not an escape hatch for real credentials.
+     */
+    staticEnv?: Record<string, string>;
+    /**
+     * Defaults to `true`. `false` keeps the definition in canonical
+     * without writing it to any agent — matches a real host config's own
+     * "defined but currently off" state (e.g. Codex's `enabled = false`)
+     * that omitting the definition entirely can't represent, since that
+     * would also throw away the definition itself.
+     */
+    enabled?: boolean;
     /** Omit for "all agents" (the default). See `Scope`. */
     agents?: Scope;
 }

package/dist/lib/deepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/lib/deepEqual.js

@@ -0,0 +1,26 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

package/dist/lib/dirEquals.d.ts

@@ -5,3 +5,12 @@
  * paths, same bytes per file; anything else is unequal.
  */
 export declare function dirContentsEqual(a: string, b: string): boolean;
+export type DirImportDecision = "create" | "already-present" | "conflict";
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export declare function decideDirImport(sourceDir: string, canonicalDir: string): DirImportDecision;

package/dist/lib/dirEquals.js

@@ -4,7 +4,7 @@
  * by this, not by name/mtime/hash-shortcut. Same set of relative file
  * paths, same bytes per file; anything else is unequal.
  */
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 function listFilesRecursive(dir) {
     const results = [];
@@ -37,3 +37,17 @@ export function dirContentsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export function decideDirImport(sourceDir, canonicalDir) {
+    if (!existsSync(canonicalDir))
+        return "create";
+    if (dirContentsEqual(sourceDir, canonicalDir))
+        return "already-present";
+    return "conflict";
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reads an agent's own real, already-configured MCP servers and converts
+ * each into canonical's `McpServerDef` shape — `trellis migrate --only
+ * mcp`'s read path (trellis-migrate-mcp-servers). Deliberately separate
+ * from each probe's own `AgentSnapshotMcpServer` (src/probes/*.ts) and its
+ * thin `{name, transport, probe?}` shape used by `doctor` — that shape
+ * discards exactly the fields this module needs, and extending it would
+ * risk `doctor`'s existing, extensively-tested behavior for no reason
+ * (design.md D1). pi has no static MCP config to read at all — no reader
+ * is defined for it; `migrate.ts` skips pi for the `mcp` category
+ * entirely, the same fact already established for skills/instructions.
+ */
+import type { McpServerDef } from "../core/types.js";
+export interface McpMigrateEntry {
+    name: string;
+    def: McpServerDef;
+}
+export interface McpMigrateUnsupported {
+    name: string;
+    reason: string;
+}
+export interface McpMigrateReadResult {
+    entries: McpMigrateEntry[];
+    unsupported: McpMigrateUnsupported[];
+}
+export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
+export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
+export interface CodexMcpEntryRich {
+    name: string;
+    enabled: boolean;
+    transport: {
+        type: string;
+        command?: string;
+        args?: string[];
+        env_vars?: string[];
+        /** Remote-transport fields. Confirmed by running the real,
+         * locally-installed `codex-cli 0.154.0` against a hand-written
+         * `url`-only server and a `url` + `bearer_token_env_var` server: the
+         * type string is `"streamable_http"` (not `"http"`), and the three
+         * `*headers*` fields come back `null` when unused. Codex's own
+         * config.toml schema (`tomlSection.ts`'s `renderServerSection`) has
+         * no way to distinguish `http` from `sse` at all — both render
+         * identically — so there is no lossy guess in always reading a
+         * remote entry back as `"http"`; that distinction was never stored. */
+        url?: string;
+        bearer_token_env_var?: string | null;
+        http_headers?: unknown;
+        env_http_headers?: unknown;
+        http_headers_helper?: unknown;
+    };
+}
+/**
+ * Pure conversion half — separated from the subprocess/file-read effects
+ * below so the stdio/non-stdio/malformed decision logic is unit-testable
+ * without a real `codex` binary on PATH (this codebase has no fake-codex
+ * fixture anywhere; codex's subprocess dependency is otherwise entirely
+ * untested at the unit level).
+ */
+export declare function buildCodexMcpReadResult(mcpEntries: CodexMcpEntryRich[], tomlContent: string | undefined): McpMigrateReadResult;
+/**
+ * Stdio only (design.md D2) — `codex mcp list --json`'s own output never
+ * exposes `url`/`bearer_token_env_var` in this codebase's `CodexMcpEntry`
+ * (src/probes/codex.ts), and this codebase has no verified evidence for
+ * what that subprocess reports for a non-stdio server. Guessing at an
+ * external tool's unverified output shape is exactly what this project's
+ * "verify, don't assume" discipline exists to prevent — a non-stdio
+ * entry is reported as unsupported instead.
+ */
+export declare function readCodexMcpDefs(homeDir: string): McpMigrateReadResult;

package/dist/lib/mcpMigrateRead.js

@@ -0,0 +1,188 @@
+/**
+ * Reads an agent's own real, already-configured MCP servers and converts
+ * each into canonical's `McpServerDef` shape — `trellis migrate --only
+ * mcp`'s read path (trellis-migrate-mcp-servers). Deliberately separate
+ * from each probe's own `AgentSnapshotMcpServer` (src/probes/*.ts) and its
+ * thin `{name, transport, probe?}` shape used by `doctor` — that shape
+ * discards exactly the fields this module needs, and extending it would
+ * risk `doctor`'s existing, extensively-tested behavior for no reason
+ * (design.md D1). pi has no static MCP config to read at all — no reader
+ * is defined for it; `migrate.ts` skips pi for the `mcp` category
+ * entirely, the same fact already established for skills/instructions.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile } from "./probeCommon.js";
+import { readServerEnvTable } from "./tomlSection.js";
+const EMPTY_RESULT = { entries: [], unsupported: [] };
+/**
+ * Trellis's own `env` (name-only reference) vs. `staticEnv` (literal
+ * value) split lives in one JSON object on disk (`jsonMcp.ts`'s
+ * `renderJsonServerEntry`) — a value is a "name" entry only when it's
+ * exactly `${KEY}` referencing its OWN key, matching exactly what that
+ * renderer ever produces; anything else (a literal value, or a `${...}`
+ * referencing a *different* name) is treated as a literal `staticEnv`
+ * value instead of guessed at.
+ */
+const SELF_VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+function splitJsonEnvMap(env) {
+    if (!env)
+        return {};
+    const names = [];
+    const literal = {};
+    for (const [key, value] of Object.entries(env)) {
+        const match = SELF_VAR_REF_RE.exec(value);
+        if (match && match[1] === key) {
+            names.push(key);
+        }
+        else {
+            literal[key] = value;
+        }
+    }
+    const result = {};
+    if (names.length > 0)
+        result.env = names;
+    if (Object.keys(literal).length > 0)
+        result.staticEnv = literal;
+    return result;
+}
+function fromRichJsonServerDef(raw) {
+    if (raw.url) {
+        const transport = raw.type === "sse" ? "sse" : "http";
+        const def = { transport, url: raw.url };
+        if (raw.headers && Object.keys(raw.headers).length > 0)
+            def.headers = raw.headers;
+        return def;
+    }
+    if (!raw.command)
+        return undefined;
+    const def = { transport: "stdio", command: raw.command };
+    if (raw.args && raw.args.length > 0)
+        def.args = raw.args;
+    Object.assign(def, splitJsonEnvMap(raw.env));
+    return def;
+}
+function readRichJsonMcpDefs(configPath) {
+    const parsed = readJsonFile(configPath);
+    const entries = [];
+    const unsupported = [];
+    for (const [name, raw] of Object.entries(parsed?.mcpServers ?? {})) {
+        const def = fromRichJsonServerDef(raw);
+        if (def) {
+            entries.push({ name, def });
+        }
+        else {
+            unsupported.push({ name, reason: "stdio entry has no command — malformed, skipped" });
+        }
+    }
+    return { entries, unsupported };
+}
+export function readClaudeCodeMcpDefs(homeDir) {
+    return readRichJsonMcpDefs(join(homeDir, ".claude.json"));
+}
+export function readKiroMcpDefs(homeDir) {
+    return readRichJsonMcpDefs(join(homeDir, ".kiro", "settings", "mcp.json"));
+}
+/**
+ * Pure conversion half — separated from the subprocess/file-read effects
+ * below so the stdio/non-stdio/malformed decision logic is unit-testable
+ * without a real `codex` binary on PATH (this codebase has no fake-codex
+ * fixture anywhere; codex's subprocess dependency is otherwise entirely
+ * untested at the unit level).
+ */
+export function buildCodexMcpReadResult(mcpEntries, tomlContent) {
+    const entries = [];
+    const unsupported = [];
+    for (const entry of mcpEntries) {
+        if (entry.transport.type !== "stdio") {
+            const remote = buildCodexRemoteDef(entry);
+            if (remote.def) {
+                entries.push({ name: entry.name, def: remote.def });
+            }
+            else {
+                unsupported.push({ name: entry.name, reason: remote.reason });
+            }
+            continue;
+        }
+        if (!entry.transport.command) {
+            unsupported.push({ name: entry.name, reason: "stdio entry has no command — malformed, skipped" });
+            continue;
+        }
+        const def = { transport: "stdio", command: entry.transport.command };
+        if (entry.transport.args && entry.transport.args.length > 0)
+            def.args = entry.transport.args;
+        if (entry.transport.env_vars && entry.transport.env_vars.length > 0)
+            def.env = entry.transport.env_vars;
+        if (tomlContent) {
+            const staticEnv = readServerEnvTable(tomlContent, entry.name);
+            if (staticEnv && Object.keys(staticEnv).length > 0)
+                def.staticEnv = staticEnv;
+        }
+        entries.push({ name: entry.name, def });
+    }
+    return { entries, unsupported };
+}
+/**
+ * A non-stdio Codex entry converts only when it's exactly `url` (+
+ * optional `bearer_token_env_var`) — the one shape this project has
+ * verified evidence for, and the only shape Trellis's own writer
+ * (`renderServerSection`'s else-branch) ever produces for Codex. Any of
+ * the three unexplained `*headers*` fields being non-null means the real
+ * server uses a mechanism this codebase has no verified shape for — that
+ * entry stays unsupported rather than silently dropping whatever those
+ * fields represent.
+ */
+function buildCodexRemoteDef(entry) {
+    const { url, bearer_token_env_var: bearerVar, http_headers, env_http_headers, http_headers_helper } = entry.transport;
+    if (http_headers != null || env_http_headers != null || http_headers_helper != null) {
+        return { reason: `codex migrate-in does not support this server's header mechanism (http_headers/env_http_headers/http_headers_helper) — no verified shape for it` };
+    }
+    if (!url) {
+        return { reason: `codex migrate-in: non-stdio entry has no url — malformed, skipped` };
+    }
+    const def = { transport: "http", url };
+    if (bearerVar) {
+        def.headers = { Authorization: `Bearer \${${bearerVar}}` };
+    }
+    return { def };
+}
+/**
+ * Stdio only (design.md D2) — `codex mcp list --json`'s own output never
+ * exposes `url`/`bearer_token_env_var` in this codebase's `CodexMcpEntry`
+ * (src/probes/codex.ts), and this codebase has no verified evidence for
+ * what that subprocess reports for a non-stdio server. Guessing at an
+ * external tool's unverified output shape is exactly what this project's
+ * "verify, don't assume" discipline exists to prevent — a non-stdio
+ * entry is reported as unsupported instead.
+ */
+export function readCodexMcpDefs(homeDir) {
+    let raw;
+    try {
+        // `codex` resolves its own config via $HOME (confirmed by running it
+        // with an overridden HOME against an empty scratch dir — it returns
+        // `[]`, not the real machine's servers), so this must be scoped to
+        // `homeDir` explicitly — `src/probes/codex.ts`'s own equivalent call
+        // has this same gap, unaddressed there; not touched by this change.
+        raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: { ...process.env, HOME: homeDir } });
+    }
+    catch {
+        return EMPTY_RESULT;
+    }
+    let mcpEntries;
+    try {
+        mcpEntries = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY_RESULT;
+    }
+    const configToml = join(homeDir, ".codex", "config.toml");
+    let tomlContent;
+    try {
+        tomlContent = readFileSync(configToml, "utf-8");
+    }
+    catch {
+        tomlContent = undefined;
+    }
+    return buildCodexMcpReadResult(mcpEntries, tomlContent);
+}

package/dist/lib/mcpOwnership.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Persisted record of what `mcp sync` itself last wrote for each agent —
+ * the ownership marker a bare TOML/JSON key otherwise lacks (mcpPlan.ts's
+ * own D7 reasoning: unlike a skill's symlink, there's nothing on disk to
+ * prove Trellis, not the user, put a given entry there). This ledger is
+ * that proof, kept separately from canonical (`~/.trellis/mcp/
+ * servers.yaml`) since it's Trellis's own private bookkeeping, not
+ * user-authored content.
+ *
+ * Stores each entry as the exact *rendered* value written at the time
+ * (a plain object for JSON agents, a TOML section string for Codex) —
+ * deliberately not a hash, so the later "is this still what we wrote"
+ * check can reuse each format's own already-existing equality check
+ * (`deepEqual` for JSON, `===` for TOML text) instead of a second,
+ * parallel comparison mechanism.
+ */
+import type { AgentId } from "../core/types.js";
+export type McpOwnershipLedger = Record<string, Record<string, unknown>>;
+export declare function mcpOwnershipPath(homeDir: string): string;
+export declare function loadMcpOwnership(homeDir: string): McpOwnershipLedger;
+export declare function saveMcpOwnership(homeDir: string, ledger: McpOwnershipLedger): void;
+/** This agent's own slice — `{}` if nothing has ever been recorded for it. */
+export declare function ownedByAgent(ledger: McpOwnershipLedger, agentId: AgentId): Record<string, unknown>;
+export declare function recordOwned(ledger: McpOwnershipLedger, agentId: AgentId, name: string, rendered: unknown): McpOwnershipLedger;
+export declare function forgetOwned(ledger: McpOwnershipLedger, agentId: AgentId, name: string): McpOwnershipLedger;

package/dist/lib/mcpOwnership.js

@@ -0,0 +1,50 @@
+/**
+ * Persisted record of what `mcp sync` itself last wrote for each agent —
+ * the ownership marker a bare TOML/JSON key otherwise lacks (mcpPlan.ts's
+ * own D7 reasoning: unlike a skill's symlink, there's nothing on disk to
+ * prove Trellis, not the user, put a given entry there). This ledger is
+ * that proof, kept separately from canonical (`~/.trellis/mcp/
+ * servers.yaml`) since it's Trellis's own private bookkeeping, not
+ * user-authored content.
+ *
+ * Stores each entry as the exact *rendered* value written at the time
+ * (a plain object for JSON agents, a TOML section string for Codex) —
+ * deliberately not a hash, so the later "is this still what we wrote"
+ * check can reuse each format's own already-existing equality check
+ * (`deepEqual` for JSON, `===` for TOML text) instead of a second,
+ * parallel comparison mechanism.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function mcpOwnershipPath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "ownership.json");
+}
+export function loadMcpOwnership(homeDir) {
+    const path = mcpOwnershipPath(homeDir);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {}; // unreadable/corrupt ledger — treat as "nothing recorded yet", never crash a sync over it
+    }
+}
+export function saveMcpOwnership(homeDir, ledger) {
+    mkdirSync(join(homeDir, ".trellis", "mcp"), { recursive: true });
+    writeFileSync(mcpOwnershipPath(homeDir), `${JSON.stringify(ledger, null, 2)}\n`);
+}
+/** This agent's own slice — `{}` if nothing has ever been recorded for it. */
+export function ownedByAgent(ledger, agentId) {
+    return ledger[agentId] ?? {};
+}
+export function recordOwned(ledger, agentId, name, rendered) {
+    return { ...ledger, [agentId]: { ...(ledger[agentId] ?? {}), [name]: rendered } };
+}
+export function forgetOwned(ledger, agentId, name) {
+    if (!(name in (ledger[agentId] ?? {})))
+        return ledger;
+    const agentEntries = { ...ledger[agentId] };
+    delete agentEntries[name];
+    return { ...ledger, [agentId]: agentEntries };
+}

package/dist/lib/memoryGraph.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Converts canonical `memories/*.md` into `@modelcontextprotocol/
+ * server-memory`'s own on-disk JSON-lines knowledge-graph format, and
+ * upserts them into an existing graph file without disturbing anything
+ * else in it (trellis-memory-sync) — closing P6's explicitly-left-open
+ * "auto-ingesting memories/*.md content into the running memory
+ * server's store" gap.
+ *
+ * Each line in that file is one JSON object, either
+ * `{type:"entity", name, entityType, observations}` or
+ * `{type:"relation", from, to, relationType}` — the real, documented
+ * shape the official server persists and reads back on its own next
+ * startup (this project writes the file directly; it never spawns or
+ * talks to a running server process).
+ *
+ * `entityType: "trellis-memory"` is this project's own in-band ownership
+ * marker — simpler than a separate ledger file (unlike MCP server sync,
+ * every agent connected to this one server shares the exact same graph,
+ * so there's no per-agent rendering to track). An existing entity with
+ * the same name but a different `entityType` was created by something
+ * else (an agent's own runtime tool calls, most likely) and is left
+ * completely untouched — reported as a conflict, never overwritten.
+ */
+import type { CanonicalSource } from "../core/types.js";
+export interface MemoryEntity {
+    type: "entity";
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+export interface MemoryRelation {
+    type: "relation";
+    from: string;
+    to: string;
+    relationType: string;
+}
+export type MemoryGraphLine = MemoryEntity | MemoryRelation;
+export declare const TRELLIS_MEMORY_ENTITY_TYPE = "trellis-memory";
+export declare function parseMemoryGraph(content: string): MemoryGraphLine[];
+export declare function renderMemoryGraph(lines: readonly MemoryGraphLine[]): string;
+export type MemorySyncAction = "create" | "already-synced" | "remove" | "conflict";
+export interface MemorySyncItem {
+    name: string;
+    action: MemorySyncAction;
+    detail: string;
+}
+export interface MemorySyncPlan {
+    items: MemorySyncItem[];
+    /** The full graph content to write — `undefined` when there is
+     * nothing to change (no create/remove items). */
+    nextGraph?: MemoryGraphLine[];
+}
+/**
+ * Pure: computes the next graph state and a human-readable plan, given
+ * the current graph's raw content (or `undefined` if the file doesn't
+ * exist yet) and canonical's memory entries. Every non-`trellis-memory`
+ * entity and every relation passes through completely untouched,
+ * regardless of what canonical wants.
+ */
+export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined): MemorySyncPlan;