agent-trellis 0.5.2 → 0.6.0

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

@@ -12,7 +12,12 @@
  * this bridge actually uses are declared here.
  */
 import type { TSchema } from "typebox";
+import { withTimeout } from "../lib/mcpConnect.js";
 import { 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 };
 interface PiToolResult {
     content: ReturnType<typeof toPiContent>;
     details: unknown;
@@ -28,14 +33,6 @@ interface PiExtensionAPI {
     registerTool(tool: PiToolDefinition): void;
     on?(event: "session_shutdown", handler: () => Promise<void> | void): void;
 }
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
 /**
  * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
  * overridable for tests, same seam every other Trellis entry point
@@ -45,4 +42,3 @@ export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, m
  * `factory(pi)` — what pi actually does — works unchanged).
  */
 export default function trellisMcpBridge(pi: PiExtensionAPI, homeDir?: string, connectTimeoutMs?: number): Promise<void>;
-export {};

package/dist/pi-bridge/index.js

@@ -11,109 +11,17 @@
  * from Trellis's own install tree). Only the handful of fields/methods
  * this bridge actually uses are declared here.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveMcpPlan } from "../adapters/mcpPlan.js";
-import { resolveSecretEnv } from "../lib/secretEnv.js";
-import { extractTemplateVarNames } from "../lib/envVarNames.js";
+import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { ALL_AGENTS } from "../core/types.js";
 import { bridgedToolName, 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" };
-const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
-/**
- * A hanging server (process alive, protocol response never sent) leaves
- * `promise` permanently unsettled — indistinguishable from "still
- * starting up" without a bound. Racing against a timeout converts that
- * into an ordinary rejection, which every caller here already knows how
- * to isolate (design.md D1, trellis-mcp-connect-timeout).
- */
-export function withTimeout(promise, timeoutMs, message) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
-    });
-}
-/**
- * A timed-out (or otherwise failed) connect attempt must not leak the
- * transport's own resources — for `StdioClientTransport` specifically,
- * an unclosed transport means an orphaned child process that outlives
- * this failed attempt indefinitely (confirmed by a real leaked
- * subprocess during this change's own test run). `transport.close()` is
- * best-effort: a transport that never fully connected may itself error
- * on close, but the original connect failure is what the caller needs
- * to see, not a secondary cleanup error.
- */
-async function connectWithCleanup(client, transport, timeoutMs, message) {
-    try {
-        await withTimeout(client.connect(transport), timeoutMs, message);
-        return client;
-    }
-    catch (err) {
-        try {
-            await transport.close();
-        }
-        catch {
-            // best-effort; the original connect failure is what matters
-        }
-        throw err;
-    }
-}
-async function connectStdio(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const envAliases = def.envAliases ?? {};
-    // `envAliases`' values are source variable names — resolved through the
-    // exact same call as `env`'s own names, never delivered as the raw
-    // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
-    // of its own (like this bridge) would otherwise crash on parsing
-    // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
-    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
-    const transport = new StdioClientTransport({
-        command: def.command,
-        args: def.args,
-        // staticEnv merges last: a literal, intentionally-plain value (an
-        // email, an environment tag) always wins over an unresolved name-only
-        // entry's empty-string fallback for the same key — though in practice
-        // resolveMcpPlan's D6 refusal never lets an unresolved name reach
-        // this point at all (trellis-mcp-static-env-and-disabled-servers).
-        env: { ...getDefaultEnvironment(), ...namedEnv, ...aliasEnv, ...(def.staticEnv ?? {}) },
-    });
-    return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-function resolveHeaders(def, secretsPolicy) {
-    if (!def.headers || Object.keys(def.headers).length === 0)
-        return undefined;
-    const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
-    const result = {};
-    for (const [key, template] of Object.entries(def.headers)) {
-        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
-    }
-    return result;
-}
-async function connectHttp(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
-async function connectSse(def, secretsPolicy, timeoutMs) {
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
-    const opts = headers ? { requestInit: { headers } } : undefined;
-    return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
-}
 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) {
@@ -178,15 +86,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            if (def.transport === "http") {
-                client = await connectHttp(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else if (def.transport === "sse") {
-                client = await connectSse(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
-            else {
-                client = await connectStdio(def, canonical.secretsPolicy, connectTimeoutMs);
-            }
+            client = await connectServer(def, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
         }
         catch (err) {
             // One unreachable/misconfigured (including permanently hanging —

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

@@ -51,5 +51,11 @@ export declare function toParametersSchema(inputSchema: unknown): TSchema;
  * (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). */
-export declare function bridgedToolName(serverName: string, toolName: string): string;
+ * 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). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/pi-bridge/schemaTranslate.js

@@ -34,7 +34,11 @@ export function toPiContent(items) {
     });
 }
 /** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5). */
-export function bridgedToolName(serverName, toolName) {
-    return `${serverName}__${toolName}`;
-}
+ * 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). */
+export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/docs/architecture.md

@@ -234,28 +234,97 @@ one header simply can't reach Codex through Trellis, and is refused
 there (not silently dropped) while still reaching every other agent.
 
 **Real OAuth** (browser redirect, short-lived access token, refresh
-token) is not implemented anywhere in Trellis, on purpose. All three
-native-config agents already have their own real, working flow for it:
-
-- Claude Code: `claude mcp add --client-id/--client-secret/--callback-port`
-- Codex: a dedicated `codex mcp login`/`codex mcp logout` pair
-- Kiro: `oauth`/`oauthScopes` fields in its own real
-  `~/.kiro/settings/mcp.json` schema
-
-pi has none of this — its bridge is Trellis's own code, and the MCP
-SDK's `authProvider: OAuthClientProvider` option is a full
-redirect-and-refresh flow that doesn't fit a synchronously-loaded
-extension's lifecycle. A remote server that requires real OAuth simply
-isn't reachable through the pi bridge today — a real, stated limitation,
-not something papered over with a partial implementation.
+token) was, for most of this project's life, deliberately not built:
+all three native-config agents already have their own working flow —
+Claude Code's `claude mcp add --client-id/--client-secret/--callback-port`,
+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/`.
+
+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.
+- **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
+  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.
+
+Tokens live one-file-per-server at `~/.trellis/mcp/oauth/<name>.json`,
+mode 0600, never in `servers.yaml` and never in the OS keychain (macOS's
+`security add-generic-password` fails with exit 152/154 in exactly the
+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.
+
+## MCP gateway mode
+
+Gateway mode collapses an agent's MCP config to one entry, like hub mode
+— but what sits behind it is a local subprocess Trellis owns
+(`trellis mcp-gateway --agent <id>`), not a URL someone operates. Set
+`mcp.gateway.enabled` in `mcp/servers.yaml`; add `mcp.gateway.agents` to
+narrow it to specific agents, or omit it to cover every managed agent.
+`gateway` and `hub` are independent fields and may both be set — gateway
+wins for any agent it covers.
+
+**Lifecycle: there isn't one.** The agent spawns it like any other stdio
+MCP server and it exits when the session ends. No daemon, no
+start/stop/status command, nothing to monitor. Two things make that
+true rather than aspirational:
+
+- The gateway watches its own stdin for EOF and tears everything down.
+  The MCP SDK's `StdioServerTransport` binds only `'data'` and
+  `'error'`, so it never reports EOF, and POSIX re-parents orphans to
+  launchd rather than killing them — without explicit teardown every
+  session would leak a gateway plus its whole upstream set, forever.
+- Upstream failures are isolated. One server that is unreachable,
+  misconfigured, or permanently hanging is logged and skipped; every
+  other server's tools are still served.
+
+**What it does:** resolves the same in-scope server set direct mode
+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
+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.
+
+**The seam.** `src/commands/mcpGateway.ts` depends on a `GatewayBackend`
+interface and nothing below it — never a connection, transport, or
+server definition. Today the only implementation connects upstreams
+in-process, one gateway per agent session. The confirmed direction is a
+single shared service holding one connection set for all agents, with
+the per-session process becoming a thin client forwarding over a Unix
+socket, speaking MCP itself (so no second protocol to own). That is a
+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.
 
 ## What Trellis explicitly does not build
 
-- An MCP aggregator/gateway's actual routing/proxy logic (hub mode above
-  lets you point every agent at one, but Trellis doesn't implement one)
-- Real OAuth for remote MCP servers (browser redirect, token storage,
-  refresh) — every agent that has its own native flow keeps using it;
-  see "Static header auth vs. real OAuth" above
+- 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`,
   documented in `schema/servers.example.yaml`; mem0/OpenMemory and
   totalrecallai-class semantic-search servers documented as opt-in

package/docs/getting-started.md

@@ -17,8 +17,9 @@ $ trellis onboard
 
 Runs `init`, detects which of Claude Code/Codex/Kiro/pi are on this machine,
 then resolves two independent choices before running `migrate`, `sync`,
-`mcp sync`, `memory sync`, and `secrets audit` — the whole onboarding path,
-no follow-up commands to type by hand:
+`mcp sync`, `memory sync`, `secrets audit`, and a final health scan — the
+whole onboarding path, no follow-up commands to type by hand, and no need
+to run `trellis doctor` separately to know whether it actually worked.
 
 1. **Migration source** — read from, at most one, never written back to.
    "Real content" means skills, custom instructions, *or* real MCP servers
@@ -65,16 +66,72 @@ memory sync
 
 secrets audit
   ✅ no findings — every present agent's real config and every declared env var passed all checks
+
+health scan (trellis doctor)
+  ✅ no findings
+
+verdict
+✅ nothing needs attention — every stage completed cleanly and verified
+exit code: 0 — nothing blocked this run
 ```
 
 No agent named `claude-code` appears in the `sync`/`mcp sync` output above —
 it's present and was the migration source, but it isn't managed, so it's
 never even probed as a sync target, not just left with zero items.
 
+**The `verdict` block is always the last thing printed**, including on a
+run that had nothing wrong — the exit code and the last line on screen
+always agree, so a conflict earlier in the run can never be hidden behind
+a later stage's own unrelated success line. Every conflict from every
+stage is collected there, each with a concrete next action, not just a
+restatement of what went wrong:
+
+```
+verdict
+❌ 1 blocking issue(s):
+   - [sync/claude-code] ~/.claude/CLAUDE.md exists and is not a Trellis-managed symlink — left untouched
+     → back up ~/.claude/CLAUDE.md's real content if you need it, remove the file, then re-run sync
+exit code: 1 — at least one blocking issue above
+```
+
+**A real (non-`--dry-run`) run verifies its own writes**, immediately
+after making them — a dry-run re-plan of `sync`/`mcp sync` against exactly
+what was just written, checked for anything still outstanding. This is
+what actually answers "did this take effect," distinct from the health
+scan below it: `trellis doctor`'s own checks compare agents against each
+other and never read canonical, so they cannot prove a write held — only
+a re-plan against canonical can. If a write somehow didn't hold (a
+filesystem permission problem, a race), it surfaces in the verdict as its
+own `blocked` item, separate from whatever the write's own stage reported.
+
+**The health scan is `trellis doctor` itself**, run at the end against
+every agent (not just the ones this run manages) — so a genuinely new
+problem this run happened to create or reveal shows up without a separate
+`trellis doctor` invocation. It never spawns a configured MCP server to
+check it (`--probe-mcp` is never passed): the worst possible moment to
+start reaching real external services with real credentials is a user's
+first-ever run of this command. A finding about an agent this run doesn't
+manage is shown, labelled as such, and doesn't fail the run — onboard
+didn't touch that agent, so its drift isn't this run's problem to fix.
+
+On a real terminal, each stage prints a `[n/6] <stage>` progress line to
+stderr as it starts — `sync`/`mcp sync` spawn real processes and can take
+a few seconds, and this keeps the screen from going silent while that
+happens. It never appears on stdout, so `trellis onboard > report.txt`
+still captures exactly the report and verdict, nothing else; it's silent
+entirely under `--json` or when stdout isn't a real terminal.
+
 Add `--dry-run` to preview the entire chain — init/migrate/sync/mcp
 sync/memory sync, including what would be written to
-`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit is
-always read-only, with or without the flag).
+`~/.trellis/managed.yaml` — with zero writes anywhere (secrets audit and
+the health scan are always read-only, with or without the flag; the
+write-verification step above has nothing to check on a dry run and is
+skipped entirely). On a real terminal, a `--dry-run` ends by offering to
+apply the plan you just read — "No" is the highlighted default, so Enter
+declines; accepting re-plans against current state and applies for real,
+rather than replaying the exact preview you saw (state may have changed
+while you were reading it). `--json` and non-interactive runs are never
+offered anything.
 
 **A managed agent's own real content still isn't overwritten.** If you
 explicitly include the source in `--manage`, sync still never overwrites
@@ -315,7 +372,8 @@ below.
 Distributes `~/.trellis/mcp/servers.yaml` to every **managed** agent's
 native MCP config — same restriction as `sync`, see above. See [`schema/servers.example.yaml`](../schema/servers.example.yaml)
 for the full documented shape — server definitions, per-agent scoping,
-known-host-injected collision avoidance, and hub mode.
+known-host-injected collision avoidance, hub mode, and gateway mode
+(below).
 
 ```
 $ trellis mcp sync
@@ -367,6 +425,63 @@ unexpanded `${SOURCE_NAME}` text to any agent with no `${VAR}` runtime
 of its own — which is exactly what broke pi's Notion connection before
 this field existed.
 
+## Gateway mode — one entry per agent instead of N
+
+Add this to `servers.yaml` and every managed agent's config collapses to
+a single MCP entry:
+
+```yaml
+gateway:
+  enabled: true
+```
+
+Then re-run `trellis mcp sync`. Instead of one native entry per server,
+each agent gets one stdio entry pointing at `trellis mcp-gateway`. The
+agent spawns it like any other stdio MCP server; it connects out to your
+servers, and exits when the session ends. There is nothing to start,
+stop, or monitor.
+
+Your servers' tools appear to the agent as `<server>__<tool>` — the
+`gitlab` server's `search` becomes `gitlab__search`.
+
+Add `agents: [claude-code, codex]` under `gateway:` to narrow it, leaving
+the rest in direct mode. Gateway mode and `hub` are independent; both can
+be set, and gateway wins for any agent it covers.
+
+Two things stop being problems in gateway mode. Codex can normally only
+express a single `Authorization: Bearer ${VAR}` header, so a server
+needing more than one was refused for Codex — in gateway mode Codex never
+sees any server's headers, so it just works. And remote servers requiring
+real OAuth become reachable from every agent, including pi.
+
+### `trellis mcp auth <server-name>`
+
+For a remote (`http`/`sse`) server that uses OAuth, authorize it once:
+
+```
+$ trellis mcp auth notion-remote
+✅ notion-remote — authorized (expires 2026-09-16T11:24:03.000Z)
+   credentials: ~/.trellis/mcp/oauth/notion-remote.json
+```
+
+This opens your browser, completes the flow, and stores the result 0600
+under `~/.trellis/mcp/oauth/` — never in `servers.yaml`, so canonical
+stays safe to read, diff, and commit.
+
+Run it once per server. After that the gateway refreshes the token
+silently whenever it expires; it never opens a browser and never prompts,
+because it is spawned by an agent with no terminal attached. Re-running
+this command when the stored token is still valid does nothing (`--force`
+overrides); when it has expired but is renewable, it refreshes without a
+browser.
+
+If a server has no stored credential, the gateway skips that one server
+and keeps serving every other — it does not fail to start.
+
+This command only applies to `http`/`sse` servers. stdio servers get
+their credentials from `env`/`env_aliases` as described above; running
+`mcp auth` on one tells you so rather than opening a pointless browser.
+
 ## `trellis memory sync`
 
 Ingests `~/.trellis/memories/*.md` into the actual on-disk file

package/docs/research.md

@@ -179,6 +179,172 @@ Reverse-engineered directly from the installed binary
   genuine code, not config templating — see
   [`src/adapters/pi/`](../src/adapters/pi).
 
+## Cross-machine / cloud sharing — surveyed 2026-09-15, future direction confirmed
+
+Trellis today is single-machine-only (`docs/architecture.md`'s "Global vs.
+workspace scope" section deliberately scopes out project-local merge, but
+says nothing about cross-*machine* sync — that's a separate, real gap, not
+something already decided against). **Cloud/cross-machine sharing is
+confirmed as a future requirement, not a maybe** — the open question is
+sequencing and substrate choice, not whether to build it.
+
+Two genuinely different problems got explored together and need to stay
+separate in any design that follows:
+
+1. **Keeping `~/.trellis` canonical source consistent across a person's own
+   multiple machines** (config sync — small files, low write frequency).
+2. **Coordinating agent execution across machines / providing a shared
+   runtime substrate** (running-process orchestration — a different problem
+   with different failure modes, not a natural extension of #1).
+
+### `cloudflare/computer` — evaluated, not adopted
+
+[cloudflare/computer](https://github.com/cloudflare/computer) gives an
+agent a durable virtual filesystem (SQLite inside a Durable Object,
+`@cloudflare/dofs`) plus a pluggable execution backend (container FUSE
+mount, isolate shell via `just-bash`, or isolate JS in a Dynamic Worker) —
+one `workspace.runtime.exec(source, { backend })` entrypoint. Aimed at
+SaaS-scale "give every concurrent agent task its own cheap, horizontally-
+scalable workspace," not at syncing a handful of config files between a
+person's own laptop and desktop.
+
+Explicitly **PREVIEW ONLY** per the project's own README: "APIs are
+unstable... NOT suitable for production use at this time." That alone
+rules it out as a dependency today, separate from the architectural
+mismatch.
+
+The one reusable idea, if problem #1 above is tackled with a real sync
+protocol later rather than git: `@cloudflare/dofs`'s sync building blocks
+(`applyChanges`/`stageBlob`/`materialiseChange`/`fetchChanges`/
+`buildManifest`/`currentRev`/watermark cursors) are a clean change-set +
+content-addressed-blob + watermark model worth studying as a *design
+reference*, not a dependency — adopting the package itself means adopting
+Cloudflare Durable Objects as a required backend, which is a vendor
+commitment Trellis has never needed for anything else it does (everything
+else runs as a local CLI against local files).
+
+**Recommendation for problem #1**: start with git as the sync transport
+(`~/.trellis` is already just markdown/YAML — a natural git repo; `trellis
+sync` gains a `git pull --rebase`/`git push` step, conflicts resolved by
+git's own mechanism) before building or adopting any bespoke sync engine.
+Matches the project's own existing principle for MCP hub mode — "no engine
+switch in the type, only a URL" — apply the same discipline here: don't
+build sync-engine abstraction ahead of validating that git alone doesn't
+already solve it.
+
+### Letta Cloud's "Agent state" — evaluated as a hosted-state model, not adopted
+
+Surveyed 2026-09-16 after recognizing the shape from
+[letta-ai/letta-code](https://github.com/letta-ai/letta-code): Letta Cloud
+keeps an agent's memory, identity, and conversation history entirely
+server-side; any machine (laptop, Cloud VM, Mac Mini, GitHub Actions) can
+run the `letta server` harness against that same state
+([README](https://github.com/letta-ai/letta-code/blob/main/README.md),
+[Constellation docs](https://docs.letta.com/letta-code/constellation)).
+Confirmed by reading the actual mechanism, not just the marketing diagram:
+
+- **Attach is outbound-only.** `letta server --env-name "work-laptop"`
+  opens one outbound WebSocket to Letta Cloud — no inbound port, ever
+  ([BYOM docs](https://docs.letta.com/platform/computers/byom)). OAuth
+  device-flow credentials persist under `~/.letta/` so reconnects are
+  silent.
+- **"Teleportation" (moving execution between machines) is a sequenced
+  single-writer handoff, never concurrent.** The source machine finishes
+  its current tool call, stops accepting new work, and releases before
+  the destination starts; "a conversation can have only one teleport in
+  flight at a time," and a failed handoff leaves the conversation on the
+  source rather than in a split state
+  ([Teleportation docs](https://docs.letta.com/platform/computers/teleportation)).
+  Memory, message history, pending tool approvals, credentials, and
+  permission mode move with it; files, working directories, running
+  processes, and installed dependencies do not — the destination
+  reconstructs its own environment rather than receiving a filesystem
+  snapshot.
+- **Even with a fully hosted state store, Letta's own docs still tell
+  users to mirror agent memory to GitHub** via `/memory-repository` as a
+  backup. The vendor that built the hosted-state alternative does not
+  treat it as a substitute for a plain, git-friendly copy.
+
+**Not adopted as a model for Trellis's own cross-machine problem, and the
+reason is structural, not a maturity/cost judgment**: Letta's "agent
+state" is the runtime state of an agent Letta itself executes — its own
+first-party memory and conversation loop. Trellis has no equivalent to
+host: canonical (`~/.trellis`) is *configuration projected into* other
+vendors' agents (Claude Code, Codex, Kiro), whose own sessions, auth, and
+runtime state Trellis never touches and has no execution loop of its own
+to hand off. There is no "conversation" for a Trellis-hosted service to
+teleport — Trellis's job ends at writing correct config to disk on the
+one machine it's invoked on. Building a hosted canonical-state service to
+mirror Letta's shape would mean Trellis becoming a resident,
+account-backed service — the same "material shift... needs its own
+explicit sign-off" line `trellis-mcp-gateway-hosting`'s proposal.md
+already drew around operating so much as a spawned subprocess, applied
+here to something with a much larger blast radius (a user's actual
+configuration data, not a per-session child process).
+
+**Two mechanisms are worth recording anyway — not as new ideas to adopt,
+but as independent confirmation that designs already committed to
+elsewhere in this project land on the same shape a production
+multi-machine system converged on:**
+
+1. Outbound-only, no-daemon-to-babysit attach is exactly
+   `trellis-mcp-gateway-hosting`'s own shape (design.md D2/D13) — an
+   agent spawns `trellis mcp-gateway`, it connects out, it exits with the
+   session. Letta using the identical pattern for "any machine attaches
+   to hosted state" is evidence the shape generalizes, not a coincidence
+   worth re-deriving from scratch if problem #2 (a shared runtime
+   substrate) is ever built.
+2. Sequenced single-writer handoff — finish, release, then let the next
+   party proceed — is exactly the OAuth refresh lock's shape
+   (`trellis-mcp-gateway-hosting` design.md D16, `withServerLock`:
+   acquire, re-read to check whether the work is already done, act, or
+   defer). Same problem (two parties who might touch shared state at
+   once), same answer (serialize, never split), arrived at independently
+   in a completely different subsystem.
+
+**Standing recommendation unchanged**: git remains the right transport
+for problem #1. This survey is a reason to be confident in that choice,
+not a reason to revisit it — the hosted-state alternative was evaluated
+on its merits and excluded on structural grounds, and even its own
+vendor keeps a git-based fallback for the same category of data Trellis
+already treats git-friendly YAML/Markdown as the source of truth for.
+
+### Sandbox / execution substrate landscape — problem #2
+
+Surveyed for "a place agents actually run" rather than "a place config
+gets copied to":
+
+| Project | Model | License / status | Notes |
+|---|---|---|---|
+| [dagger/container-use](https://github.com/dagger/container-use) | MCP server; each agent gets an isolated container + its own git branch | Apache-2.0-adjacent, early/active | Works with *any* MCP-compatible agent, no vendor lock-in per its own README; `git checkout <branch>` to review any agent's work. Lightest-weight fit for Trellis's existing "MCP is the one place we write real integration code" model — could ship as a documented default MCP server entry with zero new adapter code, the same way `memory` (P6) was added |
+| [awslabs/cli-agent-orchestrator](https://github.com/awslabs/cli-agent-orchestrator) (CAO) | Local `cao-server` + per-agent isolated tmux sessions; supervisor/worker delegation; Web UI, HTTP API, PTY WebSocket; K8s deployment (shared workspace, per-pod state, credential delivery) | Apache-2.0, active (AWS) | **Directly supports Kiro CLI, Claude Code, and Codex CLI** — three of Trellis's four managed agents by name. Closest existing match to "run agents more smoothly + fleet management," and the closest existing candidate for problem #2 (cross-machine coordination) via its K8s deployment story. Not yet verified against Trellis's own canonical source/scope model — CAO has its own agent-profile concept, which is a second place "what an agent is configured to do" could live, the exact fragmentation class `docs/research.md`'s mcp-router incident (§ MCP aggregation) already warns about |
+| [daytonaio/daytona](https://github.com/daytonaio/daytona) | Firecracker-level sandbox infra, multi-language SDKs | Open-source repo, **but its own README states core development moved to a private codebase as of June 2026 — "no longer maintained"** | Ruled out: not an active open-source target to build on |
+| [e2b-dev/E2B](https://github.com/e2b-dev/E2B), [opensandbox-group/OpenSandbox](https://github.com/opensandbox-group/OpenSandbox) | Firecracker microVM / Docker+K8s one-shot code-execution sandboxes | E2B mostly managed (weak self-host story); OpenSandbox self-hostable | Both model "spin up a sandbox per code execution," not "keep a long-lived agent runtime consistent across a person's machines" — weaker fit than container-use/CAO for Trellis's actual use case |
+
+### Recommended path, not yet built
+
+1. **Cheapest, ships now, zero new adapter code**: document `container-use`
+   as an optional MCP server entry in `schema/servers.example.yaml`
+   (same pattern P6 used for `memory`) — every managed agent gets isolated,
+   disposable containers per task through the exact mechanism Trellis
+   already has for distributing MCP config. No cross-machine claim yet,
+   just "agents run more safely/smoothly," which is this session's own
+   stated ask.
+2. **Validate cross-machine config sync with git before building anything
+   bespoke** (problem #1) — smallest possible experiment, no new runtime
+   dependency.
+3. **Evaluate CAO as the substrate for problem #2** (cross-machine
+   coordination) only after #1 and #2 are separately validated as real,
+   distinct needs — specifically check whether its agent-profile model can
+   be made to read Trellis's canonical source rather than becoming a
+   second source of truth. This is new-project-scale work, not an
+   incremental Trellis phase — should get its own openspec proposal with
+   explicit success criteria before any code is written.
+
+None of the above is built yet. This section exists so the next design
+pass starts from "what was already checked" instead of re-surveying the
+same ground.
+
 ## Codex — three hard constraints learned by breaking them
 
 All three below came from real incidents, not upfront design, and any Codex