commandmate 0.49.3 → 0.50.0

package/dist/cli/utils/security-logger.js

@@ -5,20 +5,59 @@
  * SF-SEC-2: Security event logging for CLI commands
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSecurityLogPath = getSecurityLogPath;
 exports.logSecurityEvent = logSecurityEvent;
 exports.maskSensitiveData = maskSensitiveData;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
+// Relative, not '@/': `tsconfig.cli.json` has no path aliases, so nothing the
+// CLI build compiles may reach an '@/' import. That is also why this does not
+// call `getLogDir()` (config/log-config → lib/env → lib/db/db-path-resolver,
+// all '@/'); `system-directories` is the guard `getLogDir()` itself ends in.
+const system_directories_1 = require("../../config/system-directories");
 /**
  * Get security log file path
+ *
+ * Issue #4210: `CM_LOG_DIR` is judged the way `getLogDir()`
+ * (`config/log-config.ts`) judges it for every other log writer. A value inside
+ * `/proc`, `/sys` or `/dev` — literally, through a symlink, or as the absolute
+ * form of a relative value — is refused and the default file is used. A
+ * relative value is otherwise kept as given and so resolved against this
+ * process's cwd, which is also what `getLogDir()` does: the file is only ever
+ * opened by the process that resolved it, so nothing else has to agree on it.
+ *
+ * The default stays `~/.commandmate-security.log` rather than `getLogDir()`'s
+ * `<cwd>/data/logs`: a CLI run from an arbitrary directory has no `data/logs`.
+ *
+ * @returns The file security events are appended to
  */
-function getLogPath() {
+function getSecurityLogPath() {
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate-security.log');
     const logDir = process.env.CM_LOG_DIR;
-    if (logDir) {
-        return (0, path_1.join)(logDir, 'security.log');
+    if (!logDir || isRefusedLogDir(logDir)) {
+        return fallback;
+    }
+    return (0, path_1.join)(logDir, 'security.log');
+}
+/**
+ * Whether `logDir` is one `getLogDir()` would refuse.
+ *
+ * An exception from the check itself keeps the configured value. Nothing here
+ * creates a directory — `appendFileSync` has no recursive mkdir, which is what
+ * hangs under `/proc` (Issue #1774) — so the worst a kept value can do is fail
+ * the append, which `logSecurityEvent` already ignores. Refusing on an
+ * exception would instead move events away from the directory that was asked
+ * for whenever the filesystem layer misbehaves (a test's `vi.mock('fs')` is
+ * one: `realpathSync` then answers `undefined`).
+ */
+function isRefusedLogDir(logDir) {
+    try {
+        return (0, system_directories_1.isVirtualFilesystemPath)(logDir);
+    }
+    catch {
+        return false;
     }
-    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate-security.log');
 }
 /**
  * Log a security event
@@ -26,7 +65,7 @@ function getLogPath() {
  */
 function logSecurityEvent(event) {
     try {
-        const logPath = getLogPath();
+        const logPath = getSecurityLogPath();
         const maskedDetails = maskSensitiveData(event.details);
         const logLine = `${event.timestamp} [${event.action.toUpperCase()}] ${event.command}: ${maskedDetails || ''}\n`;
         (0, fs_1.appendFileSync)(logPath, logLine, { mode: 0o600 });

package/dist/lib/detection/tools/verified-against.d.ts

@@ -258,6 +258,22 @@ export interface VerifiedAgainstStamp {
 /**
  * Tool id → the build its rules were measured against.
  *
+ * ## Reviewed by Issue #4146: no stamp moved
+ *
+ * Newer builds have been captured since, but only part of a screen set, and a
+ * stamp moves when the set is re-captured and read (see #2818, #2868, #2773).
+ *
+ *  - codex 0.166.0 (`tests/fixtures/codex-dialogs-0166/`): launch screens and the
+ *    idle composer. 未確認: the command approval, `/model`, and a running turn.
+ *  - opencode 1.18.35 (`tests/fixtures/opencode-live-4134/`): one finished turn.
+ *    未確認: the other four states the canary covers.
+ *  - claude 2.1.318 (`tests/fixtures/claude-auto-default-nudge-4134/`): one dialog.
+ *    未確認: everything else on that build.
+ *  - gemini and vibe-local have measured frames (a trust dialog; four readiness
+ *    screens) but no status rules read off them, so they stay `unmeasured`.
+ *
+ * `tests/unit/detection/tools/verified-against-4146.test.ts` keeps this list honest.
+ *
  * Keyed by the catalog / `CLIToolType` id, not by executable name: antigravity's
  * binary is `agy` (DR2-023), and that mapping belongs to the probe table, not
  * here.

package/dist/lib/detection/tools/verified-against.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verified-against.d.ts","sourceRoot":"","sources":["../../../../src/lib/detection/tools/verified-against.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,iEAAiE;AACjE,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,sBAAsB;;;;CAIzB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB;;;;CAI5B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,6BAA6B;;;;CAIhC,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAEX,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAUpF,CAAC"}
+{"version":3,"file":"verified-against.d.ts","sourceRoot":"","sources":["../../../../src/lib/detection/tools/verified-against.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,iEAAiE;AACjE,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,sBAAsB;;;;CAIzB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB;;;;CAI5B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,6BAA6B;;;;CAIhC,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAEX,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAUpF,CAAC"}

package/dist/lib/detection/tools/verified-against.js

@@ -255,6 +255,22 @@ exports.UNMEASURED_VERIFIED_AGAINST = {
 /**
  * Tool id → the build its rules were measured against.
  *
+ * ## Reviewed by Issue #4146: no stamp moved
+ *
+ * Newer builds have been captured since, but only part of a screen set, and a
+ * stamp moves when the set is re-captured and read (see #2818, #2868, #2773).
+ *
+ *  - codex 0.166.0 (`tests/fixtures/codex-dialogs-0166/`): launch screens and the
+ *    idle composer. 未確認: the command approval, `/model`, and a running turn.
+ *  - opencode 1.18.35 (`tests/fixtures/opencode-live-4134/`): one finished turn.
+ *    未確認: the other four states the canary covers.
+ *  - claude 2.1.318 (`tests/fixtures/claude-auto-default-nudge-4134/`): one dialog.
+ *    未確認: everything else on that build.
+ *  - gemini and vibe-local have measured frames (a trust dialog; four readiness
+ *    screens) but no status rules read off them, so they stay `unmeasured`.
+ *
+ * `tests/unit/detection/tools/verified-against-4146.test.ts` keeps this list honest.
+ *
  * Keyed by the catalog / `CLIToolType` id, not by executable name: antigravity's
  * binary is `agy` (DR2-023), and that mapping belongs to the probe table, not
  * here.

package/dist/lib/session/send-attempt-types.d.ts

@@ -52,6 +52,10 @@ export type SendAttemptReason =
  * input-boundary hook refused it and nothing was typed or dispatched (#3957/#3992).
  */
  | 'relay-reservation-lost'
+/** `not-sent`: the role this launch resolved cannot be applied, so nothing was started or typed (#4115). */
+ | 'role-launch-refused'
+/** `not-sent`: the role this send was conditional on does not hold right before the body (#4115). */
+ | 'role-condition-failed'
 /** `not-sent`: the pane could not be re-read under the input lock, so nothing was typed (#3945). */
  | 'recheck-failed'
 /**

package/dist/lib/session/send-attempt-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-attempt-types.d.ts","sourceRoot":"","sources":["../../../src/lib/session/send-attempt-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,eAAe,CAAC;AAErE,MAAM,MAAM,iBAAiB;AAC3B,wCAAwC;AACtC,WAAW;AACb,2EAA2E;GACzE,kBAAkB;AACpB,mEAAmE;GACjE,kBAAkB;AACpB,oDAAoD;GAClD,sBAAsB;AACxB,8GAA8G;GAC5G,gBAAgB;AAClB,sEAAsE;GACpE,iBAAiB;AACnB,oEAAoE;GAClE,qBAAqB;AACvB,4EAA4E;GAC1E,oBAAoB;AACtB,qGAAqG;GACnG,aAAa;AACf,gGAAgG;GAC9F,oBAAoB;AACtB,sGAAsG;GACpG,kBAAkB;AACpB,+FAA+F;GAC7F,iBAAiB;AACnB;;;;GAIG;GACD,wBAAwB;AAC1B,oGAAoG;GAClG,gBAAgB;AAClB;;;;GAIG;GACD,mBAAmB;AACrB,kHAAkH;GAChH,iBAAiB;AACnB,sGAAsG;GACpG,wBAAwB;AAC1B,sGAAsG;GACpG,oBAAoB;AACtB,sFAAsF;GACpF,kBAAkB;AACpB;;;GAGG;GACD,mBAAmB;AACrB;;;GAGG;GACD,mBAAmB;AACrB,yEAAyE;GACvE,YAAY,CAAC;AAEjB,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,gBAAgB,CAAC;IACxB,8FAA8F;IAC9F,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,yBAAyB,yBAAyB,CAAC"}
+{"version":3,"file":"send-attempt-types.d.ts","sourceRoot":"","sources":["../../../src/lib/session/send-attempt-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,eAAe,CAAC;AAErE,MAAM,MAAM,iBAAiB;AAC3B,wCAAwC;AACtC,WAAW;AACb,2EAA2E;GACzE,kBAAkB;AACpB,mEAAmE;GACjE,kBAAkB;AACpB,oDAAoD;GAClD,sBAAsB;AACxB,8GAA8G;GAC5G,gBAAgB;AAClB,sEAAsE;GACpE,iBAAiB;AACnB,oEAAoE;GAClE,qBAAqB;AACvB,4EAA4E;GAC1E,oBAAoB;AACtB,qGAAqG;GACnG,aAAa;AACf,gGAAgG;GAC9F,oBAAoB;AACtB,sGAAsG;GACpG,kBAAkB;AACpB,+FAA+F;GAC7F,iBAAiB;AACnB;;;;GAIG;GACD,wBAAwB;AAC1B,4GAA4G;GAC1G,qBAAqB;AACvB,qGAAqG;GACnG,uBAAuB;AACzB,oGAAoG;GAClG,gBAAgB;AAClB;;;;GAIG;GACD,mBAAmB;AACrB,kHAAkH;GAChH,iBAAiB;AACnB,sGAAsG;GACpG,wBAAwB;AAC1B,sGAAsG;GACpG,oBAAoB;AACtB,sFAAsF;GACpF,kBAAkB;AACpB;;;GAGG;GACD,mBAAmB;AACrB;;;GAGG;GACD,mBAAmB;AACrB,yEAAyE;GACvE,YAAY,CAAC;AAEjB,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,gBAAgB,CAAC;IACxB,8FAA8F;IAC9F,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,yBAAyB,yBAAyB,CAAC"}

package/dist/lib/verification/verify-config.d.ts

@@ -25,6 +25,20 @@ export interface VerifyGate {
      * key — and `undefined` is the honest reading of that.
      */
     mutex?: string;
+    /**
+     * How long this gate may wait for its {@link VerifyGate.mutex}, separately
+     * from how long its command may run (Issue #4162). Absent means `timeoutSec`,
+     * the single budget every gate had before this field existed.
+     *
+     * The two answer different questions: `timeoutSec` is "when is this command
+     * hung", and the wait is "how long is the queue on this machine". Sharing one
+     * number meant a longer queue could only be bought by also taking longer to
+     * notice a hang. Valid only beside a `mutex`: without a lock there is no wait.
+     *
+     * Optional for the same reason `mutex` is: contract rows are stored as JSON
+     * and read back without re-validating.
+     */
+    mutexWaitSec?: number;
     /**
      * Re-run this gate once, in the same tree, when its command exits non-zero
      * (Issue #1772). `1` opts in; `0` (the default) is the behaviour every gate
@@ -191,6 +205,14 @@ export declare const MAX_RETRY_ON_FAIL = 1;
  * this long is already a repository papering over a machine it should fix.
  */
 export declare const MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 32;
+/**
+ * Longest `mutexWaitSec` a gate may declare (Issue #4162): above `timeoutSec`'s
+ * ceiling on purpose, because a queue of several slow gates is longer than any
+ * one of them. A day is past any queue worth waiting behind.
+ */
+export declare const MAX_MUTEX_WAIT_SEC = 86400;
+/** The lock-wait budget of a gate, in seconds: `mutexWaitSec`, or `timeoutSec` when absent (Issue #4162). */
+export declare function mutexWaitBudgetSec(gate: Pick<VerifyGate, 'timeoutSec' | 'mutexWaitSec'>): number;
 export declare class VerifyConfigError extends Error {
     readonly issues: string[];
     constructor(issues: string[]);

package/dist/lib/verification/verify-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-config.d.ts","sourceRoot":"","sources":["../../../src/lib/verification/verify-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;;;;OAcG;IACH,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,kDAIpB,CAAC;AAEX,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,aAAa,GAAE,SAAS,UAAU,EAAO,GACxC,MAAM,EAAE,CAWV;AAED,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAM/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAA8B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAapD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAK7B;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAe9F;AA8RD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAYtE"}
+{"version":3,"file":"verify-config.d.ts","sourceRoot":"","sources":["../../../src/lib/verification/verify-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;;;;OAcG;IACH,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,kDAIpB,CAAC;AAEX,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,aAAa,GAAE,SAAS,UAAU,EAAO,GACxC,MAAM,EAAE,CAWV;AAED,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAM/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAA8B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,cAAc,CAAC,GAAG,MAAM,CAEhG;AAaD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAK7B;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAe9F;AAgTD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAYtE"}

package/dist/lib/verification/verify-config.js

@@ -8,8 +8,9 @@
  * Server-only: reads from disk, so import this from API routes / CLI only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerifyConfigError = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.VerifyConfigError = exports.MAX_MUTEX_WAIT_SEC = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
 exports.defaultPlannedGateIds = defaultPlannedGateIds;
+exports.mutexWaitBudgetSec = mutexWaitBudgetSec;
 exports.validateGateEntries = validateGateEntries;
 exports.loadVerifyConfig = loadVerifyConfig;
 const fs_1 = require("fs");
@@ -115,8 +116,18 @@ exports.MAX_RETRY_ON_FAIL = 1;
  * this long is already a repository papering over a machine it should fix.
  */
 exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 32;
+/**
+ * Longest `mutexWaitSec` a gate may declare (Issue #4162): above `timeoutSec`'s
+ * ceiling on purpose, because a queue of several slow gates is longer than any
+ * one of them. A day is past any queue worth waiting behind.
+ */
+exports.MAX_MUTEX_WAIT_SEC = 86400;
+/** The lock-wait budget of a gate, in seconds: `mutexWaitSec`, or `timeoutSec` when absent (Issue #4162). */
+function mutexWaitBudgetSec(gate) {
+    return gate.mutexWaitSec ?? gate.timeoutSec;
+}
 const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
-const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'mutexWaitSec', 'retryOnFail', 'flakyIsPass'];
 const OPTION_KEYS = [
     'baseRef',
     'skipInPrimaryCheckout',
@@ -261,6 +272,23 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
             mutex = entry.mutex;
         }
     }
+    let mutexWaitSec;
+    if (entry.mutexWaitSec !== undefined) {
+        const parsed = asInteger(entry.mutexWaitSec);
+        if (parsed === null) {
+            issues.push(`${at}.mutexWaitSec: must be an integer (got ${describe(entry.mutexWaitSec)})`);
+        }
+        else if (parsed < MIN_TIMEOUT_SEC || parsed > exports.MAX_MUTEX_WAIT_SEC) {
+            issues.push(`${at}.mutexWaitSec: must be ${MIN_TIMEOUT_SEC}..${exports.MAX_MUTEX_WAIT_SEC} (got ${parsed})`);
+        }
+        else if (entry.mutex === undefined) {
+            // A knob that can never fire is a config bug, as with flakyIsPass below.
+            issues.push(`${at}.mutexWaitSec: requires mutex (without a lock there is no wait)`);
+        }
+        else {
+            mutexWaitSec = parsed;
+        }
+    }
     let retryOnFail;
     if (entry.retryOnFail !== undefined) {
         const parsed = asInteger(entry.retryOnFail);
@@ -304,6 +332,8 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
         // absence has to keep meaning "this gate runs exactly once".
         if (mutex !== undefined)
             gate.mutex = mutex;
+        if (mutexWaitSec !== undefined)
+            gate.mutexWaitSec = mutexWaitSec;
         if (retryOnFail !== undefined)
             gate.retryOnFail = retryOnFail;
         if (flakyIsPass !== undefined)

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

@@ -1278,21 +1278,31 @@
         "badgeOwedMany": "Replies due ({count})",
         "badgeAwaiting": "Waiting on {alias}",
         "badgeAwaitingMany": "Waiting on {count} replies",
-        "badgePrompt": "Confirmation reported",
+        "badgePrompt": "Worker confirmation recorded",
         "owedTitle": "This session owes a delegated reply. It is delivered automatically when the turn ends.",
         "awaitingTitle": "This session is waiting for a delegated reply. It arrives in the composer as a relay message.",
-        "promptTitle": "The other session stopped on a confirmation; the requester has been told.",
+        "promptTitle": "A record that the other session stopped on a confirmation. It does not say the session is still waiting: it stays until this relay closes, also after the confirmation is answered and the reply takes the notice's place. A notice to the requester was queued for delivery; this badge does not say whether it arrived (check with commandmate relays --id).",
         "stripAwaiting": "Delegated to {alias}; waiting for the reply.",
         "stripAwaitingMany": "Waiting for {count} delegated replies.",
-        "stripPrompt": "{alias} is waiting for a confirmation.",
+        "stripPrompt": "{alias} stopped on a confirmation earlier (recorded; it may have been answered since).",
         "stripOwed": "Owed to {alias}: this session's reply is delivered when the turn ends.",
-        "badgeHeld": "Delivery from {alias} unconfirmed",
-        "badgeHeldMany": "Unconfirmed deliveries ({count})",
+        "badgeHeld": "Unconfirmed: {alias}",
+        "badgeHeldMany": "{count} unconfirmed",
         "heldTitle": "Whether a relay delivery to this session (a reply, a confirmation notice or an expiry notice) arrived is not known. It is not resent automatically. Check this pane, then settle it with commandmate relays resolve.",
         "stripHeld": "Delivery from {alias} unconfirmed: check this pane, then settle it with relays resolve.",
+        "badgeBlockedByPrompt": "Delivery from {alias} stopped by this pane's dialog",
+        "badgeBlockedByPromptMany": "{count} deliveries stopped by this pane's dialog",
+        "blockedByPromptTitle": "At the last delivery attempt this session (the requester) showed a confirmation dialog, so the relay delivery was stopped (nothing was typed). Answer the dialog and it is delivered on the next delivery pass (about every 15 s). Left alone, it is replaced by the expiry notice at the deadline. This is what the last attempt observed; commandmate relays --id shows when.",
+        "stripBlockedByPrompt": "Delivery from {alias} is stopped by this pane's confirmation dialog (as of the last attempt). Answer it and the delivery goes through.",
+        "stripBlockedByPromptMany": "{count} deliveries are stopped by this pane's confirmation dialog (as of the last attempt). Answer it and they go through.",
         "stripHeldMany": "{count} unconfirmed deliveries: check this pane, then settle them with relays resolve.",
         "unplacedHeldHeading": "Unconfirmed deliveries to sessions not in the roster",
         "unplacedHeldLine": "{requester} ← {alias} (relay {relayId})",
+        "blockedByPromptClosedTitle": "At the last delivery attempt this session (the requester) showed a confirmation dialog, so the expiry notice of a relay closed by its deadline was stopped (nothing was typed). Answer the dialog and it is delivered on the next delivery pass (about every 15 s). The notice stays until it is delivered; nothing replaces it. This is what the last attempt observed; commandmate relays --id shows when.",
+        "blockedByPromptMixedTitle": "At the last delivery attempt this session (the requester) showed a confirmation dialog, so the relay deliveries were stopped (nothing was typed). Answer the dialog and they are delivered on the next delivery pass (about every 15 s). Left alone, a reply of an open relay is replaced by the expiry notice at the deadline; the expiry notice of a relay closed by its deadline stays until it is delivered. This is what the last attempt observed; commandmate relays --id shows when.",
+        "unplacedBlockedHeading": "Expiry notices to sessions not in the roster (delivery stopped)",
+        "unplacedBlockedTitle": "The expiry notice of a relay closed by its deadline has not reached a session (the requester) that is not in the roster. The reason is what the last delivery attempt observed (prompt_waiting = that pane shows a confirmation dialog). It goes away once delivered; commandmate relays shows it.",
+        "unplacedBlockedLine": "{requester} ← {alias} (relay {relayId}): stopped by {reason}",
         "historyBadge": "relay",
         "historyBadgeTitle": "Delivered by another agent session (Issue #2377 relay).",
         "historyCount": "{count} relayed message(s) in view"
@@ -1728,6 +1738,15 @@
         "submit": "Add",
         "cancel": "Cancel",
         "saveError": "Could not add the agent.",
-        "maxReached": "Up to {max} agents per branch"
+        "maxReached": "Up to {max} agents per branch",
+        "role": "Role",
+        "roleUnsupported": "Roles do not apply to this agent.",
+        "roleUnavailable": "The role information could not be read, so this is added with the default role.",
+        "roleMissing": "The chosen role no longer exists. Reopen this and choose again.",
+        "rosterChanged": "The roster kept changing elsewhere, so this was not added. Try again.",
+        "rosterUnreadable": "The current roster could not be read, so this was not added, to avoid erasing other changes. Check the connection and try again.",
+        "savedUnverified": "The session was added, but the latest roster could not be read back. Do not add it again; reload the page.",
+        "outcomeUnknown": "Whether the session was added could not be confirmed. Do not add it again; reload the page and check the roster.",
+        "removedElsewhere": "The session was added, but it was removed elsewhere right after, so it was not opened. Add it again if you still need it."
     }
 }

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

@@ -1278,21 +1278,31 @@
         "badgeOwedMany": "返信予定 {count} 件",
         "badgeAwaiting": "{alias} の返信待ち",
         "badgeAwaitingMany": "返信待ち {count} 件",
-        "badgePrompt": "確認待ちを通知済み",
+        "badgePrompt": "相手の確認待ちを記録",
         "owedTitle": "このセッションは委任された返信を抱えています。ターン完了時に自動で届きます。",
         "awaitingTitle": "このセッションは委任した返信を待っています。届くとコンポーザーに relay メッセージとして入ります。",
-        "promptTitle": "相手セッションが確認待ちで止まり、依頼元へ通知済みです。",
+        "promptTitle": "相手セッションが確認待ちで止まったことの記録です。相手が今も確認待ちかどうかは表しません（相手が確認を終えて返信が知らせを置き換えた後も、この relay が閉じるまで残ります）。依頼元への知らせは配送の待ち行列に入れました（届いたかどうかはこの表示では分かりません。commandmate relays --id で確かめられます）。",
         "stripAwaiting": "{alias} へ委任、返信待ち",
         "stripAwaitingMany": "返信待ち {count} 件",
-        "stripPrompt": "{alias} が確認待ち",
+        "stripPrompt": "{alias} の確認待ちを記録（今も確認待ちとは限りません）",
         "stripOwed": "{alias} へ返信予定: ターン完了時に届きます",
-        "badgeHeld": "{alias} からの配送が未確認",
-        "badgeHeldMany": "配送未確認 {count} 件",
+        "badgeHeld": "配送が未確認: {alias}",
+        "badgeHeldMany": "{count} 件の配送が未確認",
         "heldTitle": "このセッションへの relay の配送（返信・確認待ちの通知・期限切れの通知）が届いたか分かりません。自動では再送しません。この画面を確かめてから commandmate relays resolve で片付けてください。",
         "stripHeld": "{alias} からの配送が未確認: 画面を確かめて relays resolve で片付けてください",
+        "badgeBlockedByPrompt": "{alias} からの配送: この画面の確認で停止",
+        "badgeBlockedByPromptMany": "{count} 件の配送: この画面の確認で停止",
+        "blockedByPromptTitle": "最後の配送の試行のとき、このセッション（依頼元）の画面に確認の案内が出ていたため、relay の配送を止めました（何も打鍵していません）。案内に答えると、次の配送の周回（約 15 秒ごと）で届きます。放置すると期限で時間切れの知らせに置き換わります。最後の試行の時点の観測です。観測時刻は commandmate relays --id で確かめられます。",
+        "stripBlockedByPrompt": "{alias} からの配送が、この画面の確認の案内で止まっています（最後の試行の時点）。案内に答えると届きます",
+        "stripBlockedByPromptMany": "{count} 件の配送が、この画面の確認の案内で止まっています（最後の試行の時点）。案内に答えると届きます",
         "stripHeldMany": "配送未確認 {count} 件: 画面を確かめて relays resolve で片付けてください",
         "unplacedHeldHeading": "名簿に無いセッションへの配送未確認",
         "unplacedHeldLine": "{requester} ← {alias}（relay {relayId}）",
+        "blockedByPromptClosedTitle": "期限切れで閉じた relay の時間切れの知らせを、最後の配送の試行のとき、このセッション（依頼元）の画面に確認の案内が出ていたため止めました（何も打鍵していません）。案内に答えると、次の配送の周回（約 15 秒ごと）で届きます。この知らせは届くまで残り、別の知らせに置き換わることはありません。最後の試行の時点の観測です。観測時刻は commandmate relays --id で確かめられます。",
+        "blockedByPromptMixedTitle": "最後の配送の試行のとき、このセッション（依頼元）の画面に確認の案内が出ていたため、relay の配送を止めました（何も打鍵していません）。案内に答えると、次の配送の周回（約 15 秒ごと）で届きます。開いている relay の返答は、放置すると期限で時間切れの知らせに置き換わります。期限切れで閉じた relay の時間切れの知らせは、届くまで残ります。最後の試行の時点の観測です。観測時刻は commandmate relays --id で確かめられます。",
+        "unplacedBlockedHeading": "名簿に無いセッションへの時間切れの知らせ（配送が停止中）",
+        "unplacedBlockedTitle": "期限切れで閉じた relay の時間切れの知らせが、名簿に無いセッション（依頼元）へ届かず止まっています。理由は最後の配送の試行の時点の観測です（prompt_waiting = その画面に確認の案内）。届くと消えます。commandmate relays で確かめられます。",
+        "unplacedBlockedLine": "{requester} ← {alias}（relay {relayId}）: 停止の理由 {reason}",
         "historyBadge": "relay",
         "historyBadgeTitle": "別のエージェントセッションから届いたメッセージです（Issue #2377 relay）。",
         "historyCount": "表示範囲に relay メッセージが {count} 件"
@@ -1728,6 +1738,15 @@
         "submit": "追加",
         "cancel": "キャンセル",
         "saveError": "エージェントを追加できませんでした。",
-        "maxReached": "1 つのブランチに追加できるのは {max} 件までです"
+        "maxReached": "1 つのブランチに追加できるのは {max} 件までです",
+        "role": "ロール",
+        "roleUnsupported": "このエージェントはロールの対象外です。",
+        "roleUnavailable": "ロールの情報を読めなかったため、既定のロールを引き継いで追加します。",
+        "roleMissing": "選んだロールが見つかりません。開き直して選び直してください。",
+        "rosterChanged": "名簿が別の場所で変更され続けたため、追加できませんでした。もう一度お試しください。",
+        "rosterUnreadable": "今の名簿を読めなかったため、追加しませんでした。他の変更を消さないためです。接続を確かめてもう一度お試しください。",
+        "savedUnverified": "追加は保存しましたが、最新の名簿を読み直せませんでした。もう一度追加せず、ページを再読み込みしてください。",
+        "outcomeUnknown": "追加できたか確かめられませんでした。もう一度追加せず、ページを再読み込みして名簿を確かめてください。",
+        "removedElsewhere": "追加しましたが、その直後に別の場所で削除されたため開いていません。必要ならもう一度追加してください。"
     }
 }

package/dist/server/src/config/safe-directory.js

@@ -42,6 +42,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetSafeDirectoryWarnings = resetSafeDirectoryWarnings;
 exports.resolveSafeDirectory = resolveSafeDirectory;
+exports.resolveSafeAbsoluteDirectory = resolveSafeAbsoluteDirectory;
+const path_1 = require("path");
 const logger_1 = require("../lib/logger");
 const system_directories_1 = require("./system-directories");
 const logger = (0, logger_1.createLogger)('safe-directory');
@@ -101,3 +103,31 @@ function resolveSafeDirectory(candidate, fallback, source) {
     }
     return fallback;
 }
+/**
+ * {@link resolveSafeDirectory} for a value that another process will be handed
+ * (Issue #4191): a relative candidate is made absolute against this process's
+ * working directory first, and the `/proc` check runs on that absolute form.
+ *
+ * `resolveSafeDirectory` returns a relative value as it was given, which is
+ * right for a directory only this process opens — `fs` resolves it against the
+ * same cwd every time. It is wrong for a path written into a command line, a
+ * tmux hook or a child's environment: the child resolves it against ITS cwd.
+ * Measured for `CM_AGENT_HOOKS_DIR`: the daemon runs from the package root
+ * (`src/cli/utils/daemon.ts`, `cwd: packageRoot`) and writes the settings file
+ * there, while claude is started in the worktree (`claude-session.ts`,
+ * `createSession({ workingDirectory: worktreePath })`) and reads
+ * `--settings <relative>` from there — another file, or none, and no events.
+ *
+ * Opt-in rather than a change to `resolveSafeDirectory`, whose other callers
+ * keep their values verbatim (`tests/unit/config/safe-directory.test.ts` pins
+ * that); each of them has to be judged on whether its value leaves the process.
+ *
+ * @param candidate - The configured path. Empty or undefined means "unset"
+ * @param fallback - The built-in default, already absolute
+ * @param source - What supplied the candidate, for the warning
+ * @returns The absolute form of `candidate`, or `fallback` when it is unset or
+ *   inside `/proc`, `/sys` or `/dev`
+ */
+function resolveSafeAbsoluteDirectory(candidate, fallback, source) {
+    return resolveSafeDirectory(candidate ? (0, path_1.resolve)(candidate) : undefined, fallback, source);
+}

package/dist/server/src/lib/agent-roles/adapters.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_CONFIG_CONTENT_ENV_VAR = exports.OPENCODE_V2_COMMON_INSTRUCTIONS = exports.ROLE_WRAPPER_TEXT = exports.OPENCODE_V2_WRAPPER_VERSION = exports.ROLE_WRAPPER_VERSION = void 0;
+exports.roleWrapperVersion = roleWrapperVersion;
+exports.computeRoleInjection = computeRoleInjection;
+exports.buildRoleLaunchArguments = buildRoleLaunchArguments;
+exports.splitRoleEnv = splitRoleEnv;
+exports.renderSecretEnvAssignment = renderSecretEnvAssignment;
+exports.renderRoleFlags = renderRoleFlags;
+/**
+ * The transform from a resolved role to what each CLI is handed (§5–§7 of
+ * `docs/design/agent-roles-adapters.md`). Pure: no database, no filesystem, no
+ * tmux. What the user's settings say arrives as {@link RoleComposition}, read
+ * once by `./composition`, so the same inputs always give the same fingerprint.
+ *
+ * ## The injection fingerprint
+ *
+ * It says what the process would actually be told, and it decides everything that
+ * compares roles: restart pending, whether two launches may join, and the file name.
+ * In: the adapter and its version, the wrapper version, the body fingerprint, and
+ * the composition inputs (Codex's `developer_instructions`, V2's effective agent, an
+ * explicit agent). Out: the role's name and id, where it was inherited from, paths,
+ * and the other keys of the user's env. So a rename or another level holding the
+ * same text is not a restart, and a change in `config.toml` is.
+ *
+ * @module lib/agent-roles/adapters
+ */
+const path_1 = require("path");
+const hook_settings_generator_1 = require("../../lib/hooks/hook-settings-generator");
+const fingerprint_1 = require("./fingerprint");
+/** Moves when what an adapter generates for the same input changes. */
+const ADAPTER_VERSION = '1';
+/** The wrapper every adapter puts around a body. Moves with its text. */
+exports.ROLE_WRAPPER_VERSION = '1';
+/** V2's wrapper: the shared one plus {@link OPENCODE_V2_COMMON_INSTRUCTIONS}. */
+exports.OPENCODE_V2_WRAPPER_VERSION = '1+common-1';
+/**
+ * Says that the request and the contract outrank the role. It is a request to the
+ * model and guarantees nothing (§5): the gates still judge by evidence.
+ */
+exports.ROLE_WRAPPER_TEXT = 'CommandMate started you with the role below. Keep following the current request, ' +
+    'any execution contract and the project instructions (AGENTS.md, CLAUDE.md and the like); ' +
+    'where they conflict with the role, they win. The role does not relax a contract, ' +
+    'a verification step or a permission rule.';
+/**
+ * For OpenCode V2 only, whose `system` replaces the provider's base prompt (§7.2).
+ * A precaution for the guidance that replacement drops, not a measured improvement.
+ * The API says "replaces the default instructions" beside it.
+ */
+exports.OPENCODE_V2_COMMON_INSTRUCTIONS = [
+    'You are an AI agent running in OpenCode, a coding agent harness. Help the user accomplish their goals using the tools you have available.',
+    'Prefer dedicated tools over shell commands; fall back to the shell when a tool cannot do what you need.',
+    'Keep changes consistent with the structure, naming, style, and patterns of the surrounding code.',
+    'Treat unfamiliar files or changes as potential user work and investigate before deleting or overwriting them.',
+].join('\n');
+function roleWrapperVersion(adapter) {
+    return adapter === 'opencode-v2' ? exports.OPENCODE_V2_WRAPPER_VERSION : exports.ROLE_WRAPPER_VERSION;
+}
+function buildInstructions(adapter, body, composition) {
+    const wrapped = `${exports.ROLE_WRAPPER_TEXT}\n\n${body}`;
+    if (adapter === 'opencode-v2')
+        return `${exports.OPENCODE_V2_COMMON_INSTRUCTIONS}\n\n${wrapped}`;
+    const existing = composition.codexDeveloperInstructions;
+    if (adapter === 'codex' && existing)
+        return `${existing}\n\n${wrapped}`;
+    return wrapped;
+}
+/**
+ * Fingerprint and text for one role through one adapter.
+ *
+ * @param role - Only the body fingerprint and body are read; the name and id are not inputs
+ */
+function computeRoleInjection(adapter, role, composition) {
+    const wrapperVersion = roleWrapperVersion(adapter);
+    const codexSource = adapter === 'codex' && composition.codexDeveloperInstructions
+        ? (0, fingerprint_1.computeBodyFingerprint)(composition.codexDeveloperInstructions)
+        : null;
+    const effectiveAgent = adapter === 'opencode-v2' ? (composition.opencodeV2EffectiveAgent ?? null) : null;
+    const explicitAgent = composition.explicitAgent ?? null;
+    const canonical = JSON.stringify({
+        adapter,
+        adapterVersion: ADAPTER_VERSION,
+        wrapperVersion,
+        bodyFingerprint: role.bodyFingerprint,
+        codexDeveloperInstructions: codexSource,
+        effectiveAgent,
+        explicitAgent,
+    });
+    return {
+        adapter,
+        adapterVersion: ADAPTER_VERSION,
+        wrapperVersion,
+        injectionFingerprint: (0, fingerprint_1.computeFingerprint)(Buffer.from(canonical, 'utf8')),
+        instructions: buildInstructions(adapter, role.body, composition),
+        effectiveAgent,
+        compositionSourceFingerprint: codexSource,
+    };
+}
+exports.OPENCODE_CONFIG_CONTENT_ENV_VAR = 'OPENCODE_CONFIG_CONTENT';
+const CODEX_HOME_ENV_VAR = 'CODEX_HOME';
+const COPILOT_HOME_ENV_VAR = 'COPILOT_HOME';
+/** V1: appended to `instructions`, and nothing else touched (#2053's lesson). */
+function composeOpencodeV1Content(user, path) {
+    const existing = user?.instructions;
+    return { ...user, instructions: [...(Array.isArray(existing) ? existing : []), path] };
+}
+/** V2: `agents.<effective>.system` only. `model`, `providers`, `default_agent` stay. */
+function composeOpencodeV2Content(user, agent, path) {
+    const agents = (user?.agents ?? {});
+    const current = (agents[agent] ?? {});
+    return { ...user, agents: { ...agents, [agent]: { ...current, system: `{file:${path}}` } } };
+}
+/**
+ * The arguments and environment that hand one generated file to its CLI.
+ *
+ * @param artifact - The name and path `writeRoleArtifact` answered
+ */
+function buildRoleLaunchArguments(injection, artifact, composition) {
+    const flag = (args, headlessPosition, env = {}) => ({
+        args,
+        headlessPosition,
+        env,
+        envCarriesUserValues: false,
+    });
+    const content = (value) => ({
+        args: [],
+        headlessPosition: 'trailing',
+        env: { [exports.OPENCODE_CONFIG_CONTENT_ENV_VAR]: JSON.stringify(value) },
+        envCarriesUserValues: composition.opencodeUserContent != null,
+    });
+    const { adapter } = injection;
+    switch (adapter) {
+        case 'claude':
+            return flag(['--append-system-prompt-file', artifact.path], 'trailing');
+        case 'codex':
+            // Codex finds a profile by name in its home, and a pane has the tmux server's
+            // environment, not this process's. The home is stated so that the file just
+            // inspected is the one it finds, with hooks on or off.
+            return flag(['-p', artifact.name], 'leading', { [CODEX_HOME_ENV_VAR]: (0, path_1.dirname)(artifact.path) });
+        case 'command-code':
+            return flag(['--mod', artifact.path], 'trailing');
+        case 'copilot':
+            // The same for Copilot, whose definitions are in `<home>/agents/`.
+            return flag(['--agent', artifact.name], 'leading', { [COPILOT_HOME_ENV_VAR]: (0, path_1.dirname)((0, path_1.dirname)(artifact.path)) });
+        case 'antigravity':
+            return flag(['--agent', artifact.name], 'trailing');
+        case 'opencode':
+            return content(composeOpencodeV1Content(composition.opencodeUserContent, artifact.path));
+        case 'opencode-v2':
+            return content(composeOpencodeV2Content(composition.opencodeUserContent, injection.effectiveAgent ?? 'build', artifact.path));
+    }
+}
+/**
+ * Which part of a role's environment may be written on a line.
+ *
+ * @returns `plain`, safe to spell (paths and names); `secret`, the value of the one
+ *   variable that has to go through a private file, when it holds the user's values
+ */
+function splitRoleEnv(role) {
+    const { [exports.OPENCODE_CONFIG_CONTENT_ENV_VAR]: content, ...others } = role.env;
+    if (content === undefined)
+        return { plain: others, secret: null };
+    if (role.envCarriesUserValues)
+        return { plain: others, secret: content };
+    return { plain: { ...others, [exports.OPENCODE_CONFIG_CONTENT_ENV_VAR]: content }, secret: null };
+}
+/** The assignment that reads a composed config from its private file. */
+function renderSecretEnvAssignment(file) {
+    return `${exports.OPENCODE_CONFIG_CONTENT_ENV_VAR}="$(cat ${(0, hook_settings_generator_1.shellQuote)(file)})" `;
+}
+/** The arguments as they go on a shell line. */
+function renderRoleFlags(args) {
+    return args.map((arg) => (/^[A-Za-z0-9_./=-]+$/.test(arg) ? arg : (0, hook_settings_generator_1.shellQuote)(arg))).join(' ');
+}