@edspencer/paddock 0.61.0 → 0.62.0

package/packages/server/dist/claude-home.d.ts

@@ -1,26 +1,95 @@
 import type { PaddockConfig } from "./config.js";
 /**
- * Entries of a Claude home that are USER-LEVEL configuration rather than
- * per-instance state, symlinked from the user's home into paddock's own when
- * paddock's does not already have its own.
- *
- * Without this, relocating the home silently changes agent behaviour: the user's
- * `~/.claude/CLAUDE.md` is auto-loaded into every session, `settings.json`
- * carries permissions and hooks, and `agents/` `commands/` `plugins/` are
- * capability. Dropping them is not "a clean home", it is a behaviour regression
- * nobody asked for.
- *
- * `.credentials.json` is the one that matters most: on Linux (and in the Docker
- * image) it is where `claude login` puts the OAuth token, so without the bridge
- * every file-authenticated install would come back logged out. Symlinked rather
- * than copied — a copy would duplicate a live secret onto disk AND diverge the
- * moment Claude Code refreshed the token.
- *
- * Deliberately NOT bridged: `projects/` (that's the whole point), and everything
- * that is per-instance runtime state — `todos/`, `shell-snapshots/`, `statsig/`,
- * `sessions/`. Those are exactly what should now be per-instance.
+ * The user's file-based Claude Code login, bridged in only under
+ * `claude.credentials: host` (#691).
+ *
+ * This is what the lever means on Linux and in the Docker image, where `claude
+ * login` writes a file rather than using a keychain: on darwin `credentials: host`
+ * is the `CLAUDE_SECURESTORAGE_CONFIG_DIR` empty-string trick, here it is this
+ * symlink, and one config key has to mean the same thing on both.
+ *
+ * Symlinked rather than copied — a copy would duplicate a live secret onto disk
+ * AND diverge the moment Claude Code refreshed the token.
+ *
+ * It was bridged unconditionally before the lever existed, which is why
+ * `credentials` defaulting to `host` keeps every existing install working
+ * unchanged; `own` is the new behaviour, and it has to also REMOVE a link a
+ * previous boot planted, or "isolated" would be a claim that only holds for
+ * instances that were never anything else.
+ */
+export declare const CREDENTIAL_ENTRY = ".credentials.json";
+/**
+ * Entries of the user's Claude home that paddock can bridge into its own — the
+ * complete list, for callers that want to reason about the surface rather than
+ * about one lever.
+ *
+ * There is no longer an "always bridged" set: since #691 step 4, every entry here
+ * belongs to exactly one key of the `claude:` block, and the mapping is the whole
+ * point of the block.
+ *
+ * | Entry | Lever |
+ * |---|---|
+ * | `CLAUDE.md`, `agents/`, `commands/`, `plugins/` | `claude.instructions` |
+ * | `settings.json` (its `hooks` key) | `claude.hooks` |
+ * | `.credentials.json` | `claude.credentials` |
+ *
+ * `settings.json` appears under `hooks` because that is the half of it a lever
+ * governs; its OTHER keys — permissions, model, statusline, `enabledPlugins` —
+ * are inherited in every mode, which is why `hooks: own` writes a filtered file
+ * rather than declining to bridge one. See `claude-settings.ts`.
+ *
+ * Deliberately NOT bridged in any mode: `projects/` (that's the whole point), and
+ * everything that is per-instance runtime state — `todos/`, `shell-snapshots/`,
+ * `statsig/`, `sessions/`. Those are exactly what should be per-instance.
+ *
+ * The fifth lever, `claude.mcpServers`, has NO row here on purpose: MCP servers
+ * are declared in `~/.claude.json`, which is a sibling of the home rather than an
+ * entry inside it, so it is not bridgeable at all — paddock reads it and passes
+ * the servers programmatically (`claude-mcp.ts`). That asymmetry is the reason
+ * MCP inheritance broke separately from everything in this table.
+ */
+export declare const BRIDGEABLE_ENTRIES: readonly string[];
+/**
+ * What a Keychain probe concluded.
+ *
+ * `unknown` is the important one and the default: not darwin, no `security`
+ * binary, the lookup errored, or we simply did not find an entry under a name we
+ * guessed. It must never be reported to the user as "you have no login".
+ */
+export type KeychainFinding = "found" | "unknown";
+/** Probe for a macOS login paddock's own home cannot see. Injectable for tests. */
+export type KeychainProbe = () => Promise<KeychainFinding>;
+/**
+ * Ask the macOS Keychain whether a plain-name Claude Code login exists (#683).
+ *
+ * The whole value of this is turning "you appear to have no credentials" into
+ * "you ARE logged in; paddock cannot see it, and here is the one-liner" — a
+ * distinction paddock currently cannot make, and the difference between a
+ * message that describes a problem and one that fixes it.
+ *
+ * ## The asymmetry, which is deliberate
+ *
+ * A positive result is trustworthy: an entry under that service name is a login.
+ * A negative result is NOT — `security` can fail for a dozen reasons that have
+ * nothing to do with the user, and the service name, though now read straight out
+ * of the SDK bundle rather than guessed, is still Claude Code's internal detail
+ * and can change. So a miss returns `unknown`, and the caller falls back to the
+ * existing, correct, generic warning. Being wrong about the name therefore costs
+ * nothing beyond the improvement not happening.
+ *
+ * Never prompts and never reads a secret: `find-generic-password` WITHOUT `-w`
+ * reports existence only (attributes, which are discarded), so nothing sensitive
+ * reaches a log, a transcript, or this process's memory.
+ *
+ * One known imprecision, left in on purpose: Claude Code's own lookup also passes
+ * `-a` (`process.env.USER`, falling back to the OS username), and this does not.
+ * So an entry filed under a DIFFERENT account still reads as `found` here while
+ * Claude Code would miss it — a service running under a different `USER` than the
+ * terminal that logged in. Matching that exactly would trade a rare false
+ * positive for a rarer false negative, and a false negative is the one that costs
+ * something: it downgrades a specific instruction back to the generic warning.
  */
-export declare const BRIDGED_ENTRIES: readonly [".credentials.json", "settings.json", "CLAUDE.md", "agents", "commands", "plugins"];
+export declare function probeMacosKeychainLogin(platform?: string): Promise<KeychainFinding>;
 /** A message for the operator, at the level it should be logged at. */
 export interface ClaudeHomeNotice {
     level: "info" | "warn";
@@ -29,21 +98,48 @@ export interface ClaudeHomeNotice {
 export interface ClaudeHomeReport {
     /** Entries symlinked in from the user's home this boot. */
     bridged: string[];
+    /**
+     * Entries whose bridge symlink was REMOVED this boot because the lever that
+     * governs them now says `own` (#691).
+     *
+     * The bridge is non-clobbering, so without this an instance that was ever
+     * `host` would keep reading the user's file forever after being reconfigured —
+     * "isolated" would be a claim that only holds for instances that were never
+     * anything else.
+     */
+    withdrawn: string[];
+    /**
+     * Entries paddock WROTE into its own home this boot rather than symlinking,
+     * because a lever needs part of a file and not the whole of it. Only
+     * `settings.json` today — see `claude-settings.ts`.
+     */
+    generated: string[];
     /** Messages for `app.ts` to log — config resolution has no logger of its own. */
     notices: ClaudeHomeNotice[];
 }
 /**
- * Create paddock's Claude home and bridge the user-level config into it.
+ * Create paddock's Claude home and put the user-level config into it that this
+ * instance's `claude:` levers say it should have (#691).
  *
- * Idempotent and non-clobbering: an entry paddock's home already has (whether a
- * real file the user put there or a symlink from a previous boot) is left
- * completely alone, so this is safe to run on every start.
+ * Idempotent and non-clobbering: a real file the user put in paddock's home is
+ * left completely alone, so this is safe to run on every start. What it DOES
+ * maintain is what paddock itself planted — bridge symlinks, withdrawn when a
+ * lever flips to `own`, and the generated `settings.json`, regenerated from the
+ * user's current one. Ownership of a generated file is decided by hash
+ * ({@link classifyOwnEntry}), never by "it is at a name we use".
  *
  * Never throws. A home that cannot be created is not a reason to refuse to boot
  * — Claude Code falls back to its own default and chat still works, which is the
  * same failure mode `ensureProjectChats` has always had.
+ *
+ * **Mutates `env`** (`process.env` by default) to carry `claude.credentials` into
+ * the environment Claude Code runs in — see {@link applyCredentialsMode} for why
+ * that is the only seam available and why it is safe process-wide. Done here
+ * because this is already the one call that runs before the fleet starts, and
+ * because the credential warning below has to describe the environment it just
+ * set rather than the one it found.
  */
-export declare function ensureClaudeHome(cfg: Pick<PaddockConfig, "claudeHome" | "legacyClaudeHome" | "ownsClaudeHome">, env?: NodeJS.ProcessEnv): Promise<ClaudeHomeReport>;
+export declare function ensureClaudeHome(cfg: Pick<PaddockConfig, "claudeHome" | "legacyClaudeHome" | "claude">, env?: NodeJS.ProcessEnv, probeKeychain?: KeychainProbe): Promise<ClaudeHomeReport>;
 /** One of the user's transcript folders, made readable through paddock's home. */
 export interface LegacyMirror {
     /** Folder name inside `<claudeHome>/projects/` — `encodePathForCli(engineCwd)`. */
@@ -107,6 +203,14 @@ export declare function legacySourcePath(legacyHome: string, folderName: string)
  * mirroring them would re-offer paddock's own chats as "adoptable". That also
  * makes the leftovers from before this change inert rather than confusing.
  *
+ * A folder paddock's own home ALREADY links to directly is skipped for the same
+ * reason. That is the `claude.transcripts: host` case (#691): there the folder in
+ * the user's home is a real directory that paddock itself writes through, so
+ * mirroring it would offer every project's own live chats back as importable —
+ * the #658 mistake with the arrow reversed. (Adoption de-duplicates sources by
+ * resolved real path, so this was noise rather than breakage; it is skipped here
+ * because a link paddock plants and then mirrors is confusing to find on disk.)
+ *
  * Idempotent and never throws. Returns every mirror it maintains, not only the
  * ones planted this call, so a caller can rely on the mapping after any call.
  */
@@ -123,3 +227,38 @@ export declare function mirrorLegacyTranscriptFolders(claudeHome: string, legacy
  * there is the entire point.
  */
 export declare function countLegacyTranscriptLinks(legacyHome: string, dataDir: string): Promise<number>;
+/** A `~/.claude/projects/<enc>` symlink pointing at some `.chats/` store. */
+export interface PlantedChatsLink {
+    /** The link itself, inside the user's home — the path to tell the user about. */
+    link: string;
+    /** What it points at, resolved. Always a `.chats` directory by construction. */
+    target: string;
+    /** Does the target still exist? A dangling link is the one that breaks tooling. */
+    dangling: boolean;
+}
+/**
+ * Find transcript symlinks planted in the user's home that point at a `.chats/`
+ * store OUTSIDE `dataDir` (#682).
+ *
+ * The instance's own leftovers — links into this data dir — are already reported
+ * by {@link countLegacyTranscriptLinks} as harmless pre-#620 residue, and they
+ * are: they were planted for a project whose transcripts paddock does own.
+ *
+ * The ones this finds are the poisoned kind. Under `--here` the workspace's
+ * `.chats/` sits at `<dir>/.chats` while the data dir is `<dir>/.paddock`, so a
+ * link planted by an affected build points somewhere no `dataDir` prefix match
+ * will ever catch. While it exists, every `claude` session the user starts in
+ * that directory writes into paddock's store instead of their own history, and
+ * anything that expects `~/.claude/projects/<enc>` to be a real directory
+ * (`unzip -d ~/.claude` being the observed one) fails with an error impossible
+ * to trace back here.
+ *
+ * Reported, never removed. Paddock not writing to `~/.claude` is the entire
+ * point of #620, and that has to include cleaning up after itself — a boot that
+ * silently deleted something under there would be the same class of surprise in
+ * the opposite direction. Naming the exact path is enough: `rm` is one command
+ * and the user can see what they are removing first.
+ *
+ * Never throws; an unreadable home just yields no findings.
+ */
+export declare function findPlantedChatsLinks(legacyHome: string, dataDir: string): Promise<PlantedChatsLink[]>;