commandmate 0.44.1 → 0.44.3

package/dist/cli/utils/api-client.js

@@ -9,16 +9,18 @@
  * - ApiClient: HTTP get/post with base URL and auth headers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiError = exports.ApiClient = exports.MAX_STOP_PATTERN_LENGTH = void 0;
+exports.ApiError = exports.ApiClient = exports.FOREIGN_SESSION_ERROR_CODE = exports.MAX_STOP_PATTERN_LENGTH = void 0;
 exports.isValidWorktreeId = isValidWorktreeId;
 exports.isValidInstanceId = isValidInstanceId;
 exports.resolveAuthToken = resolveAuthToken;
+exports.foreignSessionMessage = foreignSessionMessage;
 exports.handleApiError = handleApiError;
 exports.assertResponseShape = assertResponseShape;
 exports.fetchDaemonVersion = fetchDaemonVersion;
 exports.warnIfVersionSkew = warnIfVersionSkew;
 const types_1 = require("../types");
 const package_info_1 = require("./package-info");
+const uat_isolation_1 = require("../../config/uat-isolation");
 const server_url_1 = require("./server-url");
 /** Maximum stop-pattern length [SEC4-06] */
 exports.MAX_STOP_PATTERN_LENGTH = 500;
@@ -91,6 +93,30 @@ function serverErrorDetail(payload) {
 function withServerUrl(message, context) {
     return context?.serverUrl ? `${message} (server: ${context.serverUrl})` : message;
 }
+/**
+ * The `code` the server sends with the 409 for a tmux session another
+ * CommandMate server created (Issue #2865). Spelled out rather than imported:
+ * the server's constant lives next to the tmux gateway, which the CLI must not
+ * load. `tests/unit/cli/utils/api-client-foreign-session-3334.test.ts` pins the
+ * two to the same string.
+ */
+exports.FOREIGN_SESSION_ERROR_CODE = 'session_owned_by_other_server';
+/**
+ * Issue #3334: what the operator reads for that 409. It has to say three
+ * things the status alone does not: the session is another CommandMate
+ * server's, this command therefore did nothing to it, and where to go instead.
+ */
+function foreignSessionMessage(payload) {
+    const name = typeof payload?.sessionName === 'string' && payload.sessionName !== ''
+        ? `"${payload.sessionName}" `
+        : '';
+    const where = typeof payload?.sessionPath === 'string' && payload.sessionPath !== ''
+        ? ` (it was started in ${payload.sessionPath})`
+        : '';
+    return (`The tmux session ${name}belongs to another CommandMate server${where}, ` +
+        'so nothing was sent to it, read from it or stopped. ' +
+        'Use the CommandMate server that started it, or stop that session there first.');
+}
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
@@ -98,8 +124,9 @@ function withServerUrl(message, context) {
  * @param error - Error object or unknown
  * @param status - HTTP status code if available
  * @param payload - Parsed error body, when the response carried one (Issue #1637).
- *   Used for 5xx only: the 4xx messages below are already specific, and are
- *   pinned by tests as the CLI's own wording.
+ *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
+ *   messages below are already specific, and are pinned by tests as the CLI's
+ *   own wording.
  * @param context - Which server answered, when the caller knows (Issue #2404).
  *   Read by the 404 branch only; the other messages do not send anyone looking
  *   in the wrong place.
@@ -139,6 +166,23 @@ function handleApiError(error, status, payload, context) {
                     message: withServerUrl('Resource not found. Check the worktree ID.', context),
                     exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
                 };
+            case 409:
+                // Issue #3334: the one 409 every session route shares (#2865 / #3290).
+                // Without this it read "Unexpected HTTP status: 409", which does not say
+                // that nothing was done, nor why. Same exit code as that default branch,
+                // so a script branching on it sees no change. Every other 409 keeps the
+                // default wording below — the commands that own one (send's
+                // PROMPT_WAITING, verify's running run) already explain it themselves.
+                if (payload?.code === exports.FOREIGN_SESSION_ERROR_CODE) {
+                    return {
+                        message: foreignSessionMessage(payload),
+                        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
+                    };
+                }
+                return {
+                    message: `Unexpected HTTP status: ${status}`,
+                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
+                };
             case 429:
                 return {
                     message: 'Rate limited. Please retry after a moment.',
@@ -219,6 +263,11 @@ class ApiClient {
         // *under* process.env — see its doc comment for why that order is the reverse of the one
         // `status` uses. resolveServerEndpoint() then applies the same CM_BIND / CM_HTTPS_CERT +
         // CM_HTTPS_KEY rules as `status`, which the old hardcoded `http://localhost:` ignored.
+        // Issue #3360: in UAT isolation the default port 3000 is the user's production server,
+        // so a client that was not told where to go must not go anywhere.
+        if (!options?.baseUrl && (0, uat_isolation_1.isUatIsolationEnabled)() && !process.env.CM_PORT) {
+            throw new ApiError(`${uat_isolation_1.UAT_ISOLATION_ENV_VAR}=${process.env[uat_isolation_1.UAT_ISOLATION_ENV_VAR]} requires CM_PORT: refusing to fall back to the default port 3000.`, types_1.ExitCode.CONFIG_ERROR);
+        }
         this.baseUrl = options?.baseUrl || (0, server_url_1.resolveServerEndpoint)((0, server_url_1.loadClientEnv)()).url;
         this.token = resolveAuthToken(options);
         // [SEC4-02] Warn about HTTP to non-localhost
@@ -229,9 +278,11 @@ class ApiClient {
     /**
      * The base URL this client actually dials (Issue #2404).
      *
-     * Resolved once in the constructor through the precedence in
-     * `loadClientEnv()` (`--base-url` > exported `CM_PORT` > `~/.commandmate/.env`
-     * > 3000), which is why it is read from here rather than re-derived by each
+     * Resolved once in the constructor: the `baseUrl` option when a caller passes
+     * one (there is no CLI flag for it), else `CM_PORT` / `CM_BIND` through the
+     * precedence in `loadClientEnv()` (exported > `~/.commandmate/.env` > 3000;
+     * under `CM_UAT_ISOLATION=1` exported only, never 3000), which is why it is
+     * read from here rather than re-derived by each
      * caller: a second derivation is a second answer, and "which server did this
      * command talk to" only helps if it is the one the request went to.
      */
@@ -300,31 +351,7 @@ class ApiClient {
      * [DR1-05] Generic type parameter specified at call site
      */
     async post(path, body) {
-        try {
-            const response = await fetch(`${this.baseUrl}${path}`, {
-                method: 'POST',
-                headers: this.getHeaders(),
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-            });
-            if (!response.ok) {
-                // Issue #1637: read the body first — handleApiError needs it to surface
-                // the server's reason for a 5xx instead of "check the logs".
-                const payload = await readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
-                throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
-            }
-            // Handle 204 No Content
-            const text = await response.text();
-            if (!text)
-                return undefined;
-            return JSON.parse(text);
-        }
-        catch (error) {
-            if (error instanceof ApiError)
-                throw error;
-            const errResult = handleApiError(error);
-            throw new ApiError(errResult.message, errResult.exitCode);
-        }
+        return sendWithBody(this.baseUrl, 'POST', this.getHeaders(), path, body);
     }
     /**
      * HTTP PATCH request (Issue #1000: agent-instance roster mutations via
@@ -332,33 +359,38 @@ class ApiClient {
      * [DR1-05] Generic type parameter specified at call site
      */
     async patch(path, body) {
-        try {
-            const response = await fetch(`${this.baseUrl}${path}`, {
-                method: 'PATCH',
-                headers: this.getHeaders(),
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-            });
-            if (!response.ok) {
-                // Issue #1637: read the body first — handleApiError needs it to surface
-                // the server's reason for a 5xx instead of "check the logs".
-                const payload = await readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
-                throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
-            }
-            const text = await response.text();
-            if (!text)
-                return undefined;
-            return JSON.parse(text);
-        }
-        catch (error) {
-            if (error instanceof ApiError)
-                throw error;
-            const errResult = handleApiError(error);
-            throw new ApiError(errResult.message, errResult.exitCode);
-        }
+        return sendWithBody(this.baseUrl, 'PATCH', this.getHeaders(), path, body);
     }
 }
 exports.ApiClient = ApiClient;
+/** POST / PATCH share everything but the method; an empty body (204) is `undefined`. */
+async function sendWithBody(baseUrl, method, headers, path, body) {
+    try {
+        const response = await fetch(`${baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            // Issue #1637: read the body first — handleApiError needs it to surface
+            // the server's reason for a 5xx instead of "check the logs".
+            const payload = await readErrorPayload(response);
+            const errResult = handleApiError(null, response.status, payload, { serverUrl: baseUrl });
+            throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+        }
+        // Handle 204 No Content
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof ApiError)
+            throw error;
+        const errResult = handleApiError(error);
+        throw new ApiError(errResult.message, errResult.exitCode);
+    }
+}
 /**
  * Read the typed error body of a failed response.
  *

package/dist/cli/utils/server-url.d.ts

@@ -80,6 +80,7 @@ export declare function loadEnvFileValues(envPath?: string): Record<string, stri
  * reported the .env port.
  *
  * Resolution order: `process.env` > `~/.commandmate/.env` > resolveServerEndpoint() defaults.
+ * Under `CM_UAT_ISOLATION=1` the file layer is skipped (Issue #3360).
  *
  * Neither of the two consults the file *alone*; {@link loadEnvFileValues} is the loader for
  * the question where the shell must not appear as a layer at all.

package/dist/cli/utils/server-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-url.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAErE,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,cAAc,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAWpE;AAaD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAQzC"}
+{"version":3,"file":"server-url.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAErE,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,cAAc,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAWpE;AAaD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAazC"}

package/dist/cli/utils/server-url.js

@@ -14,6 +14,7 @@ exports.loadEffectiveEnv = loadEffectiveEnv;
 exports.loadEnvFileValues = loadEnvFileValues;
 exports.loadClientEnv = loadClientEnv;
 const dotenv_1 = require("dotenv");
+const uat_isolation_1 = require("../../config/uat-isolation");
 const env_setup_1 = require("./env-setup");
 /**
  * Resolve the endpoint a server started with `env` is reachable at.
@@ -104,11 +105,17 @@ function loadEnvFileValues(envPath) {
  * reported the .env port.
  *
  * Resolution order: `process.env` > `~/.commandmate/.env` > resolveServerEndpoint() defaults.
+ * Under `CM_UAT_ISOLATION=1` the file layer is skipped (Issue #3360).
  *
  * Neither of the two consults the file *alone*; {@link loadEnvFileValues} is the loader for
  * the question where the shell must not appear as a layer at all.
  */
 function loadClientEnv() {
+    // Issue #3360: a UAT / daily-check client (`CM_UAT_ISOLATION=1`) reads no .env at all —
+    // not ~/.commandmate/.env (global install), not ./.env (local) — so the target is only
+    // ever what the caller exported. ApiClient refuses to fall back to 3000 in this mode.
+    if ((0, uat_isolation_1.isUatIsolationEnabled)())
+        return { ...process.env };
     // parseEnvFile() is a read-only lookup: left to its defaults dotenv would populate
     // process.env with every key the file defines, turning file values into "exported" ones
     // for the rest of the process — the precedence this function exists to avoid.

package/dist/config/uat-isolation.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `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<Record<string, string | undefined>>;
+/** 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

package/dist/config/uat-isolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uat-isolation.d.ts","sourceRoot":"","sources":["../../src/config/uat-isolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAMH,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD,oGAAoG;AACpG,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,kBAAkB,CAAC;AAE1D,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAExD,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,GAAiB,GAAG,gBAAgB,CAK5E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,GAAiB,GAAG,OAAO,CAErE;AAED;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAYtD;AAED,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,qIACqG,CAAC;AAErI,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,QAEqF,CAAC;AAEnH,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,GAAG,GAAE,GAAiB,EACtB,QAAQ,GAAE,eAAmC,GAC5C,MAAM,GAAG,IAAI,CAgCf;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,GAAG,GAAE,GAAiB,GACrB,IAAI,CAIN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,GAAG,GAAE,GAAiB,GACrB,OAAO,GAAG,WAAW,CAKvB"}

package/dist/config/uat-isolation.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * `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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAT_OWN_HOME_FIX = exports.UAT_SAME_BUILD_FIX = exports.UatIsolationLaunchRefusedError = exports.CLAUDE_UAT_SETTING_SOURCES = exports.UAT_DEDICATED_USER_ENV_VAR = exports.UAT_ISOLATION_OWN_HOME = exports.UAT_ISOLATION_ENV_VAR = void 0;
+exports.getUatIsolationMode = getUatIsolationMode;
+exports.isUatIsolationEnabled = isUatIsolationEnabled;
+exports.checkUatOwnHomeWriteTargets = checkUatOwnHomeWriteTargets;
+exports.assertUatOwnHomeWriteTargets = assertUatOwnHomeWriteTargets;
+exports.sharedHookWritePolicy = sharedHookWritePolicy;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/** The switch. Only the exact values `1` and `own-home` turn it on. */
+exports.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). */
+exports.UAT_ISOLATION_OWN_HOME = 'own-home';
+/** The login name `own-home` must run as (Issue #3312). Compared with `os.userInfo().username`. */
+exports.UAT_DEDICATED_USER_ENV_VAR = 'CM_UAT_DEDICATED_USER';
+/**
+ * `--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.
+ */
+exports.CLAUDE_UAT_SETTING_SOURCES = 'project,local';
+/** Which isolation mode this process runs in. */
+function getUatIsolationMode(env = process.env) {
+    const value = env[exports.UAT_ISOLATION_ENV_VAR];
+    if (value === '1')
+        return 'shared-read-only';
+    if (value === exports.UAT_ISOLATION_OWN_HOME)
+        return 'own-home';
+    return 'off';
+}
+/**
+ * Whether this process runs in UAT isolation mode — `1` or `own-home`. Every
+ * protection except "never write the shared hook files" keys off this.
+ */
+function isUatIsolationEnabled(env = process.env) {
+    return getUatIsolationMode(env) !== 'off';
+}
+/**
+ * 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.
+ */
+class UatIsolationLaunchRefusedError extends Error {
+    constructor(tool, reason, fix) {
+        super(getUatIsolationMode() === 'own-home'
+            ? `${exports.UAT_ISOLATION_ENV_VAR}=${exports.UAT_ISOLATION_OWN_HOME}: refusing to start ${tool}: ${reason}. ` +
+                `This server writes the hook config only inside the dedicated user's own HOME, and ${tool} ` +
+                `would otherwise start with hooks this server did not prepare. ${fix}`
+            : `${exports.UAT_ISOLATION_ENV_VAR}=1: refusing to start ${tool}: ${reason}. ` +
+                `This server does not write the shared hook config in UAT isolation, and ${tool} ` +
+                `would read it anyway and run the production hooks. ${fix}`);
+        this.name = 'UatIsolationLaunchRefusedError';
+    }
+}
+exports.UatIsolationLaunchRefusedError = UatIsolationLaunchRefusedError;
+/** The fix for a shared hook config that does not match this build. */
+exports.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. */
+exports.UAT_OWN_HOME_FIX = `Run ${exports.UAT_ISOLATION_ENV_VAR}=${exports.UAT_ISOLATION_OWN_HOME} as the user named by ${exports.UAT_DEDICATED_USER_ENV_VAR}, ` +
+    'with HOME set to that user\'s home and every hook config path (CODEX_HOME, CM_AGENT_HOOKS_DIR, ...) inside it.';
+function currentIdentity() {
+    const info = os_1.default.userInfo();
+    return { username: info.username, uid: info.uid, homedir: info.homedir };
+}
+/**
+ * Where a write to `target` would land, symlinks followed, and whose entry
+ * decides who may write there: the target itself when it exists, else its
+ * nearest existing ancestor (a file not yet created is judged by the directory
+ * it would be created in). A dangling symlink is refused: writing through it
+ * would create a file wherever it points.
+ */
+function resolveWriteTarget(target) {
+    const absolute = path_1.default.resolve(target);
+    let existing = absolute;
+    const rest = [];
+    for (;;) {
+        let entryExists = false;
+        try {
+            fs_1.default.lstatSync(existing);
+            entryExists = true;
+        }
+        catch {
+            entryExists = false;
+        }
+        if (entryExists)
+            break;
+        const parent = path_1.default.dirname(existing);
+        if (parent === existing)
+            return `${target} has no existing ancestor`;
+        rest.unshift(path_1.default.basename(existing));
+        existing = parent;
+    }
+    let real;
+    try {
+        real = fs_1.default.realpathSync(existing);
+    }
+    catch {
+        return `${existing} is a symlink that points nowhere`;
+    }
+    return { real: path_1.default.join(real, ...rest), owner: fs_1.default.statSync(real).uid };
+}
+/**
+ * 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.
+ */
+function checkUatOwnHomeWriteTargets(writeTargets, env = process.env, identity = currentIdentity()) {
+    const dedicated = env[exports.UAT_DEDICATED_USER_ENV_VAR];
+    if (!dedicated)
+        return `${exports.UAT_DEDICATED_USER_ENV_VAR} is not set`;
+    if (identity.username !== dedicated) {
+        return `this process runs as ${identity.username}, not as the dedicated user ${dedicated}`;
+    }
+    const home = env.HOME;
+    if (!home || !path_1.default.isAbsolute(home))
+        return 'HOME is not set to an absolute path';
+    let homeReal;
+    let accountHomeReal;
+    try {
+        homeReal = fs_1.default.realpathSync(home);
+        accountHomeReal = fs_1.default.realpathSync(identity.homedir);
+    }
+    catch {
+        return `HOME (${home}) or ${dedicated}'s home directory (${identity.homedir}) does not exist`;
+    }
+    if (homeReal !== accountHomeReal) {
+        return `HOME (${home}) is not ${dedicated}'s home directory (${identity.homedir})`;
+    }
+    if (fs_1.default.statSync(homeReal).uid !== identity.uid)
+        return `HOME (${home}) is not owned by ${dedicated}`;
+    for (const target of writeTargets) {
+        const resolved = resolveWriteTarget(target);
+        if (typeof resolved === 'string')
+            return resolved;
+        if (resolved.real !== homeReal && !resolved.real.startsWith(`${homeReal}${path_1.default.sep}`)) {
+            return `${target} resolves to ${resolved.real}, outside ${dedicated}'s HOME (${homeReal})`;
+        }
+        if (resolved.owner !== identity.uid) {
+            return `${target} (${resolved.real}) is not owned by ${dedicated}`;
+        }
+    }
+    return null;
+}
+/**
+ * Under `own-home`, refuse the launch of `tool` unless
+ * {@link checkUatOwnHomeWriteTargets} passes for `writeTargets`. A no-op in
+ * every other mode.
+ *
+ * @throws {UatIsolationLaunchRefusedError}
+ */
+function assertUatOwnHomeWriteTargets(tool, writeTargets, env = process.env) {
+    if (getUatIsolationMode(env) !== 'own-home')
+        return;
+    const problem = checkUatOwnHomeWriteTargets(writeTargets, env);
+    if (problem)
+        throw new UatIsolationLaunchRefusedError(tool, problem, exports.UAT_OWN_HOME_FIX);
+}
+/**
+ * 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
+ */
+function sharedHookWritePolicy(tool, writeTargets, env = process.env) {
+    const mode = getUatIsolationMode(env);
+    if (mode === 'shared-read-only')
+        return 'read-only';
+    assertUatOwnHomeWriteTargets(tool, writeTargets, env);
+    return 'write';
+}

package/dist/lib/global-state.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Process-wide state helper for the `globalThis.__*` cache pattern.
+ *
+ * Returns the value already stored on `globalThis[key]`, or runs `init` once and
+ * stores its result. `init` runs only when the slot is `null`/`undefined`, at the
+ * moment this function is called (so callers keep their own init timing).
+ *
+ * `key` and the initial value are typed from each file's `declare global`
+ * declaration. This module imports nothing so any layer (server, CLI) can use it.
+ */
+export declare function getOrInitGlobal<K extends keyof typeof globalThis>(key: K, init: () => NonNullable<(typeof globalThis)[K]>): NonNullable<(typeof globalThis)[K]>;
+//# sourceMappingURL=global-state.d.ts.map

package/dist/lib/global-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-state.d.ts","sourceRoot":"","sources":["../../src/lib/global-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,OAAO,UAAU,EAC/D,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,WAAW,CAAC,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,WAAW,CAAC,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAErC"}