@edspencer/paddock 0.61.1 → 0.63.0

package/packages/server/dist/mcp-servers.js

@@ -0,0 +1,399 @@
+/**
+ * The prefix that makes a string an environment reference rather than a literal.
+ * Same spelling as `managementApi.clients.<id>.auth.ref`, deliberately: an
+ * operator should have to learn it once.
+ */
+export const ENV_REF_PREFIX = "env:";
+/**
+ * Server names paddock materialises itself, which a declaration may not take.
+ *
+ * Kept as literals rather than imported from `send-file-mcp.ts`/`self-mcp.ts` so
+ * config resolution stays free of the runtime modules — `mcp-servers-reserved`
+ * in the unit tests asserts the two spellings still agree.
+ */
+export const RESERVED_MCP_SERVER_NAMES = ["paddock", "paddock_manage"];
+/**
+ * `mcp__<server>__<tool>` is the tool name both runtimes match against, and the
+ * allowlist pattern is built from it by string concatenation, so a name with a
+ * separator or whitespace in it produces a pattern that matches nothing. Claude
+ * Code uses the same character class for a server name.
+ */
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+/** Keys of a declaration this module understands. Anything else is a typo. */
+const KNOWN_KEYS = new Set(["command", "args", "env", "url", "type", "headers"]);
+/**
+ * Env keys whose INLINE value is probably a credential. Deliberately a name
+ * heuristic and never a value one: matching on the value would mean reading it
+ * closely enough to describe it, and this module's whole posture is that it
+ * never looks at a value it is not about to hand to a server process.
+ */
+const SECRET_ISH_KEY_RE = /(TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH|PAT|COOKIE)/i;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * A URL with everything credential-shaped removed — no query string, no
+ * fragment, no `user:pass@`. Used for every log line that mentions a `url`,
+ * because a remote MCP endpoint's API key is conventionally a query parameter.
+ * An unparseable URL is reported as its scheme only rather than echoed.
+ */
+export function redactUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const auth = u.username || u.password ? "<redacted>@" : "";
+        return `${u.protocol}//${auth}${u.host}${u.pathname}${u.search ? "?<redacted>" : ""}`;
+    }
+    catch {
+        return "<unparseable url>";
+    }
+}
+/**
+ * A server rendered for a human, carrying no secret. THE chokepoint: every
+ * notice, warning and error about a declared server goes through here, so
+ * auditing "can a token reach a log line?" is auditing one function.
+ *
+ * Args and env values are counted, never printed — an API key is as likely to be
+ * `--token=…` in `args` as it is to be an `env` value. The command is reduced to
+ * its basename for the same reason, which the leak test in
+ * `test/unit/mcp-servers.test.ts` is what forced: a full path is more useful in a
+ * log, but the rule "nothing from the block is echoed" is only worth having if it
+ * has no exceptions to remember. The server's own name is printed alongside and
+ * is what actually identifies it.
+ */
+export function describeServer(name, def) {
+    const parts = [];
+    if (def.command)
+        parts.push(`stdio: ${def.command.split(/[\\/]/).pop()}`);
+    if (def.url)
+        parts.push(`${def.type ?? "http"}: ${redactUrl(def.url)}`);
+    if (def.args?.length)
+        parts.push(`${def.args.length} args`);
+    const envCount = Object.keys(def.env ?? {}).length;
+    if (envCount > 0)
+        parts.push(`${envCount} env ${envCount === 1 ? "entry" : "entries"}`);
+    const headerCount = Object.keys(def.headers ?? {}).length;
+    if (headerCount > 0)
+        parts.push(`${headerCount} ${headerCount === 1 ? "header" : "headers"}`);
+    return `${name} (${parts.join(", ")})`;
+}
+/**
+ * Resolve a string leaf: `env:VAR_NAME` reads `VAR_NAME`, anything else is a
+ * literal.
+ *
+ * An unset or blank variable FAILS the leaf, which drops the whole server. That
+ * is the fail-closed direction here for the same reason it is in
+ * `management-config.ts`: a server started without the credential it was
+ * declared with either fails every call confusingly or — worse for something
+ * that talks to a third party — connects unauthenticated.
+ */
+function resolveLeaf(raw, env, where) {
+    if (!raw.startsWith(ENV_REF_PREFIX))
+        return { ok: true, value: raw };
+    const varName = raw.slice(ENV_REF_PREFIX.length).trim();
+    if (varName.length === 0)
+        return { ok: false, error: `${where}: \`env:\` names no variable` };
+    const value = env[varName];
+    if (value === undefined || value.trim().length === 0) {
+        return {
+            ok: false,
+            error: `${where}: environment variable ${varName} is unset or empty`,
+        };
+    }
+    return { ok: true, value };
+}
+/**
+ * Validate + resolve one declaration into the shape herdctl's `McpServerSchema`
+ * carries, or explain why it cannot be.
+ *
+ * The one rejection left that is about the engine rather than about the file is
+ * **an unknown key** — the only defence against `arg:`/`envs:`/`commands:`, which
+ * would otherwise yield a server that starts with the wrong argv.
+ *
+ * `headers` and `type: sse` were rejections too until herdctl 5.32.0, because
+ * the schema had no field for either: a bearer-authenticated server arrived
+ * unauthenticated and missed its stored OAuth token (keyed on a hash that
+ * includes the headers and the type), and an `sse` url was silently connected to
+ * as HTTP. Both are now carried verbatim, so both are accepted — `headers`
+ * through the same `env:VAR` resolution as `env`, and `type` checked only for
+ * agreeing with the declaration (`stdio` for a `command`, `http`/`sse` for a
+ * `url`).
+ */
+function narrowDeclaration(name, raw, env) {
+    const where = `mcpServers.${name}`;
+    const errors = [];
+    const warnings = [];
+    const fail = (msg) => ({
+        errors: [...errors, `${msg} — not attached`],
+        warnings,
+    });
+    if (!NAME_RE.test(name)) {
+        return fail(`${where}: a server name may contain only letters, digits, \`_\` and \`-\` (its tools are ` +
+            `named mcp__${name}__<tool>, and the allowlist pattern is built from that)`);
+    }
+    if (RESERVED_MCP_SERVER_NAMES.includes(name)) {
+        return fail(`${where}: "${name}" is reserved for a server paddock injects itself, and two servers ` +
+            `cannot share the mcp__${name}__* namespace`);
+    }
+    if (!isRecord(raw))
+        return fail(`${where}: is not a mapping`);
+    const unknown = Object.keys(raw).filter((k) => !KNOWN_KEYS.has(k));
+    if (unknown.length > 0) {
+        return fail(`${where}: unrecognised key(s) ${unknown.join(", ")} ` +
+            `(supported: command, args, env, url, type, headers) ` +
+            `— a mistyped key would otherwise be dropped without a trace`);
+    }
+    const hasCommand = typeof raw.command === "string" && raw.command.trim().length > 0;
+    const hasUrl = typeof raw.url === "string" && raw.url.trim().length > 0;
+    if (hasCommand && hasUrl) {
+        return fail(`${where}: declares both a \`command\` and a \`url\`; a server is one or the other`);
+    }
+    if (!hasCommand && !hasUrl) {
+        return fail(`${where}: declares neither a \`command\` nor a \`url\`, so there is nothing to start`);
+    }
+    const server = {};
+    if (raw.type !== undefined) {
+        const type = String(raw.type).trim().toLowerCase();
+        // `sse` joined `http` here in herdctl 5.32.0; an explicit type now wins over
+        // the bare-`url` ⇒ `http` inference rather than being stripped on the way
+        // down. It still has to agree with the rest of the declaration, because a
+        // `type` that disagrees is a typo and starting the wrong transport is a
+        // confusing failure rather than a loud one.
+        const expected = hasUrl ? ["http", "sse"] : ["stdio"];
+        if (!expected.includes(type)) {
+            return fail(`${where}: \`type: ${type}\` disagrees with the declaration ` +
+                `(expected ${expected.join(" or ")})`);
+        }
+        server.type = type;
+    }
+    if (hasCommand) {
+        const res = resolveLeaf(raw.command.trim(), env, `${where}.command`);
+        if (!res.ok)
+            return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+        server.command = res.value;
+    }
+    if (hasUrl) {
+        const res = resolveLeaf(raw.url.trim(), env, `${where}.url`);
+        if (!res.ok)
+            return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+        server.url = res.value;
+        // A key in the query string is one of the two ways a remote MCP endpoint is
+        // authenticated (the other, `headers`, is carryable again since #700), and
+        // this file is git-tracked. Say so once; never echo the query itself.
+        if (!raw.url.startsWith(ENV_REF_PREFIX)) {
+            let parsed;
+            try {
+                parsed = new URL(server.url);
+            }
+            catch {
+                /* an unparseable url is the engine's problem, not a secrets one */
+            }
+            if (parsed && (parsed.search || parsed.username || parsed.password)) {
+                warnings.push(`${where}.url: carries a query string or userinfo, which is where an API key usually ` +
+                    `rides. This file is git-tracked — prefer \`url: ${ENV_REF_PREFIX}VAR_NAME\` and ` +
+                    `keep the value in the environment`);
+            }
+        }
+    }
+    if (raw.args !== undefined) {
+        if (!Array.isArray(raw.args) || !raw.args.every((a) => typeof a === "string")) {
+            return fail(`${where}.args: must be a list of strings`);
+        }
+        const args = [];
+        for (const [i, arg] of raw.args.entries()) {
+            const res = resolveLeaf(arg, env, `${where}.args[${i}]`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            args.push(res.value);
+        }
+        if (args.length > 0)
+            server.args = args;
+    }
+    if (raw.env !== undefined) {
+        if (!isRecord(raw.env))
+            return fail(`${where}.env: must be a mapping of NAME to value`);
+        const resolved = {};
+        for (const [key, value] of Object.entries(raw.env)) {
+            if (typeof value !== "string") {
+                return fail(`${where}.env.${key}: must be a string (values are passed to a process verbatim)`);
+            }
+            const res = resolveLeaf(value, env, `${where}.env.${key}`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            resolved[key] = res.value;
+            if (!value.startsWith(ENV_REF_PREFIX) && SECRET_ISH_KEY_RE.test(key)) {
+                warnings.push(`${where}.env.${key}: looks like a credential and is written into the config file ` +
+                    `itself, which is git-tracked — prefer \`${key}: ${ENV_REF_PREFIX}VAR_NAME\` and set ` +
+                    `the value in the environment`);
+            }
+        }
+        if (Object.keys(resolved).length > 0)
+            server.env = resolved;
+    }
+    if (raw.headers !== undefined) {
+        if (!hasUrl) {
+            return fail(`${where}.headers: only a \`url\` server can carry headers`);
+        }
+        if (!isRecord(raw.headers)) {
+            return fail(`${where}.headers: must be a mapping of header name to value`);
+        }
+        const resolved = {};
+        for (const [key, value] of Object.entries(raw.headers)) {
+            if (typeof value !== "string") {
+                return fail(`${where}.headers.${key}: must be a string`);
+            }
+            const res = resolveLeaf(value, env, `${where}.headers.${key}`);
+            if (!res.ok)
+                return { errors, warnings: [...warnings, `${res.error} — server not attached`] };
+            resolved[key] = res.value;
+            // Same heuristic as `env`, one rule to learn — and `Authorization` is the
+            // usual reason a header is declared at all, so this fires on the common
+            // case rather than the exotic one.
+            if (!value.startsWith(ENV_REF_PREFIX) && SECRET_ISH_KEY_RE.test(key)) {
+                warnings.push(`${where}.headers.${key}: looks like a credential and is written into the config file ` +
+                    `itself, which is git-tracked — prefer \`${key}: ${ENV_REF_PREFIX}VAR_NAME\` and set ` +
+                    `the value in the environment`);
+            }
+        }
+        if (Object.keys(resolved).length > 0)
+            server.headers = resolved;
+    }
+    return { server, errors, warnings };
+}
+/**
+ * Resolve the whole `mcpServers:` block against `env`.
+ *
+ * Never throws. A declaration paddock cannot carry is reported and dropped so one
+ * typo cannot take an instance down — the same posture as
+ * `resolveManagementApiConfig`, and for the same reason: this is a capability,
+ * and losing a capability is better than losing the instance.
+ */
+export function resolveDeclaredMcpServers(file, env) {
+    const servers = {};
+    const errors = [];
+    const warnings = [];
+    if (file === undefined || file === null)
+        return { servers, errors, warnings };
+    if (!isRecord(file)) {
+        errors.push("mcpServers: must be a mapping of server name to declaration — ignored");
+        return { servers, errors, warnings };
+    }
+    for (const [rawName, decl] of Object.entries(file)) {
+        const name = rawName.trim();
+        if (name.length === 0) {
+            errors.push("mcpServers: a server name is empty — not attached");
+            continue;
+        }
+        const res = narrowDeclaration(name, decl, env);
+        errors.push(...res.errors);
+        warnings.push(...res.warnings);
+        if (res.server)
+            servers[name] = res.server;
+    }
+    return { servers, errors, warnings };
+}
+/**
+ * The one way a declared credential leaves paddock, said out loud.
+ *
+ * Everything else in this module is about keeping a resolved value out of the
+ * places paddock controls — the log, an error, the Settings API. It does that
+ * completely, and it is still not the whole story, because of what herdctl does
+ * with the record afterwards:
+ *
+ * ```js
+ * // @herdctl/core, runner/runtime/cli-runtime.js
+ * const mcpServers = transformMcpServers(options.agent.mcp_servers);
+ * const mcpConfig = JSON.stringify({ mcpServers });
+ * args.push("--mcp-config", mcpConfig);      // ← env values and all
+ * ```
+ *
+ * A process ARGUMENT is not private on Linux: `/proc/<pid>/cmdline` is
+ * world-readable by default (no `hidepid`), and `ps` prints it. So on the CLI
+ * runtime every declared server's `env` — and, since #700 made the field
+ * carryable, its `headers` — is legible to any local user for the lifetime of
+ * each `claude` invocation. Observed, not
+ * inferred: `test/integration/declared-mcp-argv.test.ts` drives a real turn and
+ * reads the token back out of the spawned process's argv.
+ *
+ * The SDK runtime does NOT do this. It hands the same record to the SDK
+ * in-process, and the stdio server it spawns receives the value in its
+ * environment, where `/proc/<pid>/environ` is owner-only — which is exactly what
+ * Claude Code itself does, so it is not a regression to fix here.
+ *
+ * Which runtime runs is `driveMode`: `session` (the default) is the SDK,
+ * `batch` is the CLI. Hence a WARNING on an instance that is on `batch`, and an
+ * informational note otherwise — because a single project can pin `driveMode:
+ * batch` for itself and bring the exposure back with it.
+ *
+ * Paddock cannot close this from here: the fix is upstream (the Claude CLI's
+ * `--mcp-config` also accepts a file path, which is not readable from another
+ * process's argv). Refusing to attach the server instead would break the feature
+ * for the deployments most likely to need it, so what this does is refuse to be
+ * silent — the same posture step 5 takes towards the fields the engine's schema
+ * cannot carry.
+ */
+function argvExposure(names, driveMode) {
+    const batch = driveMode === "batch";
+    return {
+        level: batch ? "warn" : "info",
+        message: `${names.join(", ")} ${names.length === 1 ? "declares" : "declare"} \`env\` values or ` +
+            `\`headers\`, and ` +
+            `under \`driveMode: batch\` the engine passes the whole server definition to \`claude\` ` +
+            `as a \`--mcp-config\` COMMAND-LINE argument — where any local process can read it via ` +
+            `/proc/<pid>/cmdline. ` +
+            (batch
+                ? `This instance is on \`driveMode: batch\`, so that applies to every turn. Prefer ` +
+                    `\`driveMode: session\` (the default) for a server that holds a credential.`
+                : `This instance is on \`driveMode: session\`, which passes them in-process instead — ` +
+                    `but a project that pins \`driveMode: batch\` brings the exposure back.`),
+    };
+}
+/**
+ * What to say at boot about the declared servers — the answer to "what does this
+ * instance actually have?", which should be readable off the log rather than
+ * inferred from a YAML file plus an environment.
+ *
+ * Takes the already-resolved servers, so it cannot see a raw declaration and
+ * therefore cannot leak one; every line it produces goes through
+ * {@link describeServer}.
+ */
+export function declaredMcpNotices(opts) {
+    const names = Object.keys(opts.servers);
+    if (names.length === 0)
+        return [];
+    const notices = [
+        {
+            level: "info",
+            message: `MCP servers declared by this instance (\`mcpServers:\`): ` +
+                `${names.map((n) => describeServer(n, opts.servers[n])).join("; ")}. ` +
+                `Every project's keeper gets all of them.`,
+        },
+    ];
+    const shadowed = names.filter((n) => opts.hostNames?.includes(n));
+    if (shadowed.length > 0) {
+        notices.push({
+            level: "info",
+            message: `${shadowed.join(", ")} ${shadowed.length === 1 ? "is" : "are"} also declared in your ` +
+                `~/.claude.json (\`claude.mcpServers: host\`); this instance's own declaration wins.`,
+        });
+    }
+    // `headers` joined `env` here in #700: herdctl 5.32.0 carries them, so an
+    // `Authorization` bearer now rides in the same `--mcp-config` argv element that
+    // #702 found an `env` token in — and a bearer is the likelier long-lived
+    // credential of the two. A server declared with headers and no env would
+    // otherwise be the one case this warning missed.
+    const exposed = names.filter((n) => Object.keys(opts.servers[n].env ?? {}).length > 0 ||
+        Object.keys(opts.servers[n].headers ?? {}).length > 0);
+    if (exposed.length > 0 && opts.driveMode !== undefined) {
+        // The one place a declared credential escapes paddock, and it escapes
+        // downstream of every rule this module enforces — see {@link argvExposure}.
+        notices.push(argvExposure(exposed, opts.driveMode));
+    }
+    if (opts.browserMcp && names.includes("playwright")) {
+        notices.push({
+            level: "warn",
+            message: `mcpServers.playwright collides with paddock's own browser server, which WINS — your ` +
+                `declaration is not attached. Set \`browserMcp: false\` to use yours instead.`,
+        });
+    }
+    return notices;
+}

package/packages/server/dist/routes/chats.js

@@ -584,7 +584,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         schema: {
             tags: ["Chats"],
             summary: "Delete a project chat",
-            description: "Deletes a project chat (session): removes its transcript JSONL and clears any archived/starred flag so a future session id can't inherit it. Responds 200 with `{ ok, removed }`.",
+            description: "Deletes a project chat (session) and clears any archived/starred flag so a future session id can't inherit it. Responds 200 with `{ ok, removed, retained }`. In a Claude home Paddock owns, the transcript JSONL is unlinked (`removed: true`). In a home it does NOT own the transcript is the user's own terminal `claude` history — Paddock plants no symlink there (#682), so there is no copy to delete — and the session is RELEASED instead: it leaves the chat list, the file stays on disk, and `retained` is true (#689).",
             params: {
                 type: "object",
                 properties: {
@@ -605,7 +605,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         try {
             const agent = await agentForSlug(req.params.slug);
             await cleanupAttachments(agent, req.params.sessionId);
-            const removed = await herdctl.deleteSession(agent, req.params.sessionId);
+            const { removed, retained } = await herdctl.deleteSession(agent, req.params.sessionId);
             // Drop any archived/starred/unread/detached flag so a future session id
             // can't inherit it. (Read-state watermarks, other users' unread overrides,
             // provenance and any queued message are deliberately NOT swept here — that
@@ -619,7 +619,7 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             // has to be cleared on the same path — otherwise a recycled session id
             // silently starts life detached from a parent it never had.
             await parentDetach.setDetached(agent, req.params.sessionId, false).catch(() => undefined);
-            return reply.code(200).send({ ok: true, removed });
+            return reply.code(200).send({ ok: true, removed, retained });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -1208,7 +1208,13 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                 try {
                     await cleanupAttachments(agent, sessionId);
                     const gone = await herdctl.deleteSession(agent, sessionId);
-                    if (gone)
+                    // `retained` counts as success here, and the distinction matters for
+                    // the flag-clearing below. These two buckets are "no longer in the
+                    // chat list" vs "still in it": a RELEASED chat (#689) left the list
+                    // even though its transcript survives on disk, so its flags must be
+                    // cleared like any other departure. Only a genuine failure — nothing
+                    // on disk to act on — belongs in `failed`.
+                    if (gone.removed || gone.retained)
                         removed.push(sessionId);
                     else
                         failed.push(sessionId);

package/packages/server/dist/transcripts.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whose transcripts this instance uses — the `claude.transcripts` config key.
+ *
+ * `own` = paddock's, inside the data dir / project. `host` = this machine's
+ * Claude Code, shared live. See the module doc for the mechanism.
+ */
+export type TranscriptsMode = "own" | "host";
+/** Isolation is the default: nothing outside the data dir is written (#691). */
+export declare const DEFAULT_TRANSCRIPTS_MODE: TranscriptsMode;
+/** Type guard, so an unknown config value falls back instead of failing a boot. */
+export declare function isKnownTranscriptsMode(value: string): value is TranscriptsMode;
 /**
  * Encode a working directory the way Claude Code names its transcript dir.
  * For paths under 200 chars this is just the non-alphanumeric→'-' replacement
@@ -8,7 +19,44 @@ export declare function encodeProjectDir(dir: string): string;
 /** Absolute path to the project's local transcript directory. */
 export declare function projectChatsDir(projectDir: string): string;
 /**
- * Ensure `<chatsHostDir>/.chats/` exists and that Claude Code's encoded
+ * The transcript folder a Claude home holds for `workingDir` —
+ * `<home>/projects/<encoded-cwd>`.
+ *
+ * The LITERAL path, before any symlink is followed, which is what makes it worth
+ * naming: it is the string Claude Code builds its session file AND its agent
+ * memory dir (`<here>/memory`) out of, and the agent harness refuses to write to
+ * any path with a `.claude` component in it (#690). Under paddock's own home it
+ * never has one, in either {@link TranscriptsMode}.
+ */
+export declare function encodedTranscriptDir(claudeHome: string, workingDir: string): string;
+/**
+ * Where a project's transcripts are planted, and where they point.
+ *
+ * `path` is the Claude home to plant the redirect symlink in, and it is REQUIRED
+ * — no default (#620). Callers must pass `cfg.claudeHome`: the engine is
+ * constructed with that same resolved value, and a symlink planted in a
+ * different home than the one the engine reads is exactly the "chats list but
+ * open empty" failure (#588). It used to default to the env-derived home for
+ * callers with no config, and `ensureSweeperHome` silently took that default —
+ * so the sweeper's symlink landed in a different home than every other agent's.
+ * Making the parameter required is what stops that class of bug at the type
+ * level.
+ *
+ * Since #691 paddock ALWAYS owns `path`, so the old `owned` flag is gone: the
+ * question it used to answer ("may we write here?") now has one answer, and the
+ * question that actually varies — whose transcripts these are — is
+ * {@link transcripts}.
+ */
+export interface ClaudeHomeTarget {
+    /** Absolute path to paddock's own Claude home (`cfg.claudeHome`). */
+    path: string;
+    /** Whose transcripts this instance uses (`cfg.claude.transcripts`). */
+    transcripts: TranscriptsMode;
+    /** The user's own `~/.claude` — the store under `transcripts: "host"`. */
+    userHome: string;
+}
+/**
+ * Ensure the project's transcript store exists and that Claude Code's encoded
  * transcript path for `workingDir` is a symlink pointing at it (migrating an
  * existing real transcript dir in the process). Safe to call on every agent
  * registration. Never throws — a failure here must not block agent registration
@@ -21,38 +69,21 @@ export declare function projectChatsDir(projectDir: string): string;
  * store stays in the project's metadata dir (the data repo) — so transcripts
  * never pollute the external repo's working tree — hence the two are split.
  *
- * `home.path` is the Claude home to plant the symlink in, and it is REQUIRED —
- * no default (#620). Callers must pass `cfg.claudeHome`: the engine is
- * constructed with that same resolved value, and a symlink planted in a
- * different home than the one the engine reads is exactly the "chats list but
- * open empty" failure (#588). It used to default to the env-derived home for
- * callers with no config, and `ensureSweeperHome` silently took that default —
- * so the sweeper's symlink landed in a different home than every other agent's.
- * Making the parameter required is what stops that class of bug at the type
- * level.
- *
- * `home.owned` gates EVERY write into the home (#620, #682). Two of them:
+ * The store is `<chatsHostDir>/.chats/` under `transcripts: "own"` and the user's
+ * own `~/.claude/projects/<encoded-cwd>/` under `transcripts: "host"`; everything
+ * below is the same code either way.
  *
- *  - Migrating an existing real transcript directory into `.chats/` copies the
- *    files and then REMOVES the originals. That is correct self-healing inside a
- *    home paddock owns, where such a directory can only be paddock's own doing.
- *    Inside the user's `~/.claude` it is somebody else's data — a `claude` CLI
- *    session run in a directory paddock happens to also manage — so we leave it
- *    strictly alone and let the SDK keep writing there.
- *  - Planting the redirect symlink at a path that does not exist yet. Not
- *    destructive on the day it happens, which is why it was missed, but it
- *    silently claims where the user's FUTURE sessions for that directory get
- *    written (#682). See the branch itself for the full argument.
+ * ## The one write into `~/.claude`, and why it is not the #682 mistake
  *
- * Either way those transcripts stay importable through adoption (#588), which is
- * the deliberate, user-driven version of the same move.
+ * Under `host` this creates `~/.claude/projects/<encoded-cwd>/` if it is missing,
+ * because a symlink to a non-existent directory is not something Claude Code can
+ * `mkdir -p` through. That is a directory Claude Code itself would create the
+ * first time the user ran `claude` there, made under a config key whose entire
+ * meaning is "share the host's transcripts". #682 was the opposite: planting a
+ * link that silently REDIRECTED the user's future sessions into paddock's store
+ * on an instance that had asked for no such thing. Under `own` — the default —
+ * nothing under `~/.claude` is created, read or written at all.
  */
-export interface ClaudeHomeTarget {
-    /** Absolute path to the Claude home to plant the redirect symlink in. */
-    path: string;
-    /** Whether paddock owns this home — see `PaddockConfig.ownsClaudeHome`. */
-    owned: boolean;
-}
 export declare function ensureProjectChats(workingDir: string, chatsHostDir: string, home: ClaudeHomeTarget): Promise<void>;
 /**
  * Read a session's FIRST user message text, untruncated, straight from its