/** * `CM_UAT_ISOLATION=1` — the mode a UAT / daily-check server and its CLI run in * (Issue #3360). * * A UAT server is isolated from production by its own port, DB, tmux socket and * state directories (`.commandmate/uat.yaml`). Three paths were left that those * do not cover, because they are keyed by the user's login rather than by * anything the UAT can move: * * 1. **codex's shared files.** `$CODEX_HOME/hooks.json`, the relay under * `$CODEX_HOME/commandmate/` and the hook trust in `config.toml` live beside * codex's login (`auth.json`), so moving `CODEX_HOME` logs codex out. In this * mode the server writes none of them: it reuses the shared file only when it * is already byte-identical to what this build would write (the per-session * URL travels in the environment, so the hooks then reach THIS server), and * otherwise refuses the launch ({@link UatIsolationLaunchRefusedError}) — * a bare codex would still read the shared file and run production's hooks. * antigravity's `~/.gemini/config/hooks.json` and copilot's * `~/.copilot/settings.json` (Issue #3391) are handled the same way. It * also never answers the hook review with *trust*, which is codex writing * `config.toml`. * 2. **claude's user-level hooks.** `--settings` is added to * `~/.claude/settings.json`, not substituted for it, so the user's own hooks * (which post to production) would run in a UAT session too. Moving * `CLAUDE_CONFIG_DIR` logs claude out (measured, `-p` and interactive). In * this mode claude is launched with `--setting-sources project,local`, which * drops the user source and keeps `--settings` (measured on 2.1.289) — the * interactive launch and `claude -p` (Schedules, daily summary) alike. * 3. **the CLI's `.env`.** A client in this mode reads no `.env` file at all and * refuses to fall back to port 3000: it dials only the `CM_PORT` the caller * exported. * * Unset (or any value other than `1` / `own-home`) changes nothing anywhere. * * ## `CM_UAT_ISOLATION=own-home` (Issue #3312) * * For a run under a dedicated OS user (the daily product-path check), whose * HOME holds nobody else's CLI config. Everything above still holds — the * launch is refused rather than started bare when hook setup fails, the * receiver URL travels in the launch environment, headless `codex exec` / * `agy -p` are refused, claude reads no user-level settings, the CLI reads no * `.env` and never falls back to 3000 — with one difference: the shared hook * files (codex's `hooks.json`, relay and trust, antigravity's and copilot's * hook files, the claude settings under `CM_AGENT_HOOKS_DIR`) are WRITTEN by * this build, instead of being reused read-only. Only after * {@link assertUatOwnHomeWriteTargets} has checked, before each launch, that * this process runs as `CM_UAT_DEDICATED_USER`, that HOME is that user's, and * that every file it is about to write resolves (symlinks followed) to a place * inside that HOME owned by that user. {@link sharedHookWritePolicy} is the one * rule each tool's launch path calls. * * `docs/user-guide/uat-isolation.md` has the measurement table and the skip * conditions for what cannot be isolated. * * @module config/uat-isolation */ /** The switch. Only the exact values `1` and `own-home` turn it on. */ export declare const UAT_ISOLATION_ENV_VAR = "CM_UAT_ISOLATION"; /** The value of {@link UAT_ISOLATION_ENV_VAR} for a run under a dedicated OS user (Issue #3312). */ export declare const UAT_ISOLATION_OWN_HOME = "own-home"; /** The login name `own-home` must run as (Issue #3312). Compared with `os.userInfo().username`. */ export declare const UAT_DEDICATED_USER_ENV_VAR = "CM_UAT_DEDICATED_USER"; /** * - `off`: not isolated. * - `shared-read-only` (`1`): the shared hook files are reused only when they * already match this build, never written. * - `own-home`: the shared hook files are written, inside the dedicated user's * own HOME only (Issue #3312). */ export type UatIsolationMode = 'off' | 'shared-read-only' | 'own-home'; /** * `--setting-sources` for a claude session in this mode: the user source * (`$CLAUDE_CONFIG_DIR/settings.json`, hooks and plugins included) is dropped; * the repository's own `project` / `local` settings and `--settings` stay. */ export declare const CLAUDE_UAT_SETTING_SOURCES = "project,local"; type Env = Readonly>; /** Which isolation mode this process runs in. */ export declare function getUatIsolationMode(env?: Env): UatIsolationMode; /** * Whether this process runs in UAT isolation mode — `1` or `own-home`. Every * protection except "never write the shared hook files" keys off this. */ export declare function isUatIsolationEnabled(env?: Env): boolean; /** * Thrown by a launch that would otherwise start an agent which reads a shared * hook config this server did not (and in this mode may not) write. * * Starting the agent "without hooks" is not an option for codex, antigravity * or copilot: the shared file is read regardless of what this server passes, * so the production server's hooks — already trusted — would run in the UAT * session and post to production. So the launch is refused, and the message says what * makes it start. */ export declare class UatIsolationLaunchRefusedError extends Error { constructor(tool: string, reason: string, fix: string); } /** The fix for a shared hook config that does not match this build. */ export declare const UAT_SAME_BUILD_FIX = "Run the UAT with the same CommandMate build as the production server, so the shared file already matches what this build writes."; /** The fix for an `own-home` launch whose user, HOME or write targets did not check out. */ export declare const UAT_OWN_HOME_FIX: string; /** Who this process is. `os.userInfo()` reads the account database, not `$HOME`. */ export interface ProcessIdentity { username: string; uid: number; homedir: string; } /** * Why an `own-home` launch may not write `writeTargets`, or null when it may * (Issue #3312). Checks, in this order: `CM_UAT_DEDICATED_USER` is set and is * the user this process runs as; `HOME` resolves to that user's home directory * (from the account database) and is owned by them; each target resolves — * every symlink on the way followed — to a path inside that home, and the entry * that decides the write (the target, or its nearest existing ancestor) is * owned by that user. */ export declare function checkUatOwnHomeWriteTargets(writeTargets: readonly string[], env?: Env, identity?: ProcessIdentity): string | null; /** * Under `own-home`, refuse the launch of `tool` unless * {@link checkUatOwnHomeWriteTargets} passes for `writeTargets`. A no-op in * every other mode. * * @throws {UatIsolationLaunchRefusedError} */ export declare function assertUatOwnHomeWriteTargets(tool: string, writeTargets: readonly string[], env?: Env): void; /** * The one rule for a hook file shared with the user's other CommandMate * servers (codex, antigravity and copilot call it; Issue #3312): * * - not isolated: `write` * - `CM_UAT_ISOLATION=1`: `read-only` — reuse it only when it already matches * - `CM_UAT_ISOLATION=own-home`: `write`, once * {@link assertUatOwnHomeWriteTargets} has passed for every path the write * touches; otherwise the launch is refused * * @throws {UatIsolationLaunchRefusedError} Under `own-home` only */ export declare function sharedHookWritePolicy(tool: string, writeTargets: readonly string[], env?: Env): 'write' | 'read-only'; export {}; //# sourceMappingURL=uat-isolation.d.ts.map