commandmate 0.26.0 → 0.27.0

package/dist/lib/security/env-sanitizer.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Environment Variable Sanitizer
+ * Issue #294: Sanitizes environment variables for child processes
+ *
+ * Removes sensitive environment variables (auth tokens, certificates, database paths)
+ * before spawning child processes like `claude -p`.
+ *
+ * [S1-001/S4-001] Centralized sensitive key management
+ *
+ * ## What this file defends — the one sentence (Issue #1996)
+ *
+ * **A CommandMate process must hand its children neither a credential nor the
+ * identity of the agent that started it.**
+ *
+ * Two halves, and they fail differently:
+ *
+ *  - **Credentials** — {@link SENSITIVE_ENV_KEYS}. A child that can read them
+ *    can act as this server, or read its database.
+ *  - **The launching agent's identity** — {@link AGENT_CORRELATION_ENV_KEYS}:
+ *    every variable `AgentLaunchPlan.env` writes onto an agent's launch line
+ *    that says *which server to report to* and *as which instance*. A child
+ *    that inherits them reports somebody else's work as that instance's.
+ *
+ * A per-tool config redirect (`CODEX_HOME`) is on the launch line too and is
+ * deliberately **not** stripped: it says where a tool reads its own settings,
+ * which is neither a credential nor an identity, and a child that inherits one
+ * is unaffected.
+ *
+ * ## Issue #1942 — why a *prefix* joined the list
+ *
+ * 設計方針書 §13.2 S8 asks for two halves. #1904 landed the first: the values a
+ * hook needs are handed to the agent on its launch line (`CM_HOOK_PORT=3011
+ * copilot`) instead of being baked into a machine-global settings file. This is
+ * the second: those variables must not travel any further than the agent.
+ *
+ * The leak this closes is not the agent's own children — CommandMate does not
+ * own that environment — it is **CommandMate's**. A server started from inside
+ * a pane CommandMate itself launched inherits that pane's launch line, and
+ * every child *this* process then spawns (`claude -p` for Assistant Chat, the
+ * slash-command probes, `copilot --version`) inherits it in turn. The values
+ * are a correlation key and a port: a relay firing from one of those children
+ * posts its events to another server, attributed to an instance that is not the
+ * one running. Nothing errors; the events simply land on the wrong session.
+ *
+ * ## Issue #1996 — why the prefix could not be the whole rule
+ *
+ * #1942 chose `CM_HOOK_*` because a namespace is stronger than a list: the next
+ * variable in it is stripped whether or not its author reads this file. That
+ * reasoning is still right, and the prefix stays. What was wrong was the
+ * premise that the namespace *covers the launch line*. Building all seven
+ * sources' `prepareLaunch` and reading `env` back — the measurement is pinned in
+ * `tests/unit/lib/agent-launch-plan-secrets-1933.test.ts` — finds six identity
+ * variables, and two of them start with `CM_HOOK_`.
+ *
+ * The other four produce the same failure #1942 named, by two measured routes:
+ *
+ *  - `scripts/hooks/cmate-agent-event.sh` reads `CM_AGENT_TOOL` from the
+ *    environment (`TOOL="${CM_AGENT_TOOL:-claude}"`) and, with no `CM_HOOK_URL`,
+ *    falls back to `http://127.0.0.1:${CM_PORT:-3000}/api/hooks/agent-event`.
+ *    Stripping only the `CM_HOOK_` half therefore makes the destination *valid
+ *    again* — usually the live server — while the attribution stays wrong. The
+ *    event lands, on the wrong tool.
+ *  - The generated antigravity `PreToolUse` command gates on
+ *    `[ -z "${CM_PERMISSION_HOOK_URL:-}" ]`, which is its whole test for "am I a
+ *    CommandMate-launched session". `~/.gemini/config/hooks.json` is a
+ *    machine-global singleton, so an inherited `CM_PERMISSION_HOOK_URL` makes
+ *    any agy started under one of CommandMate's children ask *another
+ *    instance's* server for permission, and obey the answer.
+ *
+ * ### Why the prefix was not simply widened to `CM_AGENT_`
+ *
+ * Because `CM_AGENT_` is not CommandMate's own namespace, and the sentence that
+ * justifies the `CM_HOOK_` prefix — "there is no operator value here to
+ * preserve" — is false for it. `CM_AGENT_HOOKS_INJECT` and `CM_AGENT_HOOKS_DIR`
+ * are **operator switches read from the ambient environment**
+ * (`hooks/sources/copilot/hook-settings.ts`, `hooks/hook-settings-generator.ts`);
+ * stripping them would silently change a child's configuration. #1942's own test
+ * already pinned that shape. And `CM_PERMISSION_HOOK_URL` shares no prefix with
+ * anything, so no namespace rule could have covered the set in any case.
+ *
+ * Renaming the four into `CM_HOOK_*` so the prefix *would* suffice was
+ * considered and rejected: `CM_AGENT_TOOL` is documented in the shipped relay's
+ * own `--help` and depended on by the hand-configured hooks of #1549, and
+ * `~/.copilot/settings.json` / `~/.gemini/config/hooks.json` are machine-global
+ * files already on disk carrying the old names — every already-configured
+ * session would stop correlating until rewritten.
+ *
+ * So the rule is a **union**: the credential list, the enumerated identity set,
+ * and the `CM_HOOK_` prefix that still covers whatever is invented inside it.
+ *
+ * ## The join with `lib/hooks`, and what replaces the prefix as a drift guard
+ *
+ * `lib/security` does not import `lib/hooks` — the dependency already runs the
+ * other way (`hooks/agent-event-service`, `hooks/sources/copilot/hook-settings`
+ * and `hooks/sources/codex/hooks-config` all import
+ * `lib/security/path-validator`), and inverting it would put a package cycle
+ * underneath four child-process spawners. `tests/unit/guards/security-no-hooks-import.test.ts`
+ * holds that.
+ *
+ * The enumeration below is therefore a second copy of a list `lib/hooks` also
+ * declares, and two tests are the join:
+ *
+ *  1. `tests/unit/lib/agent-launch-plan-secrets-1933.test.ts` builds all seven
+ *     `prepareLaunch` plans and asserts their env keys are **exactly**
+ *     `AGENT_CORRELATION_ENV_VARS` plus `AGENT_LAUNCH_CONFIG_ENV_VARS`. A source
+ *     that starts writing a new variable — in any namespace — goes red there, by
+ *     name.
+ *  2. `tests/unit/security/child-process-agent-env-1996.test.ts` takes that
+ *     declared list and proves, with a real child process, that none of it is
+ *     readable. Deleting a name from {@link AGENT_CORRELATION_ENV_KEYS} does not
+ *     shrink what that test iterates, so the deletion is what goes red.
+ *
+ * Together those two are stronger than the prefix was, because the prefix never
+ * covered a name outside its own namespace at all.
+ */
+/**
+ * List of environment variable keys that must be removed before
+ * passing environment to child processes.
+ *
+ * These include authentication tokens, TLS certificates, IP restriction
+ * settings, and database paths that should not be inherited by spawned
+ * CLI tool processes.
+ *
+ * `CM_AUTH_TOKEN` — the **plaintext** bearer token — joined in Issue #1996. Only
+ * the `_HASH` form was listed, and the plaintext one is what a request is
+ * actually authenticated with: measured with a real child, `claude -p` and the
+ * version probes could read it back. It is expected in a server's environment
+ * (the CLI's own `--token` warning tells operators to prefer the variable, and
+ * §10.7 of the 設計方針書 has the agent's hooks read it "from process
+ * inheritance"), and `lib/slash-command-catalog`'s docblock already claimed a
+ * probe "never hands CommandMate's auth token … to a third-party CLI".
+ *
+ * Nothing that spawns with {@link sanitizeEnvForChildProcess} needs it: none of
+ * the five call sites configures hooks for its child. The **agent's** pane is
+ * unaffected — tmux inherits the server's environment directly and never goes
+ * through this function — so `$CM_AUTH_TOKEN` still expands in a hook.
+ */
+export declare const SENSITIVE_ENV_KEYS: readonly ["CLAUDECODE", "CM_AUTH_TOKEN", "CM_AUTH_TOKEN_HASH", "CM_AUTH_EXPIRE", "CM_HTTPS_KEY", "CM_HTTPS_CERT", "CM_ALLOWED_IPS", "CM_TRUST_PROXY", "CM_DB_PATH", "GH_DEBUG"];
+/**
+ * The namespace CommandMate writes onto an agent's launch line (Issue #1942).
+ *
+ * Kept alongside {@link AGENT_CORRELATION_ENV_KEYS} rather than replaced by it.
+ * Inside this namespace the prefix is still the stronger rule — a `CM_HOOK_*`
+ * variable invented next year is stripped whether or not anyone remembers this
+ * file exists, and `CM_HOOK_` is CommandMate's own namespace, so there is no
+ * operator value here to preserve. What #1996 measured is that the namespace is
+ * two of the launch line's six identity variables, not all of them; see the
+ * module comment.
+ */
+export declare const COMMANDMATE_HOOK_ENV_PREFIX = "CM_HOOK_";
+/**
+ * Every variable an agent's launch line uses to say **which server to report to
+ * and as which instance** (Issue #1996).
+ *
+ * The measured contents of `AgentLaunchPlan.env` across all seven sources, minus
+ * the per-tool config redirects. `lib/hooks/sources/launch-command` declares the
+ * same set as `AGENT_CORRELATION_ENV_VARS`; this is the second copy, and the two
+ * tests named in the module comment are the join. Sorted, so a diff against the
+ * measured set reads cleanly.
+ *
+ * Two of them are inside {@link COMMANDMATE_HOOK_ENV_PREFIX} and would be
+ * stripped anyway. They are listed regardless: this array is the statement of
+ * *what the rule is about*, and a reader who has to subtract a prefix to see the
+ * set is a reader who will get it wrong again.
+ */
+export declare const AGENT_CORRELATION_ENV_KEYS: readonly ["CM_AGENT_INSTANCE_ID", "CM_AGENT_TOOL", "CM_AGENT_WORKTREE_ID", "CM_HOOK_PORT", "CM_HOOK_URL", "CM_PERMISSION_HOOK_URL"];
+/**
+ * Whether `key` is removed from a child process's environment.
+ *
+ * @param key - An environment variable name
+ * @returns `true` for a listed secret, a launch-line identity variable, or
+ *   anything in CommandMate's hook namespace
+ */
+export declare function isStrippedChildProcessEnvKey(key: string): boolean;
+/**
+ * Create a sanitized copy of process.env suitable for child processes.
+ *
+ * Removes every key {@link isStrippedChildProcessEnvKey} claims: the listed
+ * secrets (Issue #294/#545/#1996), the launch-line identity of the agent this
+ * process was started under (Issue #1996), and CommandMate's own `CM_HOOK_*`
+ * namespace (Issue #1942). Non-sensitive variables (PATH, HOME, NODE_ENV, etc.)
+ * are preserved, including the operator's own `CM_AGENT_HOOKS_*` switches.
+ *
+ * @returns A shallow copy of process.env with sensitive keys removed
+ *
+ * @example
+ * ```typescript
+ * import { execFile } from 'child_process';
+ * import { sanitizeEnvForChildProcess } from './env-sanitizer';
+ *
+ * execFile('claude', ['-p', message], {
+ *   env: sanitizeEnvForChildProcess(),
+ *   cwd: worktreePath,
+ * });
+ * ```
+ */
+export declare function sanitizeEnvForChildProcess(): NodeJS.ProcessEnv;
+//# sourceMappingURL=env-sanitizer.d.ts.map

package/dist/lib/security/env-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/lib/security/env-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,iLAWrB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,aAAa,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,qIAO7B,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAAC,UAAU,CAQ9D"}

package/dist/lib/security/env-sanitizer.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Environment Variable Sanitizer
+ * Issue #294: Sanitizes environment variables for child processes
+ *
+ * Removes sensitive environment variables (auth tokens, certificates, database paths)
+ * before spawning child processes like `claude -p`.
+ *
+ * [S1-001/S4-001] Centralized sensitive key management
+ *
+ * ## What this file defends — the one sentence (Issue #1996)
+ *
+ * **A CommandMate process must hand its children neither a credential nor the
+ * identity of the agent that started it.**
+ *
+ * Two halves, and they fail differently:
+ *
+ *  - **Credentials** — {@link SENSITIVE_ENV_KEYS}. A child that can read them
+ *    can act as this server, or read its database.
+ *  - **The launching agent's identity** — {@link AGENT_CORRELATION_ENV_KEYS}:
+ *    every variable `AgentLaunchPlan.env` writes onto an agent's launch line
+ *    that says *which server to report to* and *as which instance*. A child
+ *    that inherits them reports somebody else's work as that instance's.
+ *
+ * A per-tool config redirect (`CODEX_HOME`) is on the launch line too and is
+ * deliberately **not** stripped: it says where a tool reads its own settings,
+ * which is neither a credential nor an identity, and a child that inherits one
+ * is unaffected.
+ *
+ * ## Issue #1942 — why a *prefix* joined the list
+ *
+ * 設計方針書 §13.2 S8 asks for two halves. #1904 landed the first: the values a
+ * hook needs are handed to the agent on its launch line (`CM_HOOK_PORT=3011
+ * copilot`) instead of being baked into a machine-global settings file. This is
+ * the second: those variables must not travel any further than the agent.
+ *
+ * The leak this closes is not the agent's own children — CommandMate does not
+ * own that environment — it is **CommandMate's**. A server started from inside
+ * a pane CommandMate itself launched inherits that pane's launch line, and
+ * every child *this* process then spawns (`claude -p` for Assistant Chat, the
+ * slash-command probes, `copilot --version`) inherits it in turn. The values
+ * are a correlation key and a port: a relay firing from one of those children
+ * posts its events to another server, attributed to an instance that is not the
+ * one running. Nothing errors; the events simply land on the wrong session.
+ *
+ * ## Issue #1996 — why the prefix could not be the whole rule
+ *
+ * #1942 chose `CM_HOOK_*` because a namespace is stronger than a list: the next
+ * variable in it is stripped whether or not its author reads this file. That
+ * reasoning is still right, and the prefix stays. What was wrong was the
+ * premise that the namespace *covers the launch line*. Building all seven
+ * sources' `prepareLaunch` and reading `env` back — the measurement is pinned in
+ * `tests/unit/lib/agent-launch-plan-secrets-1933.test.ts` — finds six identity
+ * variables, and two of them start with `CM_HOOK_`.
+ *
+ * The other four produce the same failure #1942 named, by two measured routes:
+ *
+ *  - `scripts/hooks/cmate-agent-event.sh` reads `CM_AGENT_TOOL` from the
+ *    environment (`TOOL="${CM_AGENT_TOOL:-claude}"`) and, with no `CM_HOOK_URL`,
+ *    falls back to `http://127.0.0.1:${CM_PORT:-3000}/api/hooks/agent-event`.
+ *    Stripping only the `CM_HOOK_` half therefore makes the destination *valid
+ *    again* — usually the live server — while the attribution stays wrong. The
+ *    event lands, on the wrong tool.
+ *  - The generated antigravity `PreToolUse` command gates on
+ *    `[ -z "${CM_PERMISSION_HOOK_URL:-}" ]`, which is its whole test for "am I a
+ *    CommandMate-launched session". `~/.gemini/config/hooks.json` is a
+ *    machine-global singleton, so an inherited `CM_PERMISSION_HOOK_URL` makes
+ *    any agy started under one of CommandMate's children ask *another
+ *    instance's* server for permission, and obey the answer.
+ *
+ * ### Why the prefix was not simply widened to `CM_AGENT_`
+ *
+ * Because `CM_AGENT_` is not CommandMate's own namespace, and the sentence that
+ * justifies the `CM_HOOK_` prefix — "there is no operator value here to
+ * preserve" — is false for it. `CM_AGENT_HOOKS_INJECT` and `CM_AGENT_HOOKS_DIR`
+ * are **operator switches read from the ambient environment**
+ * (`hooks/sources/copilot/hook-settings.ts`, `hooks/hook-settings-generator.ts`);
+ * stripping them would silently change a child's configuration. #1942's own test
+ * already pinned that shape. And `CM_PERMISSION_HOOK_URL` shares no prefix with
+ * anything, so no namespace rule could have covered the set in any case.
+ *
+ * Renaming the four into `CM_HOOK_*` so the prefix *would* suffice was
+ * considered and rejected: `CM_AGENT_TOOL` is documented in the shipped relay's
+ * own `--help` and depended on by the hand-configured hooks of #1549, and
+ * `~/.copilot/settings.json` / `~/.gemini/config/hooks.json` are machine-global
+ * files already on disk carrying the old names — every already-configured
+ * session would stop correlating until rewritten.
+ *
+ * So the rule is a **union**: the credential list, the enumerated identity set,
+ * and the `CM_HOOK_` prefix that still covers whatever is invented inside it.
+ *
+ * ## The join with `lib/hooks`, and what replaces the prefix as a drift guard
+ *
+ * `lib/security` does not import `lib/hooks` — the dependency already runs the
+ * other way (`hooks/agent-event-service`, `hooks/sources/copilot/hook-settings`
+ * and `hooks/sources/codex/hooks-config` all import
+ * `lib/security/path-validator`), and inverting it would put a package cycle
+ * underneath four child-process spawners. `tests/unit/guards/security-no-hooks-import.test.ts`
+ * holds that.
+ *
+ * The enumeration below is therefore a second copy of a list `lib/hooks` also
+ * declares, and two tests are the join:
+ *
+ *  1. `tests/unit/lib/agent-launch-plan-secrets-1933.test.ts` builds all seven
+ *     `prepareLaunch` plans and asserts their env keys are **exactly**
+ *     `AGENT_CORRELATION_ENV_VARS` plus `AGENT_LAUNCH_CONFIG_ENV_VARS`. A source
+ *     that starts writing a new variable — in any namespace — goes red there, by
+ *     name.
+ *  2. `tests/unit/security/child-process-agent-env-1996.test.ts` takes that
+ *     declared list and proves, with a real child process, that none of it is
+ *     readable. Deleting a name from {@link AGENT_CORRELATION_ENV_KEYS} does not
+ *     shrink what that test iterates, so the deletion is what goes red.
+ *
+ * Together those two are stronger than the prefix was, because the prefix never
+ * covered a name outside its own namespace at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_CORRELATION_ENV_KEYS = exports.COMMANDMATE_HOOK_ENV_PREFIX = exports.SENSITIVE_ENV_KEYS = void 0;
+exports.isStrippedChildProcessEnvKey = isStrippedChildProcessEnvKey;
+exports.sanitizeEnvForChildProcess = sanitizeEnvForChildProcess;
+/**
+ * List of environment variable keys that must be removed before
+ * passing environment to child processes.
+ *
+ * These include authentication tokens, TLS certificates, IP restriction
+ * settings, and database paths that should not be inherited by spawned
+ * CLI tool processes.
+ *
+ * `CM_AUTH_TOKEN` — the **plaintext** bearer token — joined in Issue #1996. Only
+ * the `_HASH` form was listed, and the plaintext one is what a request is
+ * actually authenticated with: measured with a real child, `claude -p` and the
+ * version probes could read it back. It is expected in a server's environment
+ * (the CLI's own `--token` warning tells operators to prefer the variable, and
+ * §10.7 of the 設計方針書 has the agent's hooks read it "from process
+ * inheritance"), and `lib/slash-command-catalog`'s docblock already claimed a
+ * probe "never hands CommandMate's auth token … to a third-party CLI".
+ *
+ * Nothing that spawns with {@link sanitizeEnvForChildProcess} needs it: none of
+ * the five call sites configures hooks for its child. The **agent's** pane is
+ * unaffected — tmux inherits the server's environment directly and never goes
+ * through this function — so `$CM_AUTH_TOKEN` still expands in a hook.
+ */
+exports.SENSITIVE_ENV_KEYS = [
+    'CLAUDECODE',
+    'CM_AUTH_TOKEN', // Issue #1996: plaintext bearer token, not just its hash
+    'CM_AUTH_TOKEN_HASH',
+    'CM_AUTH_EXPIRE',
+    'CM_HTTPS_KEY',
+    'CM_HTTPS_CERT',
+    'CM_ALLOWED_IPS',
+    'CM_TRUST_PROXY',
+    'CM_DB_PATH',
+    'GH_DEBUG', // Issue #545: Prevent gh debug output in child processes [SEC4-003]
+];
+/**
+ * The namespace CommandMate writes onto an agent's launch line (Issue #1942).
+ *
+ * Kept alongside {@link AGENT_CORRELATION_ENV_KEYS} rather than replaced by it.
+ * Inside this namespace the prefix is still the stronger rule — a `CM_HOOK_*`
+ * variable invented next year is stripped whether or not anyone remembers this
+ * file exists, and `CM_HOOK_` is CommandMate's own namespace, so there is no
+ * operator value here to preserve. What #1996 measured is that the namespace is
+ * two of the launch line's six identity variables, not all of them; see the
+ * module comment.
+ */
+exports.COMMANDMATE_HOOK_ENV_PREFIX = 'CM_HOOK_';
+/**
+ * Every variable an agent's launch line uses to say **which server to report to
+ * and as which instance** (Issue #1996).
+ *
+ * The measured contents of `AgentLaunchPlan.env` across all seven sources, minus
+ * the per-tool config redirects. `lib/hooks/sources/launch-command` declares the
+ * same set as `AGENT_CORRELATION_ENV_VARS`; this is the second copy, and the two
+ * tests named in the module comment are the join. Sorted, so a diff against the
+ * measured set reads cleanly.
+ *
+ * Two of them are inside {@link COMMANDMATE_HOOK_ENV_PREFIX} and would be
+ * stripped anyway. They are listed regardless: this array is the statement of
+ * *what the rule is about*, and a reader who has to subtract a prefix to see the
+ * set is a reader who will get it wrong again.
+ */
+exports.AGENT_CORRELATION_ENV_KEYS = [
+    'CM_AGENT_INSTANCE_ID',
+    'CM_AGENT_TOOL',
+    'CM_AGENT_WORKTREE_ID',
+    'CM_HOOK_PORT',
+    'CM_HOOK_URL',
+    'CM_PERMISSION_HOOK_URL',
+];
+/**
+ * Whether `key` is removed from a child process's environment.
+ *
+ * @param key - An environment variable name
+ * @returns `true` for a listed secret, a launch-line identity variable, or
+ *   anything in CommandMate's hook namespace
+ */
+function isStrippedChildProcessEnvKey(key) {
+    return (exports.SENSITIVE_ENV_KEYS.includes(key) ||
+        exports.AGENT_CORRELATION_ENV_KEYS.includes(key) ||
+        key.startsWith(exports.COMMANDMATE_HOOK_ENV_PREFIX));
+}
+/**
+ * Create a sanitized copy of process.env suitable for child processes.
+ *
+ * Removes every key {@link isStrippedChildProcessEnvKey} claims: the listed
+ * secrets (Issue #294/#545/#1996), the launch-line identity of the agent this
+ * process was started under (Issue #1996), and CommandMate's own `CM_HOOK_*`
+ * namespace (Issue #1942). Non-sensitive variables (PATH, HOME, NODE_ENV, etc.)
+ * are preserved, including the operator's own `CM_AGENT_HOOKS_*` switches.
+ *
+ * @returns A shallow copy of process.env with sensitive keys removed
+ *
+ * @example
+ * ```typescript
+ * import { execFile } from 'child_process';
+ * import { sanitizeEnvForChildProcess } from './env-sanitizer';
+ *
+ * execFile('claude', ['-p', message], {
+ *   env: sanitizeEnvForChildProcess(),
+ *   cwd: worktreePath,
+ * });
+ * ```
+ */
+function sanitizeEnvForChildProcess() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (isStrippedChildProcessEnvKey(key)) {
+            delete env[key];
+        }
+    }
+    return env;
+}

package/dist/server/locales/en/notifications.json

@@ -1,16 +1,16 @@
 {
     "title": "Notifications",
-    "description": "Get a push notification when an agent is waiting for you or finishes a session — even when the app is closed.",
+    "description": "Get a push notification when something needs you — a prompt, a failed verification, an upstream API fault, or a session that could not start — even when the app is closed. Completions are optional.",
     "enable": "Enable notifications",
     "enabling": "Enabling…",
     "enabledOnThisDevice": "Notifications are enabled on this device.",
     "unsubscribe": "Unsubscribe this device",
     "types": {
         "heading": "Notify me about",
-        "promptWaiting": "Prompt waiting",
-        "promptWaitingDesc": "When an agent is waiting for your reply",
-        "completion": "Session complete",
-        "completionDesc": "When an agent finishes a session"
+        "promptWaiting": "When you need to act",
+        "promptWaitingDesc": "A prompt waiting for you, a failed verification gate, an upstream API fault, or a session that could not start. Nothing moves until you do",
+        "completion": "Also tell me about completions (optional)",
+        "completionDesc": "Ordinary completions that need nothing from you. Off by default on newly registered devices (change it for this device here)"
     },
     "permission": {
         "denied": "Notifications are blocked in your browser settings. Allow them for this site to receive push notifications."
@@ -34,7 +34,18 @@
         "terminalAttentionWithExcerpt": "Needs attention in the terminal: {excerpt}",
         "terminalAttention": "Needs attention in the terminal",
         "stillWaitingPrompt": "Still waiting for your reply ({minutes} min)",
-        "stillWaitingTerminal": "Still needs attention in the terminal ({minutes} min)"
+        "stillWaitingTerminal": "Still needs attention in the terminal ({minutes} min)",
+        "failureVerificationWithExcerpt": "Verification failed: {excerpt}",
+        "failureVerification": "Verification failed",
+        "failureUpstreamWithExcerpt": "Stalled by an upstream API fault: {excerpt}",
+        "failureUpstream": "Stalled by an upstream API fault",
+        "failureSessionStartWithExcerpt": "Could not start the session: {excerpt}",
+        "failureSessionStart": "Could not start the session",
+        "failureSessionUnavailableWithExcerpt": "Could not start the session: {excerpt} is not installed",
+        "failureSessionUnavailable": "Could not start the session: the CLI tool is not installed",
+        "failureWithExcerpt": "Failed: {excerpt}",
+        "failure": "Failed",
+        "promptResolved": "Handled — answered on another device"
     },
     "escalation": {
         "heading": "Reminder",

package/dist/server/locales/ja/notifications.json

@@ -1,16 +1,16 @@
 {
     "title": "通知",
-    "description": "エージェントが応答待ちになったり、セッションが完了したときに、アプリを開いていなくてもプッシュ通知を受け取れます。",
+    "description": "対応が必要になったとき（応答待ち・検証の不合格・上流APIの障害・セッションの起動失敗）に、アプリを開いていなくてもプッシュ通知を受け取れます。対応の要らない完了通知は任意です。",
     "enable": "通知を有効にする",
     "enabling": "有効化中…",
     "enabledOnThisDevice": "この端末で通知が有効です。",
     "unsubscribe": "この端末の通知を解除",
     "types": {
         "heading": "通知する種別",
-        "promptWaiting": "応答待ち",
-        "promptWaitingDesc": "エージェントがあなたの応答を待っているとき",
-        "completion": "セッション完了",
-        "completionDesc": "エージェントがセッションを完了したとき"
+        "promptWaiting": "対応が必要なとき",
+        "promptWaitingDesc": "応答待ち・検証ゲートの不合格・上流APIの障害・セッションの起動失敗。あなたが動かないと進みません",
+        "completion": "完了も知らせる（任意）",
+        "completionDesc": "対応の要らない正常完了。新しく登録した端末では既定でオフです（この端末の設定はここで変えられます）"
     },
     "permission": {
         "denied": "ブラウザの設定で通知がブロックされています。このサイトの通知を許可してください。"
@@ -34,7 +34,18 @@
         "terminalAttentionWithExcerpt": "端末の確認が必要です: {excerpt}",
         "terminalAttention": "端末の確認が必要です",
         "stillWaitingPrompt": "まだ応答待ちです（{minutes}分経過）",
-        "stillWaitingTerminal": "まだ端末の確認が必要です（{minutes}分経過）"
+        "stillWaitingTerminal": "まだ端末の確認が必要です（{minutes}分経過）",
+        "failureVerificationWithExcerpt": "検証ゲート不合格: {excerpt}",
+        "failureVerification": "検証ゲートに不合格しました",
+        "failureUpstreamWithExcerpt": "上流APIの障害で停止しています: {excerpt}",
+        "failureUpstream": "上流APIの障害で停止しています",
+        "failureSessionStartWithExcerpt": "セッションを起動できませんでした: {excerpt}",
+        "failureSessionStart": "セッションを起動できませんでした",
+        "failureSessionUnavailableWithExcerpt": "セッションを起動できませんでした: {excerpt} がインストールされていません",
+        "failureSessionUnavailable": "セッションを起動できませんでした: CLI ツールがインストールされていません",
+        "failureWithExcerpt": "失敗しました: {excerpt}",
+        "failure": "失敗しました",
+        "promptResolved": "対応済みです（他の端末で応答されました）"
     },
     "escalation": {
         "heading": "再通知",

package/dist/server/src/config/activity-bar-config.js

@@ -37,6 +37,10 @@ exports.ACTIVITIES = [
     // rather than inserted so the existing ArrowUp/ArrowDown order — which users
     // and tests both index by position — is unchanged.
     { id: 'verification', labelKey: 'activityBar.verification', icon: lucide_react_1.ShieldCheck },
+    // Issue #1968: the masked `.env` editor. Appended for the same reason
+    // `verification` was — the ArrowUp/ArrowDown order is indexed by position by
+    // both users and tests, so an insert would silently renumber every tab.
+    { id: 'env', labelKey: 'activityBar.env', icon: lucide_react_1.KeyRound },
 ];
 /**
  * Set of valid ActivityId values for runtime validation.

package/dist/server/src/config/cli-tool-timing-config.js

@@ -20,7 +20,7 @@
  * All values are preserved from the original literals (no behavior change).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAUDE_RESTART_DELAY_MS = exports.CLAUDE_ENV_SANITIZE_WAIT_MS = exports.VIBE_LOCAL_DOUBLE_ENTER_WAIT_MS = exports.OPENCODE_EXIT_WAIT_MS = exports.CODEX_DIALOG_SETTLE_MS = exports.TUI_EXIT_WAIT_MS = exports.TUI_INTERRUPT_SETTLE_MS = exports.TUI_MESSAGE_PROCESSED_WAIT_MS = exports.TUI_TEXT_INPUT_WAIT_MS = exports.TUI_SESSION_CREATE_WAIT_MS = void 0;
+exports.CLAUDE_RESTART_DELAY_MS = exports.CLAUDE_ENV_SANITIZE_WAIT_MS = exports.VIBE_LOCAL_DOUBLE_ENTER_WAIT_MS = exports.COPILOT_EXIT_WAIT_MS = exports.OPENCODE_INTERRUPT_SECOND_ESCAPE_DELAY_MS = exports.OPENCODE_EXIT_WAIT_MS = exports.CODEX_DIALOG_SETTLE_MS = exports.TUI_EXIT_WAIT_MS = exports.TUI_INTERRUPT_SETTLE_MS = exports.TUI_MESSAGE_PROCESSED_WAIT_MS = exports.TUI_TEXT_INPUT_WAIT_MS = exports.TUI_SESSION_CREATE_WAIT_MS = void 0;
 /**
  * Wait (ms) after `createSession()` before sending the first keys, giving tmux
  * time to spin up the session.
@@ -48,8 +48,9 @@ exports.TUI_INTERRUPT_SETTLE_MS = 300;
 /**
  * Wait (ms) after an exit/quit command (or Ctrl+D) for the CLI to shut down
  * gracefully before the tmux session is killed.
- * Sites: codex / gemini / vibe-local / copilot killSession(),
+ * Sites: codex / gemini / vibe-local killSession(),
  * session-key-sender stopSession().
+ * (copilot moved to {@link COPILOT_EXIT_WAIT_MS} in Issue #1905.)
  */
 exports.TUI_EXIT_WAIT_MS = 500;
 /**
@@ -62,8 +63,64 @@ exports.CODEX_DIALOG_SETTLE_MS = 500;
  * Wait (ms) for OpenCode to process its `/exit` TUI command. Longer than the
  * generic exit wait because OpenCode's TUI teardown is slower.
  * Site: opencode killSession().
+ *
+ * Issue #1905 measured the teardown on opencode 1.18.21 (private tmux socket,
+ * 200x50): once `/exit` is submitted as body-then-Enter the TUI is gone in
+ * 0.445 / 0.456 / 0.458 s (n=3), so this window is not the binding constraint.
+ * It was left at 2000 rather than tightened because the measurement is for an
+ * unloaded machine.
  */
 exports.OPENCODE_EXIT_WAIT_MS = 2000;
+/**
+ * Wait (ms) between the two Escape presses that abort an opencode turn.
+ *
+ * opencode 1.18 does not interrupt on a single Escape. The first press re-labels
+ * the footer `esc interrupt` -> `esc again to interrupt` and abandons nothing;
+ * only a SECOND Escape inside that label's lifetime aborts the turn.
+ *
+ * Issue #1894 measured the label on opencode 1.18.21 (private tmux socket,
+ * 80x200): sampling the footer every ~360 ms after one Escape, `esc again to
+ * interrupt` is up from 0.31 s through 4.71 s and the row has reverted to `esc
+ * interrupt` by 5.07 s. So the deadline is five seconds, and a single Escape
+ * really does nothing -- the generation continued to a natural
+ * `Build ... 11.3s` completion in 3 runs out of 3.
+ *
+ * 300 ms is the design policy's number
+ * (`docs/design/multi-agent-state-architecture.md` §6.3) and it is kept, because
+ * both directions of error are bounded by real measurements rather than by
+ * taste:
+ *
+ * - too LATE is the dangerous side (the turn is not aborted and the pane just
+ *   collects Escapes). Driving the real `OpenCodeTool.interrupt()` against a
+ *   live 1.18.21 session, the whole call -- `send-keys`, this wait, `send-keys`
+ *   -- took 317 ms end to end, i.e. the two tmux executions cost ~17 ms and the
+ *   press lands at 6% of the deadline. Even the crude shell harness used for
+ *   the first probe, which pays a python interpreter per step, landed its
+ *   second press at 594 ms: 8x inside the window.
+ * - too EARLY would risk the second press being swallowed before opencode has
+ *   armed the label. The label was already up at the first sample after the
+ *   first press (0.31 s), and both the 317 ms and the 594 ms double-press
+ *   aborted the turn (`▣  Build · GPT-5.6 Luna · interrupted` mid-sentence), so
+ *   the arming cost is well under one wait.
+ *
+ * Site: opencode interrupt().
+ */
+exports.OPENCODE_INTERRUPT_SECOND_ESCAPE_DELAY_MS = 300;
+/**
+ * Wait (ms) for Copilot to process its `/exit` TUI command before the tmux
+ * session is killed. Copilot-specific because {@link TUI_EXIT_WAIT_MS} (500) is
+ * shorter than the shutdown actually takes.
+ * Site: copilot killSession().
+ *
+ * Issue #1905 measured GitHub Copilot CLI 1.0.80 in a private tmux socket
+ * (200x50, unloaded). Time from the submitting keystroke to the pane's process
+ * no longer being `copilot`, across every exit spelling copilot accepts:
+ * 1.006 / 1.109 / 1.115 / 1.118 / 1.204 / 1.208 / 1.288 / 1.330 / 1.795 /
+ * 2.165 / 2.193 s. Every sample is past 500 ms, i.e. the generic constant
+ * guaranteed the tmux kill landed mid-shutdown; 3000 covers the slowest sample
+ * with room for a loaded machine.
+ */
+exports.COPILOT_EXIT_WAIT_MS = 3000;
 /**
  * Wait (ms) between the two Enter key presses in vibe-local's IME submit mode
  * (first Enter inserts a newline, second Enter submits).

package/dist/server/src/config/copilot-constants.js

@@ -9,7 +9,7 @@
  * - src/lib/cli-tools/copilot.ts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_MODEL_NAME_LENGTH = exports.MODEL_NAME_PATTERN = exports.COPILOT_MODEL_SWITCH_TIMEOUT_MS = exports.COPILOT_TRUNCATION_MARKER = exports.COPILOT_MAX_MESSAGE_LENGTH = exports.COPILOT_TEXT_INPUT_DELAY_MS = exports.COPILOT_SEND_ENTER_DELAY_MS = void 0;
+exports.COPILOT_INSTALL_HINT = exports.MAX_MODEL_NAME_LENGTH = exports.MODEL_NAME_PATTERN = exports.COPILOT_MODEL_SWITCH_TIMEOUT_MS = exports.COPILOT_TRUNCATION_MARKER = exports.COPILOT_MAX_MESSAGE_LENGTH = exports.COPILOT_TEXT_INPUT_DELAY_MS = exports.COPILOT_SEND_ENTER_DELAY_MS = void 0;
 /**
  * Delay (ms) after sending text before pressing Enter.
  * Copilot CLI auto-enters multi-line mode when text exceeds pane width.
@@ -53,3 +53,13 @@ exports.MODEL_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9\-._/:]*$/;
  * Issue #588: Shared validation constant.
  */
 exports.MAX_MODEL_NAME_LENGTH = 128;
+/**
+ * How to install GitHub Copilot CLI, as shown when a session refuses to start.
+ * Issue #1907.
+ *
+ * The message this replaced was `gh extension install github/gh-copilot`, which
+ * installs a different, retired product (the `suggest` / `explain` extension).
+ * Copilot CLI is a standalone binary now, and `gh copilot` is a preview command
+ * built into `gh` that downloads it rather than a way of installing it.
+ */
+exports.COPILOT_INSTALL_HINT = 'Install with: brew install copilot-cli (macOS) or npm i -g @github/copilot';