agent-trellis 0.7.0 → 0.8.0

package/dist/pi-bridge/index.js

@@ -15,29 +15,17 @@ import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { McpToolRegistry } from "../lib/mcpToolRegistry.js";
+import { withOAuthHeader } from "../lib/gatewayBackend.js";
 import { ALL_AGENTS } from "../core/types.js";
-import { bridgedToolName, toParametersSchema, toPiContent } from "./schemaTranslate.js";
+import { toParametersSchema, toPiContent } from "./schemaTranslate.js";
 /** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
  * importing it from the module it was written against — proving the
  * extraction changed nothing it could observe. */
 export { withTimeout };
 const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
-function registerServerTools(pi, serverName, client, timeoutMs) {
-    return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => {
-        for (const tool of result.tools) {
-            pi.registerTool({
-                name: bridgedToolName(serverName, tool.name),
-                label: tool.name,
-                description: tool.description ?? `MCP tool "${tool.name}" from server "${serverName}"`,
-                parameters: toParametersSchema(tool.inputSchema),
-                async execute(_toolCallId, params) {
-                    const result = await client.callTool({ name: tool.name, arguments: params });
-                    const content = Array.isArray(result.content) ? result.content : [];
-                    return { content: toPiContent(content), details: result };
-                },
-            });
-        }
-    });
+function listServerTools(client, timeoutMs) {
+    return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => result.tools);
 }
 /**
  * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
@@ -57,6 +45,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // is pi reading canonical directly at its own runtime, P4's own concern.
     const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
     const clients = new Set();
+    const registry = new McpToolRegistry();
     const closeClient = async (client) => {
         if (!clients.delete(client))
             return;
@@ -83,25 +72,57 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // pi 0.85.x emits this before tearing down an extension runtime. Keep the
     // hook optional so the bridge remains loadable in older compatible hosts.
     pi.on?.("session_shutdown", closeAllClients);
-    await Promise.all(desired.map(async ({ name, def }) => {
+    const discovered = await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            client = await connectServer(def, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
+            const effectiveDef = def.auth === "oauth" && def.url
+                ? await withOAuthHeader(name, def, homeDir)
+                : def;
+            client = await connectServer(effectiveDef, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
         }
         catch (err) {
             // One unreachable/misconfigured (including permanently hanging —
             // trellis-mcp-connect-timeout) server must never prevent every
             // other server's tools from registering (tasks.md 3.2).
             console.error(`trellis-mcp-bridge: failed to connect to MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
-            return;
+            return undefined;
         }
         clients.add(client);
         try {
-            await registerServerTools(pi, name, client, connectTimeoutMs);
+            const tools = await listServerTools(client, connectTimeoutMs);
+            return { name, client, tools };
         }
         catch (err) {
             console.error(`trellis-mcp-bridge: failed to list tools for MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
             await closeClient(client);
+            return undefined;
         }
     }));
+    // Add in canonical plan order, not completion order, so allocation remains
+    // stable when multiple upstreams answer concurrently.
+    for (const result of discovered) {
+        if (!result)
+            continue;
+        registry.add(result.name, result.client, result.tools);
+    }
+    for (const tool of registry.listTools()) {
+        const target = registry.resolve(tool.name);
+        if (!target)
+            continue;
+        const originalName = target.toolName;
+        const serverName = target.serverName;
+        pi.registerTool({
+            name: tool.name,
+            label: originalName,
+            description: tool.description ?? `MCP tool "${originalName}" from server "${serverName}"`,
+            parameters: toParametersSchema(tool.inputSchema),
+            async execute(_toolCallId, params) {
+                const result = await registry.callTool(tool.name, params);
+                const content = Array.isArray(result.content)
+                    ? result.content
+                    : [];
+                return { content: toPiContent(content), details: result };
+            },
+        });
+    }
 }

package/dist/pi-bridge/schemaTranslate.d.ts

@@ -50,12 +50,8 @@ export declare function toParametersSchema(inputSchema: unknown): TSchema;
  * own `AgentToolResult.content` has no representation for them
  * (design.md D3). */
 export declare function toPiContent(items: McpContentItem[]): PiContent[];
-/** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
- *
- * Now one implementation shared with the gateway's own aggregation rather
- * than two identical ones: the naming convention is the contract between
- * a prefixed name and the server it routes to, and two copies of it could
- * drift into routing tools to the wrong upstream
- * (trellis-mcp-gateway-hosting design.md D3). */
+/** Legacy direct prefix helper kept for callers/tests that need to render a
+ * source-qualified name. The live bridge uses `McpToolRegistry` so it can
+ * allocate short names across all connected servers, normalize invalid
+ * characters, and retain the raw name for routing. */
 export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/pi-bridge/schemaTranslate.js

@@ -33,12 +33,8 @@ export function toPiContent(items) {
         }
     });
 }
-/** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
- *
- * Now one implementation shared with the gateway's own aggregation rather
- * than two identical ones: the naming convention is the contract between
- * a prefixed name and the server it routes to, and two copies of it could
- * drift into routing tools to the wrong upstream
- * (trellis-mcp-gateway-hosting design.md D3). */
+/** Legacy direct prefix helper kept for callers/tests that need to render a
+ * source-qualified name. The live bridge uses `McpToolRegistry` so it can
+ * allocate short names across all connected servers, normalize invalid
+ * characters, and retain the raw name for routing. */
 export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/probes/kimi-code.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Kimi Code probe. Kimi 2.x stores user MCP declarations in
+ * `~/.kimi-code/mcp.json`, user Skills in `~/.kimi-code/skills`, and global
+ * instructions in `~/.kimi-code/AGENTS.md`. Kimi also discovers the generic
+ * `~/.agents/skills` root; it is reported so doctor can observe it, while the
+ * Runtime-only launcher can explicitly isolate it later.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export interface ProbeOptions {
+    probeMcp?: boolean;
+}
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/kimi-code.js

@@ -0,0 +1,55 @@
+/**
+ * Kimi Code probe. Kimi 2.x stores user MCP declarations in
+ * `~/.kimi-code/mcp.json`, user Skills in `~/.kimi-code/skills`, and global
+ * instructions in `~/.kimi-code/AGENTS.md`. Kimi also discovers the generic
+ * `~/.agents/skills` root; it is reported so doctor can observe it, while the
+ * Runtime-only launcher can explicitly isolate it later.
+ */
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+function kimiEnv(homeDir) {
+    return { ...process.env, HOME: homeDir, KIMI_CODE_HOME: join(homeDir, ".kimi-code") };
+}
+export async function probe(homeDir = homedir(), opts = {}) {
+    const root = join(homeDir, ".kimi-code");
+    const mcpPath = join(root, "mcp.json");
+    const mcpConfig = readJsonFile(mcpPath);
+    const kimiRoot = pathRef(root);
+    if (kimiRoot === undefined) {
+        return { agent: "kimi-code", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    let version;
+    try {
+        version = execFileSync("kimi", ["--version"], { encoding: "utf-8", timeout: 5_000, env: kimiEnv(homeDir) }).trim();
+    }
+    catch {
+        // A config-only fixture remains probeable without a binary on PATH.
+    }
+    const mcpServers = Object.entries(mcpConfig?.mcpServers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? (def.transport === "sse" ? "sse" : "http") : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(mcpConfig?.mcpServers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, kimiEnv(homeDir)));
+        }));
+    }
+    const skillRoots = [
+        scanSkillRoot(join(root, "skills")),
+        scanSkillRoot(join(homeDir, ".agents", "skills")),
+    ].filter((entry) => entry !== undefined);
+    return {
+        agent: "kimi-code",
+        present: true,
+        version,
+        skillRoots,
+        mcpServers,
+        instructionsFile: pathRef(join(root, "AGENTS.md")),
+        diagnostics: [],
+    };
+}

package/dist/sdk.d.ts

@@ -11,4 +11,4 @@
  */
 export { loadCanonicalSource } from "./core/canonical.js";
 export { ALL_AGENTS, resolveScope } from "./core/types.js";
-export type { AgentId, AgentProfile, CanonicalSource, HubConfig, McpConfig, McpServerDef, MemoryEntry, Scope, SecretsPolicy, SkillRef, Transport, } from "./core/types.js";
+export type { AgentId, AgentProfile, CapabilityDelivery, CanonicalSource, HubConfig, McpConfig, McpRuntimeConfig, McpServerDef, MemoryEntry, Scope, SecretsPolicy, SkillRef, Transport, } from "./core/types.js";

package/docs/architecture.md

@@ -18,7 +18,7 @@ required reading for that.
                 │  trellis sync / trellis doctor
         ┌───────┼────────┬─────────────┬──────────────┐
         ▼                ▼             ▼              ▼
-   Claude Code         Codex          Kiro            pi
+   Claude Code         Codex          Kiro            pi          Kimi Code
   (symlink adapter) (incremental   (symlink adapter) (bridge
                      TOML writer)                    extension)
 ```
@@ -57,7 +57,7 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 ## Global vs. workspace scope
 
 **Global only, for now.** Trellis manages `~/.trellis` — one canonical
-source per machine, applied to that machine's four agents. It does not yet
+source per machine, applied to that machine's five supported agents. It does not yet
 read or merge a project-local `.trellis/` in a specific repo.
 
 The `.agents Protocol` draft (see `research.md`) describes a two-layer
@@ -72,11 +72,11 @@ that's scope creep against this section, not a natural extension.
 
 ## Private / agent-specific capabilities
 
-Not everything belongs to all four agents. A skill built around Claude
+Not everything belongs to all five agents. A skill built around Claude
 Code's Task-based subagent delegation has no equivalent to delegate to on
 Codex; an MCP server might only make sense for one agent's workflow. Every
 scopable item — skill, subagent profile, memory entry, MCP server —
-defaults to "shared with all four," and can be restricted with an explicit
+defaults to "shared with all managed agents," and can be restricted with an explicit
 `scope` (skills/agents/memories) or inline `agents:` (MCP servers, see
 below). Restriction is the exception you declare, not something you
 configure for the common case.
@@ -173,8 +173,22 @@ the hub instead — meaningfully less code and one fewer class of failure
 the project that is an agent runtime extension, not a config generator,
 regardless of hub mode.
 
+The pi bridge symlink follows the currently executing Trellis installation.
+When switching from a checkout to a global package (or between installation
+roots), sync can repair an outside-root link only if its target ends in
+`dist/pi-bridge/bundle.js` and its bytes match the current bridge bundle.
+The repair is backed up, including the old symlink target. Modified, unrelated,
+or dangling outside-root links remain conflicts; this exception applies only
+to the bridge extension, not to Skill or instruction symlinks.
+
 ## MCP hub mode
 
+For onboarding, the short rule is: **Gateway is the recommended local
+Trellis mode; Hub is for an already-running external service**. Gateway is a
+local stdio subprocess that Trellis starts for the Agent session. Hub is an
+HTTP endpoint operated outside this process; Trellis only writes the URL and
+does not deploy, configure, or health-manage that Hub.
+
 Every agent's MCP surface can be either N direct server definitions
 (default) or one static entry pointing at a single HTTP endpoint — `mcp.hub.url`
 in `mcp/servers.yaml` is the field, but the supported way to set it is
@@ -197,7 +211,7 @@ to the code writing one entry that points at it.
 - Every adapter writes ONE entry instead of N. This is most of the value:
   adding a new backend server means editing wherever the hub's own config
   lives (this project doesn't prescribe that either) and never touching
-  any of the four agents' configs or restarting them, if the hub supports
+  any of the five agents' configs or restarting them, if the hub supports
   live reload (mcp-hub does, via SSE).
 - The collision check against `known_host_injected` (docs/research.md
   §"Codex — three hard constraints") shrinks to checking one name instead
@@ -245,23 +259,29 @@ Codex's `codex mcp login`/`logout` pair, Kiro's `oauth`/`oauthScopes`
 fields — and pi, whose bridge is Trellis's own code, simply couldn't
 reach such a server at all.
 
-That changed with gateway mode (below), which made it unavoidable: in
-gateway mode the agent connects to Trellis, and Trellis connects to the
-remote server, so the agent's own OAuth flow is no longer on the path.
-Trellis now implements the client half itself — discovery (RFC 8414 /
-RFC 9728), dynamic client registration (RFC 7591), authorization code
-with PKCE S256 (RFC 7636), and the refresh grant — in `src/lib/oauth/`.
+Gateway mode does not automatically take ownership of OAuth servers. Mark a
+server explicitly with `auth: oauth` (or `trellis mcp set <name> --auth oauth`)
+and gateway planning keeps it direct. This preserves the native Agent OAuth
+flow for Claude Code/Codex/Kiro; Pi's bridge is the client for its direct OAuth
+connection and may use Trellis's own OAuth store. Trellis never infers this
+classification from a URL or a transient 401.
+
+Trellis still implements the client half itself — discovery (RFC 8414 /
+RFC 9728), dynamic client registration (RFC 7591), authorization code with
+PKCE S256 (RFC 7636), and the refresh grant — in `src/lib/oauth/`, but that
+path is currently used for Pi/direct bridge connections rather than silently
+replacing native Agent authorization.
 
 Two rules shape it, both from the constraint that the gateway is spawned
 silently by an agent with no terminal attached:
 
-- **Only `trellis mcp auth <server>` ever opens a browser.** It is run by
-  a human, once. The gateway never initiates an interactive flow under
-  any circumstance; a server with no stored credential is skipped the
-  same way an unreachable one is.
+- **Only an explicit human authorization command opens a browser.** Native
+  clients use their own login command for direct OAuth entries. Pi's direct
+  bridge uses `trellis mcp auth <server>`. The gateway never initiates an
+  interactive flow and never connects an OAuth-marked server.
 - **Refreshing is silent, and serialized by a lock.** A `refresh_token`
-  grant needs neither a browser nor a callback, so the gateway does it
-  at connect time. The lock (`~/.trellis/mcp/oauth/<name>.lock`) exists
+  grant needs neither a browser nor a callback, so the Pi direct bridge can
+  do it at connect time. The lock (`~/.trellis/mcp/oauth/<name>.lock`) exists
   because most authorization servers rotate the refresh token and
   invalidate its predecessor — two concurrent refreshes would leave one
   party holding a credential that is already dead.
@@ -272,8 +292,9 @@ mode 0600, never in `servers.yaml` and never in the OS keychain (macOS's
 non-interactive, no-GUI-session context the gateway runs in — measured,
 not assumed).
 
-In direct mode nothing here applies: each agent keeps using its own
-native OAuth flow, exactly as before.
+In direct mode nothing here changes: each agent keeps using its own native
+OAuth flow. In gateway mode, an OAuth-marked server is also kept direct; only
+ordinary MCP servers enter the gateway.
 
 ## MCP gateway mode
 
@@ -311,15 +332,25 @@ true rather than aspirational:
 would have written for that agent (same `resolveMcpPlan`, so per-server
 `agents:` scope, `enabled: false`, host-injected collisions,
 literal-secret refusals and unresolved `env` names all behave
-identically), connects each one, and exposes their tools as
-`<server>__<tool>`. Secrets resolve through `resolveSecretEnv` exactly as
+identically), connects each one, and exposes their tools through the shared
+Agent-safe name allocator. Names contain only `[A-Za-z0-9_-]` and are at most
+64 characters; unique short names stay short, while duplicate names retain a
+normalized `<server>__<tool>` identity. Secrets resolve through
+`resolveSecretEnv` exactly as
 in direct mode — the gateway introduces no second path by which a value
 could reach disk.
 
 **What it changes for the agents:** Codex's single-`bearer_token_env_var`
 limitation stops applying, because Codex no longer receives any server's
-`headers` — the gateway holds them. Remote servers needing real OAuth
-become reachable from every agent, including pi, for the same reason.
+`headers` — the gateway holds them. OAuth-marked servers are intentionally
+kept direct; ordinary remote servers remain shared through the gateway. An
+upstream tool keeps its original name when that name is unique and longer than
+the short-name threshold; generic short names receive a compact
+`<server>__<tool>` prefix even when unique. A tool already carrying its source
+prefix is not repeated. Dotted or otherwise invalid names are normalized, and long names
+receive a deterministic hash suffix within the 64-character budget. If
+normalized names still collide, Trellis adds a stable suffix instead of
+dropping a tool.
 
 **The seam.** `src/commands/mcpGateway.ts` depends on a `GatewayBackend`
 interface and nothing below it — never a connection, transport, or
@@ -332,12 +363,117 @@ substitution at one construction site: the entry written into each
 agent's config is identical either way, so converging later requires no
 re-sync and nothing the user notices.
 
+## MCP Runtime direction
+
+Gateway mode is the first consumer of a broader runtime shape. The runtime
+edge is available as `trellis mcp-runtime --agent <id>`. Existing
+`trellis mcp-gateway --agent <id>` entries are a compatibility alias and now
+use the same provider registry. Both edges can expose Trellis-owned
+capabilities and selected upstream MCP capabilities:
+
+```text
+Agent
+  │ one MCP connection
+  ▼
+Trellis MCP Runtime
+  ├─ BuiltinRegistry
+  │   ├─ SkillProvider   (read/search canonical skills)
+  │   ├─ RuntimeMemoryProvider
+  │   │   └─ CanonicalMemoryProvider (read-only canonical Markdown)
+  │   └─ StatusProvider  (future read-only diagnostics)
+  └─ UpstreamProvider
+      └─ existing GatewayBackend / future RemoteBackend
+```
+
+The runtime is a protocol edge; providers are the capability boundary. A
+provider may expose tools, resources, prompts, or a combination. The current
+`GatewayBackend` remains the upstream tool aggregation implementation and is
+mounted as an `UpstreamProvider`, so connection, OAuth, timeout, namespace,
+and cleanup logic stay in one place.
+
+Native skills remain the default delivery. Runtime MCP delivery is configured
+per agent under `mcp.runtime.delivery` and supports `native`, `mcp`, or
+`both`. The built-in providers are intentionally read-only and scope-filtered:
+SkillProvider reads canonical skills, while RuntimeMemoryProvider adapts a
+CanonicalMemoryProvider that reads canonical Markdown memories through
+`trellis.memory.search`, `trellis.memory.read`, and
+`trellis://memories/<name>.md`. Neither executes scripts or mutates canonical
+state. When the documented `memory` MCP backend is enabled, Agent-created
+entities and observations are written through that upstream MCP server; the
+Runtime provider does not duplicate its graph protocol. `trellis memory
+extract` is the explicit, conflict-safe graph-to-canonical path. A future
+local-graph/OpenViking source can implement the same MemoryProvider contract,
+and native/private Agent stores are never scraped implicitly.
+
+`trellis.runtime.status` reports Memory readiness separately: backend
+configuration, graph existence/readiness, canonical count, write authority,
+and which managed Agents receive the shared route. This prevents an empty
+canonical directory from being mistaken for a missing or unusable backend.
+
+Onboarding keeps two Memory decisions independent:
+
+- `--memory-migrate on|off` imports supported native Markdown memory into
+  canonical `memories/*.md`.
+- `--memory on|off` enables the shared Memory MCP backend and graph.
+
+The first adapter is Claude Code's exact current-workspace project-memory
+directory. Kimi Code and pi session stores, and Kiro databases, are reported as
+unsupported until a format-specific adapter is reviewed; Trellis does not
+interpret sessions or caches as memory.
+
+Kimi Code is Runtime-first. Its adapter writes one `trellis` entry to
+`~/.kimi-code/mcp.json`; it does not copy canonical Skills into
+`~/.kimi-code/skills` when delivery is `mcp`. Use `trellis kimi` for this mode:
+the launcher passes Kimi's documented `--skills-dir` override an empty
+temporary directory, preventing Kimi's automatic `~/.agents/skills` discovery
+from duplicating the Runtime SkillProvider. Kimi's native mode remains
+available when delivery is `native` or `both`.
+
+Kimi's user MCP registry is `~/.kimi-code/mcp.json`; the adapter preserves
+unowned entries and uses the existing MCP ownership ledger for the one entry
+Trellis owns. The Kimi CLI itself remains responsible for login and OAuth.
+
+## Built-in Trellis Skill lifecycle
+
+`schema/builtin-skills/trellis-runtime/SKILL.md` is part of the Trellis
+package, not a user-specific copy. `trellis init` bootstraps it into the
+canonical source at `~/.trellis/skills/trellis-runtime/SKILL.md`; subsequent
+changes are made once there and distributed through the normal adapter path.
+
+The Skill has two contracts:
+
+- **Takeover contract:** describe the safe operator flow — inspect, dry-run,
+  choose the migration source and managed boundary, select capabilities,
+  authorize OAuth, sync, audit, verify, and rollback. This is a procedure for
+  the human or an Agent assisting the human; it is not a license for an Agent
+  to silently rewrite native configuration.
+- **Runtime contract:** describe how a managed Agent consumes
+  `SkillProvider`, `RuntimeMemoryProvider`, the instruction provider, status
+  providers, and task handoff providers through the current MCP edge.
+
+Delivery determines how the second contract reaches an Agent:
+
+| Delivery | Projection | Runtime Skill source |
+| --- | --- | --- |
+| `native` | Trellis-owned native symlink | Agent's native Skill discovery |
+| `mcp` | No native Trellis Skill projection | `SkillProvider` through `trellis mcp-runtime` |
+| `both` | Native projection plus Runtime entry | Both, intentionally during compatibility or transition |
+
+This keeps takeover instructions and post-takeover capability instructions in
+one versioned Skill while preserving the security boundary: Runtime providers
+are external context, native instructions remain authoritative at startup,
+and task mutations require explicit confirmation. The MCP client's generated
+namespace (for example `mcp__trellis__skills_search`) is not part of the
+portable Skill contract.
+
 ## What Trellis explicitly does not build
 
 - A resident MCP gateway daemon. Gateway mode above is a per-session
   subprocess with no lifecycle; hub mode points at something you operate.
   Neither is a service Trellis starts, supervises, or keeps running.
-- A memory backend (defaults to `@modelcontextprotocol/server-memory`,
+- A semantic/external memory backend (the built-in provider only exposes
+  read-only canonical Markdown; the default graph backend remains
+  `@modelcontextprotocol/server-memory`,
   turned on with `trellis onboard --memory on` (trellis-onboard-mcp-mode)
   rather than hand-editing `servers.yaml`, documented in
   `schema/servers.example.yaml`; mem0/OpenMemory and totalrecallai-class
@@ -419,6 +555,53 @@ once; it is never where you repeatedly verify against it.
 ```
 scripts/sandbox.sh                    # interactive shell in the sandbox
 scripts/sandbox.sh npm run dev doctor  # run a command in the sandbox
+scripts/sandbox.sh --runtime           # divergent multi-agent Runtime lab
+scripts/sandbox.sh --migration         # Kiro -> Codex post-migration lab
+scripts/sandbox.sh --management        # steady-state unified management lab
+scripts/sandbox.sh --failure           # hanging-upstream isolation lab
+scripts/sandbox-matrix.sh              # run the full scenario matrix
+scripts/agent-sandbox.sh               # real Codex/Claude/Kiro/pi/Kimi CLI config smoke
+```
+
+`agent-sandbox.sh` 默认使用一次性 HOME。需要进行授权时，显式使用专用
+Docker volume（默认名为 `trellis-agent-auth-home`）：
+
+如果宿主机已经登录 Codex 或 pi，可以显式复用单个认证文件：
+
+```
+scripts/agent-sandbox.sh --host-auth codex
+scripts/agent-sandbox.sh --host-auth pi
+```
+
+这两个命令只读取宿主机对应的 `auth.json`，不读取整个 agent 配置目录。
+
+```
+scripts/agent-sandbox.sh --login codex
+scripts/agent-sandbox.sh --login claude
+scripts/agent-sandbox.sh --login kiro
+scripts/agent-sandbox.sh --status codex
+scripts/agent-sandbox.sh --status claude
+scripts/agent-sandbox.sh --status kiro
+scripts/agent-sandbox.sh --auth codex exec --help
+scripts/agent-sandbox.sh --auth claude -p --help
+scripts/agent-sandbox.sh --prepare
+scripts/agent-sandbox.sh --host-auth codex
+scripts/agent-sandbox.sh --host-auth pi
+```
+
+授权只写入这个 Docker volume，不会复制宿主机的登录态，也不会进入
+Git、镜像或 fixture。`--login` 会分别执行真实 agent 的登录命令：
+Codex 使用 device auth，Claude Code 使用 Claude subscription 登录，
+Kiro CLI 使用 free license 的 device flow。Kiro 在未登录时会明确拒绝
+`mcp list`，这是预期的授权前置条件。需要清空授权 volume 时，应由用户
+显式执行 `docker volume rm <volume-name>`；Trellis 不会自动删除它。
+
+授权后若要在同一登录态中运行真实 agent，使用 `--auth` 前缀，例如：
+
+```
+scripts/agent-sandbox.sh --prepare
+scripts/agent-sandbox.sh --auth codex exec ...
+scripts/agent-sandbox.sh --auth claude -p ...
 ```
 
 Backed by OrbStack (this machine's Docker context — a Mac-native,
@@ -449,5 +632,20 @@ known findings, not just to look plausible:
   exercise the case-sensitivity check.
 - `test/fixtures/sample-mcp-server.js` — a minimal real MCP server (reads
   `initialize` over stdio, replies with fixed `serverInfo`) so
-  `probeMcpServer` has something deterministic to handshake against inside
-  the container without depending on a real npm package or network access.
+ `probeMcpServer` has something deterministic to handshake against inside
+ the container without depending on a real npm package or network access.
+
+For the MCP Runtime phase, the sandbox has a separate intentionally
+divergent fixture rather than expanding the baseline one:
+
+```
+scripts/sandbox.sh --runtime
+```
+
+This scenario gives Claude Code, Codex, Kiro, pi, and Kimi Code different native
+skills, instructions, and MCP entries; adds canonical scope, per-agent
+direct/gateway routes, `native`/`mcp`/`both` delivery, a deliberate
+host-injected collision, and canonical memory content. The lab then runs
+native sync, MCP sync, memory sync, secrets audit, and real MCP client
+handshakes against Claude/Codex/pi/Kimi runtime views. All writes stay inside
+the container-local HOME.

package/docs/assets/agent-trellis-architecture-horizontal.svg

@@ -0,0 +1,80 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">Agent Trellis — Unified Code Agent Runtime</title>
+  <desc id="desc">A horizontal architecture diagram showing Code Agents running on top of Agent Trellis Runtime, which manages Skills, MCP, Memory, and Instructions.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1118"/>
+      <stop offset="1" stop-color="#111c24"/>
+    </linearGradient>
+    <linearGradient id="base" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#273742"/>
+      <stop offset="1" stop-color="#17232c"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="18" stdDeviation="16" flood-color="#000" flood-opacity=".35"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#a9efd2"/>
+    </marker>
+    <style>
+      .sans { font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .mono { font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace; }
+      .title { fill: #f5efe3; font-size: 42px; font-weight: 720; letter-spacing: -.8px; }
+      .subtitle { fill: #a9efd2; font-size: 18px; font-weight: 620; letter-spacing: 2px; }
+      .label { fill: #f5efe3; font-size: 19px; font-weight: 680; }
+      .small { fill: #9aaab4; font-size: 14px; }
+      .tiny { fill: #7f919d; font-size: 12px; }
+    </style>
+  </defs>
+
+  <rect width="1600" height="900" fill="url(#bg)"/>
+  <path d="M0 120H1600M0 780H1600M120 0V900M1480 0V900" stroke="#24333d" stroke-width="1" opacity=".55"/>
+
+  <g class="sans">
+    <text x="100" y="94" class="title">Agent Trellis</text>
+    <text x="102" y="127" class="subtitle">UNIFIED CODE AGENT RUNTIME</text>
+    <text x="1500" y="96" text-anchor="end" class="small">one runtime · many coding agents</text>
+
+    <!-- Agent layer -->
+    <text x="800" y="190" text-anchor="middle" class="small" letter-spacing="2">CODE AGENTS</text>
+    <g filter="url(#shadow)">
+      <rect x="110" y="224" width="240" height="112" rx="16" fill="#17242c" stroke="#a9efd2" stroke-width="2"/>
+      <rect x="380" y="224" width="240" height="112" rx="16" fill="#17242c" stroke="#a9efd2" stroke-width="2"/>
+      <rect x="650" y="224" width="300" height="112" rx="16" fill="#17242c" stroke="#f2b35b" stroke-width="3"/>
+      <rect x="980" y="224" width="240" height="112" rx="16" fill="#17242c" stroke="#a9efd2" stroke-width="2"/>
+      <rect x="1250" y="224" width="240" height="112" rx="16" fill="#17242c" stroke="#a9efd2" stroke-width="2"/>
+    </g>
+    <text x="230" y="274" text-anchor="middle" class="label">Claude Code</text>
+    <text x="230" y="303" text-anchor="middle" class="tiny">native adapter</text>
+    <text x="500" y="274" text-anchor="middle" class="label">Codex</text>
+    <text x="500" y="303" text-anchor="middle" class="tiny">native adapter</text>
+    <text x="800" y="274" text-anchor="middle" class="label">Kimi Code</text>
+    <text x="800" y="303" text-anchor="middle" class="tiny">Runtime-first</text>
+    <text x="1100" y="274" text-anchor="middle" class="label">Kiro</text>
+    <text x="1100" y="303" text-anchor="middle" class="tiny">native adapter</text>
+    <text x="1370" y="274" text-anchor="middle" class="label">pi</text>
+    <text x="1370" y="303" text-anchor="middle" class="tiny">bridge adapter</text>
+
+    <path d="M230 338V405M500 338V405M800 338V405M1100 338V405M1370 338V405" stroke="#a9efd2" stroke-width="2" marker-end="url(#arrow)"/>
+
+    <!-- Runtime foundation -->
+    <g filter="url(#shadow)">
+      <rect x="140" y="420" width="1320" height="220" rx="24" fill="url(#base)" stroke="#f2b35b" stroke-width="2"/>
+      <rect x="165" y="445" width="1270" height="68" rx="14" fill="#0e1820" stroke="#41515b"/>
+      <rect x="165" y="528" width="1270" height="68" rx="14" fill="#0e1820" stroke="#41515b"/>
+    </g>
+    <text x="800" y="475" text-anchor="middle" class="label" font-size="24">Agent Trellis Runtime</text>
+    <text x="800" y="501" text-anchor="middle" class="tiny">canonical source · policy · providers · adapters</text>
+    <text x="325" y="570" text-anchor="middle" class="label">Skills</text>
+    <text x="625" y="570" text-anchor="middle" class="label">MCP</text>
+    <text x="925" y="570" text-anchor="middle" class="label">Memory</text>
+    <text x="1225" y="570" text-anchor="middle" class="label">Instructions</text>
+    <path d="M325 540v-20M625 540v-20M925 540v-20M1225 540v-20" stroke="#f2b35b" stroke-width="3"/>
+
+    <!-- Canonical source -->
+    <path d="M800 640V700" stroke="#f2b35b" stroke-width="3" marker-end="url(#arrow)"/>
+    <rect x="400" y="714" width="800" height="86" rx="18" fill="#101a22" stroke="#53636c"/>
+    <text x="800" y="750" text-anchor="middle" class="label">Canonical Source</text>
+    <text x="800" y="777" text-anchor="middle" class="mono small">~/.trellis  ·  one source of truth</text>
+  </g>
+</svg>