commandmate 0.49.3 → 0.50.0

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

@@ -0,0 +1,409 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTANCE_CREATION_KEY_TTL_MS = exports.AgentRoleInUseError = exports.AgentRoleNameChangedError = exports.AgentRoleVersionConflictError = exports.AgentRoleNameConflictError = exports.AgentRoleNotFoundError = exports.AgentRoleValidationError = void 0;
+exports.listAgentRoles = listAgentRoles;
+exports.getAgentRole = getAgentRole;
+exports.createAgentRole = createAgentRole;
+exports.getAgentRoleReferences = getAgentRoleReferences;
+exports.updateAgentRole = updateAgentRole;
+exports.deleteAgentRole = deleteAgentRole;
+exports.getSystemRoleDefaults = getSystemRoleDefaults;
+exports.setSystemRoleDefault = setSystemRoleDefault;
+exports.getRepositoryRoleStates = getRepositoryRoleStates;
+exports.setRepositoryRoleState = setRepositoryRoleState;
+exports.getInstanceRoleState = getInstanceRoleState;
+exports.setInstanceRoleState = setInstanceRoleState;
+exports.hasAnyRoleSetting = hasAnyRoleSetting;
+exports.getInstanceCreationKey = getInstanceCreationKey;
+exports.recordInstanceCreationKey = recordInstanceCreationKey;
+exports.settleInstanceCreationKey = settleInstanceCreationKey;
+exports.recordRoleLaunch = recordRoleLaunch;
+exports.getLatestRoleLaunchRecords = getLatestRoleLaunchRecords;
+/**
+ * Role tables (Issue #4114, migration v64).
+ *
+ * Every write that could leave a reference half done runs in a transaction. The
+ * body is never logged and never placed in an error message.
+ *
+ * @module lib/db/agent-roles-db
+ */
+const crypto_1 = require("crypto");
+const fingerprint_1 = require("../../lib/agent-roles/fingerprint");
+const validation_1 = require("../../lib/agent-roles/validation");
+class AgentRoleValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentRoleValidationError';
+    }
+}
+exports.AgentRoleValidationError = AgentRoleValidationError;
+class AgentRoleNotFoundError extends Error {
+    roleId;
+    constructor(roleId) {
+        super(`Role not found: ${roleId}`);
+        this.roleId = roleId;
+        this.name = 'AgentRoleNotFoundError';
+    }
+}
+exports.AgentRoleNotFoundError = AgentRoleNotFoundError;
+class AgentRoleNameConflictError extends Error {
+    constructor(name) {
+        super(`A role named "${name}" already exists`);
+        this.name = 'AgentRoleNameConflictError';
+    }
+}
+exports.AgentRoleNameConflictError = AgentRoleNameConflictError;
+class AgentRoleVersionConflictError extends Error {
+    currentBodyVersion;
+    constructor(currentBodyVersion) {
+        super(`The role is at body version ${currentBodyVersion}`);
+        this.currentBodyVersion = currentBodyVersion;
+        this.name = 'AgentRoleVersionConflictError';
+    }
+}
+exports.AgentRoleVersionConflictError = AgentRoleVersionConflictError;
+class AgentRoleNameChangedError extends Error {
+    currentName;
+    constructor(currentName) {
+        super('The role was renamed since it was read');
+        this.currentName = currentName;
+        this.name = 'AgentRoleNameChangedError';
+    }
+}
+exports.AgentRoleNameChangedError = AgentRoleNameChangedError;
+class AgentRoleInUseError extends Error {
+    references;
+    constructor(references) {
+        super('The role is in use');
+        this.references = references;
+        this.name = 'AgentRoleInUseError';
+    }
+}
+exports.AgentRoleInUseError = AgentRoleInUseError;
+function mapRole(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        body: row.body,
+        bodyVersion: row.body_version,
+        bodyFingerprint: (0, fingerprint_1.computeBodyFingerprint)(row.body),
+        bodyBytes: Buffer.byteLength(row.body, 'utf8'),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function isUniqueNameViolation(error) {
+    return error instanceof Error && error.message.includes('UNIQUE constraint failed: agent_roles.name');
+}
+function validatedName(name) {
+    const normalized = (0, validation_1.normalizeRoleName)(name);
+    if (!normalized.ok)
+        throw new AgentRoleValidationError(normalized.problem);
+    return normalized.name;
+}
+function assertBody(body) {
+    const problem = (0, validation_1.roleBodyProblem)(body);
+    if (problem)
+        throw new AgentRoleValidationError(problem);
+}
+// ---------------------------------------------------------------------------
+// Roles
+// ---------------------------------------------------------------------------
+/** Every role, by name. */
+function listAgentRoles(db) {
+    const rows = db.prepare('SELECT * FROM agent_roles ORDER BY name ASC').all();
+    return rows.map(mapRole);
+}
+function getAgentRole(db, id) {
+    const row = db.prepare('SELECT * FROM agent_roles WHERE id = ?').get(id);
+    return row ? mapRole(row) : null;
+}
+/**
+ * @throws {AgentRoleValidationError} The name or body is not acceptable
+ * @throws {AgentRoleNameConflictError} The name is taken
+ */
+function createAgentRole(db, input) {
+    const name = validatedName(input.name);
+    assertBody(input.body);
+    // Short and hex: it becomes part of a generated file name.
+    const id = (0, crypto_1.randomBytes)(8).toString('hex');
+    const now = Date.now();
+    try {
+        db.prepare(`INSERT INTO agent_roles (id, name, body, body_version, created_at, updated_at) VALUES (?, ?, ?, 1, ?, ?)`).run(id, name, input.body, now, now);
+    }
+    catch (error) {
+        if (isUniqueNameViolation(error))
+            throw new AgentRoleNameConflictError(name);
+        throw error;
+    }
+    return getAgentRole(db, id);
+}
+/** What points directly at this role. */
+function getAgentRoleReferences(db, roleId) {
+    const instances = db
+        .prepare(`SELECT worktree_id AS worktreeId, instance_id AS instanceId FROM agent_instance_roles
+       WHERE role_id = ? ORDER BY worktree_id, instance_id`)
+        .all(roleId);
+    const repositories = db
+        .prepare(`SELECT d.repository_id AS repositoryId, r.path AS repositoryPath, d.cli_tool_id AS cliToolId
+       FROM agent_role_repository_defaults d JOIN repositories r ON r.id = d.repository_id
+       WHERE d.role_id = ? ORDER BY r.path, d.cli_tool_id`)
+        .all(roleId);
+    const system = db
+        .prepare(`SELECT cli_tool_id AS cliToolId FROM agent_role_system_defaults WHERE role_id = ? ORDER BY cli_tool_id`)
+        .all(roleId);
+    return { instances, repositories, system };
+}
+/**
+ * Edit a role. The body version moves only when the bytes change, so a rename is
+ * not a new version of the text.
+ *
+ * @param input.expectedBodyVersion - When given, the edit applies only at this version
+ * @param input.expectedName - When given, the edit applies only under this name, or
+ *   when the role already has the name asked for
+ * @throws {AgentRoleNotFoundError}
+ * @throws {AgentRoleVersionConflictError} Someone else got there first; nothing changed
+ * @throws {AgentRoleNameChangedError} Someone else renamed it first; nothing changed
+ * @throws {AgentRoleValidationError}
+ * @throws {AgentRoleNameConflictError}
+ */
+function updateAgentRole(db, id, input) {
+    const name = input.name === undefined ? undefined : validatedName(input.name);
+    if (input.body !== undefined)
+        assertBody(input.body);
+    const newBody = input.body;
+    return db.transaction(() => {
+        const before = getAgentRole(db, id);
+        if (!before)
+            throw new AgentRoleNotFoundError(id);
+        if (input.expectedBodyVersion !== undefined && input.expectedBodyVersion !== before.bodyVersion) {
+            throw new AgentRoleVersionConflictError(before.bodyVersion);
+        }
+        if (input.expectedName !== undefined && input.expectedName !== before.name && name !== before.name) {
+            throw new AgentRoleNameChangedError(before.name);
+        }
+        const bodyChanged = newBody !== undefined && newBody !== before.body;
+        try {
+            db.prepare(`UPDATE agent_roles SET name = ?, body = ?, body_version = ?, updated_at = ? WHERE id = ?`).run(name ?? before.name, newBody ?? before.body, bodyChanged ? before.bodyVersion + 1 : before.bodyVersion, Date.now(), id);
+        }
+        catch (error) {
+            if (isUniqueNameViolation(error))
+                throw new AgentRoleNameConflictError(name ?? before.name);
+            throw error;
+        }
+        return {
+            before,
+            after: getAgentRole(db, id),
+            affected: getAgentRoleReferences(db, id),
+        };
+    })();
+}
+/**
+ * Delete a role. With `force`, the settings pointing at it go in the same
+ * transaction, so they read as "inherit" afterwards and not as an explicit none.
+ * Launch records and generated files stay.
+ *
+ * @throws {AgentRoleNotFoundError}
+ * @throws {AgentRoleInUseError} It has references and `force` was not given
+ */
+function deleteAgentRole(db, id, options = {}) {
+    return db.transaction(() => {
+        const role = getAgentRole(db, id);
+        if (!role)
+            throw new AgentRoleNotFoundError(id);
+        const affected = getAgentRoleReferences(db, id);
+        const inUse = affected.instances.length + affected.repositories.length + affected.system.length > 0;
+        if (inUse && !options.force)
+            throw new AgentRoleInUseError(affected);
+        db.prepare('DELETE FROM agent_instance_roles WHERE role_id = ?').run(id);
+        db.prepare('DELETE FROM agent_role_repository_defaults WHERE role_id = ?').run(id);
+        db.prepare('DELETE FROM agent_role_system_defaults WHERE role_id = ?').run(id);
+        db.prepare('DELETE FROM agent_roles WHERE id = ?').run(id);
+        return { role, affected };
+    })();
+}
+function assertRoleExists(db, roleId) {
+    if (!db.prepare('SELECT 1 FROM agent_roles WHERE id = ?').get(roleId)) {
+        throw new AgentRoleNotFoundError(roleId);
+    }
+}
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+function toStoredState(row) {
+    if (!row)
+        return { state: 'inherit' };
+    if (row.role_id === null)
+        return { state: 'none' };
+    return { state: 'role', roleId: row.role_id, roleName: row.role_name };
+}
+/** @returns The tools with a system default. A missing key means unset. */
+function getSystemRoleDefaults(db) {
+    const rows = db
+        .prepare(`SELECT d.cli_tool_id, d.role_id, r.name AS role_name
+       FROM agent_role_system_defaults d JOIN agent_roles r ON r.id = d.role_id`)
+        .all();
+    return Object.fromEntries(rows.map((row) => [row.cli_tool_id, { roleId: row.role_id, roleName: row.role_name }]));
+}
+/**
+ * @param roleId - The role, or null for unset (no row)
+ * @throws {AgentRoleNotFoundError}
+ */
+function setSystemRoleDefault(db, cliToolId, roleId) {
+    if (roleId === null) {
+        db.prepare('DELETE FROM agent_role_system_defaults WHERE cli_tool_id = ?').run(cliToolId);
+        return;
+    }
+    assertRoleExists(db, roleId);
+    db.prepare(`INSERT INTO agent_role_system_defaults (cli_tool_id, role_id, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(cli_tool_id) DO UPDATE SET role_id = excluded.role_id, updated_at = excluded.updated_at`).run(cliToolId, roleId, Date.now());
+}
+/** @returns The tools with a row for this root. A missing key means inherit. */
+function getRepositoryRoleStates(db, repositoryId) {
+    const rows = db
+        .prepare(`SELECT d.cli_tool_id, d.role_id, r.name AS role_name
+       FROM agent_role_repository_defaults d LEFT JOIN agent_roles r ON r.id = d.role_id
+       WHERE d.repository_id = ?`)
+        .all(repositoryId);
+    return Object.fromEntries(rows.map((row) => [row.cli_tool_id, toStoredState(row)]));
+}
+/** @throws {AgentRoleNotFoundError} */
+function setRepositoryRoleState(db, repositoryId, cliToolId, input) {
+    if (input.state === 'inherit') {
+        db.prepare('DELETE FROM agent_role_repository_defaults WHERE repository_id = ? AND cli_tool_id = ?').run(repositoryId, cliToolId);
+        return;
+    }
+    const roleId = input.state === 'role' ? input.roleId : null;
+    if (roleId !== null)
+        assertRoleExists(db, roleId);
+    db.prepare(`INSERT INTO agent_role_repository_defaults (repository_id, cli_tool_id, role_id, updated_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(repository_id, cli_tool_id) DO UPDATE SET role_id = excluded.role_id, updated_at = excluded.updated_at`).run(repositoryId, cliToolId, roleId, Date.now());
+}
+function getInstanceRoleState(db, worktreeId, instanceId) {
+    const row = db
+        .prepare(`SELECT i.role_id, r.name AS role_name
+       FROM agent_instance_roles i LEFT JOIN agent_roles r ON r.id = i.role_id
+       WHERE i.worktree_id = ? AND i.instance_id = ?`)
+        .get(worktreeId, instanceId);
+    return toStoredState(row);
+}
+/**
+ * Whether the target may hold a setting is for the caller to decide
+ * (`agent-roles/management.ts`): this writes what it is told.
+ *
+ * @throws {AgentRoleNotFoundError}
+ */
+function setInstanceRoleState(db, worktreeId, instanceId, input) {
+    if (input.state === 'inherit') {
+        db.prepare('DELETE FROM agent_instance_roles WHERE worktree_id = ? AND instance_id = ?').run(worktreeId, instanceId);
+        return;
+    }
+    const roleId = input.state === 'role' ? input.roleId : null;
+    if (roleId !== null)
+        assertRoleExists(db, roleId);
+    db.prepare(`INSERT INTO agent_instance_roles (worktree_id, instance_id, role_id, updated_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(worktree_id, instance_id) DO UPDATE SET role_id = excluded.role_id, updated_at = excluded.updated_at`).run(worktreeId, instanceId, roleId, Date.now());
+}
+/**
+ * Whether any level holds a setting. With none, every instance of every tool
+ * resolves to no role, so a launch need not run git to find that out (#4115).
+ */
+function hasAnyRoleSetting(db) {
+    const row = db
+        .prepare(`SELECT (EXISTS (SELECT 1 FROM agent_instance_roles)
+            OR EXISTS (SELECT 1 FROM agent_role_repository_defaults)
+            OR EXISTS (SELECT 1 FROM agent_role_system_defaults)) AS present`)
+        .get();
+    return row?.present === 1;
+}
+// ---------------------------------------------------------------------------
+// Creation keys (#4132, migration v65)
+// ---------------------------------------------------------------------------
+/** How long a key is remembered. A request's deadline is seconds, so a late one is well inside it. */
+exports.INSTANCE_CREATION_KEY_TTL_MS = 24 * 60 * 60 * 1000;
+function getInstanceCreationKey(db, worktreeId, key) {
+    const row = db
+        .prepare(`SELECT instance_id, request_fingerprint FROM agent_instance_creation_keys
+       WHERE worktree_id = ? AND idempotency_key = ?`)
+        .get(worktreeId, key);
+    return row ? { instanceId: row.instance_id, requestFingerprint: row.request_fingerprint } : null;
+}
+function writeInstanceCreationKey(db, worktreeId, key, record) {
+    const now = Date.now();
+    db.prepare('DELETE FROM agent_instance_creation_keys WHERE created_at < ?').run(now - exports.INSTANCE_CREATION_KEY_TTL_MS);
+    db.prepare(`INSERT INTO agent_instance_creation_keys (worktree_id, idempotency_key, instance_id, request_fingerprint, created_at)
+     VALUES (?, ?, ?, ?, ?)`).run(worktreeId, key, record.instanceId, record.requestFingerprint, now);
+}
+/** Written in the transaction that creates the row, so one never exists without the other. */
+function recordInstanceCreationKey(db, worktreeId, key, instanceId, requestFingerprint) {
+    writeInstanceCreationKey(db, worktreeId, key, { instanceId, requestFingerprint });
+}
+/**
+ * What a key came to. One that has made nothing is marked given up on here, so a request
+ * still on its way with it makes nothing either: the answer holds from now on.
+ *
+ * @returns The instance it made, or null when it made none and never will
+ */
+function settleInstanceCreationKey(db, worktreeId, key) {
+    return db.transaction(() => {
+        const existing = getInstanceCreationKey(db, worktreeId, key);
+        if (existing)
+            return existing.instanceId;
+        writeInstanceCreationKey(db, worktreeId, key, { instanceId: null, requestFingerprint: null });
+        return null;
+    })();
+}
+function mapLaunchRecord(row) {
+    return {
+        id: row.id,
+        worktreeId: row.worktree_id,
+        instanceId: row.instance_id,
+        cliToolId: row.cli_tool_id,
+        phase: row.phase,
+        sessionGeneration: row.session_generation,
+        source: row.source,
+        repositoryId: row.repository_id,
+        roleId: row.role_id,
+        roleName: row.role_name,
+        bodyVersion: row.body_version,
+        bodyFingerprint: row.body_fingerprint,
+        injectionFingerprint: row.injection_fingerprint,
+        artifactFingerprint: row.artifact_fingerprint,
+        adapterId: row.adapter_id,
+        adapterVersion: row.adapter_version,
+        wrapperVersion: row.wrapper_version,
+        artifactPath: row.artifact_path,
+        effectiveAgent: row.effective_agent,
+        compositionSourceFingerprint: row.composition_source_fingerprint,
+        noRoleReason: row.no_role_reason,
+        recordedAt: row.recorded_at,
+    };
+}
+/**
+ * Add one line of evidence. There is no function that changes one.
+ *
+ * @throws When this generation already has a record of this phase
+ */
+function recordRoleLaunch(db, record) {
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare(`INSERT INTO agent_role_launch_records (
+       id, worktree_id, instance_id, cli_tool_id, phase, session_generation, source,
+       repository_id, role_id, role_name, body_version, body_fingerprint,
+       injection_fingerprint, artifact_fingerprint, adapter_id, adapter_version,
+       wrapper_version, artifact_path, effective_agent, composition_source_fingerprint,
+       no_role_reason, recorded_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, record.worktreeId, record.instanceId, record.cliToolId, record.phase, record.sessionGeneration, record.source, record.repositoryId, record.roleId, record.roleName, record.bodyVersion, record.bodyFingerprint, record.injectionFingerprint, record.artifactFingerprint, record.adapterId, record.adapterVersion, record.wrapperVersion, record.artifactPath, record.effectiveAgent, record.compositionSourceFingerprint, record.noRoleReason, Date.now());
+    return id;
+}
+/** The latest record of each phase for one instance. Ties on the clock go to the later insert. */
+function getLatestRoleLaunchRecords(db, worktreeId, instanceId) {
+    const latest = (phase) => {
+        const row = db
+            .prepare(`SELECT * FROM agent_role_launch_records
+         WHERE worktree_id = ? AND instance_id = ? AND phase = ?
+         ORDER BY recorded_at DESC, rowid DESC LIMIT 1`)
+            .get(worktreeId, instanceId, phase);
+        return row ? mapLaunchRecord(row) : null;
+    };
+    return { requested: latest('requested'), launched: latest('launched') };
+}

package/dist/server/src/lib/db/agent-session-cost-sampler.js

@@ -41,6 +41,7 @@ exports.stopAgentSessionCostSampler = stopAgentSessionCostSampler;
 const agent_session_telemetry_1 = require("../../lib/hooks/agent-session-telemetry");
 const types_1 = require("../../lib/cli-tools/types");
 const logger_1 = require("../../lib/logger");
+const test_run_detection_1 = require("../../lib/test-run-detection");
 const agent_session_cost_db_1 = require("./agent-session-cost-db");
 const logger = (0, logger_1.createLogger)('agent-session-cost-sampler');
 /**
@@ -160,7 +161,7 @@ function sampleAgentSessionCosts(db, now = Date.now()) {
  * needing to know which kind of process it is in.
  *
  * The timer is `unref()`d so it never keeps Node alive, and skipped outright
- * under Vitest: a suite that opens a database should not acquire a background
+ * in a test run ({@link isUnderTest}): a suite that opens a database should not acquire a background
  * writer to a file it is about to delete.
  *
  * @param db - Database instance to write into
@@ -169,7 +170,7 @@ function sampleAgentSessionCosts(db, now = Date.now()) {
 function startAgentSessionCostSampler(db) {
     if (globalThis.__agentSessionCostSampler)
         return false;
-    if (process.env.VITEST || process.env.NODE_ENV === 'test')
+    if ((0, test_run_detection_1.isUnderTest)())
         return false;
     const timer = setInterval(() => {
         try {

package/dist/server/src/lib/db/db-instance.js

@@ -10,8 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TEST_DB_ROOT_ENV = void 0;
-exports.isInsideVitestWorker = isInsideVitestWorker;
+exports.TEST_DB_ROOT_ENV = exports.isInsideVitestWorker = void 0;
 exports.assertTestDatabasePathIsolated = assertTestDatabasePathIsolated;
 exports.getDbInstance = getDbInstance;
 exports.closeDbInstance = closeDbInstance;
@@ -21,6 +20,8 @@ const abi_recovery_1 = require("./abi-recovery");
 const agent_session_cost_sampler_1 = require("./agent-session-cost-sampler");
 const env_1 = require("../../lib/env");
 const system_directories_1 = require("../../config/system-directories");
+const test_run_detection_1 = require("../../lib/test-run-detection");
+Object.defineProperty(exports, "isInsideVitestWorker", { enumerable: true, get: function () { return test_run_detection_1.isInsideVitestWorker; } });
 let dbInstance = null;
 /**
  * `fs` / `os` are required lazily, as getDbInstance() always did for `fs`: a
@@ -35,36 +36,6 @@ function nodeTmpdir() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return require('os').tmpdir();
 }
-/**
- * Issue #4086: is this code running inside a Vitest worker?
- *
- * Read off the worker state Vitest itself installs on `globalThis` (its
- * `getWorkerState()` reads the same `__vitest_worker__` global, in the forks
- * and threads pools alike), not off environment variables: the environment is
- * both inherited and editable. A test may swap `NODE_ENV` to `production`
- * mid-run (tests/unit/pwa/ServiceWorkerRegistrar.test.tsx does) and must stay
- * guarded, while a child process started outside Vitest inherits `VITEST` and
- * must not be taken for a test run.
- */
-function isInsideVitestWorker() {
-    const state = globalThis.__vitest_worker__;
-    return typeof state === 'object' && state !== null;
-}
-/**
- * Issue #4086: is this a test run (the guard's on-switch)?
- *
- * Inside a Vitest worker: always, whatever `NODE_ENV` says right now.
- * Outside one: only with `NODE_ENV=test` (a test's own child process, which
- * also inherits the per-process CM_DB_PATH). `VITEST` alone never counts —
- * the daemon spreads `process.env` into the server it starts
- * (src/cli/utils/daemon.ts buildChildEnv), so a `NODE_ENV=production` server
- * started from a shell where `VITEST` was left behind opens its real database.
- */
-function isUnderTest(env, inVitestWorker) {
-    if (inVitestWorker)
-        return true;
-    return (env.NODE_ENV ?? '').trim() === 'test';
-}
 /** realpath of the nearest existing ancestor, with the missing tail re-joined. */
 function physicalPath(target) {
     const fs = nodeFs();
@@ -101,8 +72,7 @@ exports.TEST_DB_ROOT_ENV = 'CM_TEST_DB_ROOT';
  * databases tests/setup.ts hands out — not under the temp dir, because
  * `validateDbPath` rejects /tmp and /var, where every OS temp dir lives). Not
  * only the one setup path, so tests that name their own database keep working.
- * Active inside a Vitest worker (even while a test has swapped `NODE_ENV`) and
- * in a process with `NODE_ENV=test`; a no-op otherwise, so a real server is
+ * Active when {@link isUnderTest} says so; a no-op otherwise, so a real server is
  * never affected — including one that inherited `VITEST` but runs with
  * `NODE_ENV=production`.
  *
@@ -110,8 +80,8 @@ exports.TEST_DB_ROOT_ENV = 'CM_TEST_DB_ROOT';
  *   passes `false` to ask how a process outside Vitest would be judged
  * @throws Error when under test and `dbPath` is in neither directory
  */
-function assertTestDatabasePathIsolated(dbPath, env = process.env, tmpRoot = nodeTmpdir(), inVitestWorker = isInsideVitestWorker()) {
-    if (!isUnderTest(env, inVitestWorker))
+function assertTestDatabasePathIsolated(dbPath, env = process.env, tmpRoot = nodeTmpdir(), inVitestWorker = (0, test_run_detection_1.isInsideVitestWorker)()) {
+    if (!(0, test_run_detection_1.isUnderTest)(env, inVitestWorker))
         return;
     const resolved = path_1.default.resolve(dbPath);
     const roots = [tmpRoot, env[exports.TEST_DB_ROOT_ENV]]
@@ -179,7 +149,7 @@ function getDbInstance() {
             throw error;
         }
         dbInstance = db;
-        if (isUnderTest(process.env, isInsideVitestWorker())) {
+        if ((0, test_run_detection_1.isUnderTest)()) {
             (globalThis.__commandmateTestDbClosers ??= new Set()).add(closeDbInstance);
         }
         // Issue #2044: the agent cost ledger needs somebody to copy the in-memory

package/dist/server/src/lib/db/migrations/index.js

@@ -47,6 +47,8 @@ const v60_session_relays_1 = require("./v60-session-relays");
 const v61_session_notes_1 = require("./v61-session-notes");
 const v62_session_relays_bind_1 = require("./v62-session-relays-bind");
 const v63_session_relays_delivery_attempt_1 = require("./v63-session-relays-delivery-attempt");
+const v64_agent_roles_1 = require("./v64-agent-roles");
+const v65_agent_instance_creation_keys_1 = require("./v65-agent-instance-creation-keys");
 /**
  * Complete ordered list of all migrations.
  * Used internally by the barrel file (db-migrations.ts); NOT exported from the barrel (DR2-004).
@@ -97,4 +99,6 @@ exports.migrations = [
     ...v61_session_notes_1.v61_migrations,
     ...v62_session_relays_bind_1.v62_migrations,
     ...v63_session_relays_delivery_attempt_1.v63_migrations,
+    ...v64_agent_roles_1.v64_migrations,
+    ...v65_agent_instance_creation_keys_1.v65_migrations,
 ];

package/dist/server/src/lib/db/migrations/runner.js

@@ -18,7 +18,7 @@ const pre_migration_backup_1 = require("./pre-migration-backup");
  * Current schema version
  * Increment this when adding new migrations
  */
-exports.CURRENT_SCHEMA_VERSION = 63;
+exports.CURRENT_SCHEMA_VERSION = 65;
 /**
  * Get current schema version from database
  */

package/dist/server/src/lib/db/migrations/v64-agent-roles.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Migration v64: roles (Epic #4112, Issue #4114).
+ *
+ * ## The three states of a setting
+ *
+ * A level holds a role, an explicit "no role", or nothing, in which case the next
+ * level decides. No row is "nothing" and a NULL `role_id` is the explicit none.
+ * The system level has no explicit none (`role_id NOT NULL`): it is the last level.
+ *
+ * ## Why no reference to `agent_roles` is `ON DELETE SET NULL`
+ *
+ * NULL means "explicitly none", so a deleted role would quietly become a decision
+ * nobody made. They are `RESTRICT`, and `deleteAgentRole` with `force` removes the
+ * rows in one transaction, which reads as "inherit".
+ *
+ * ## Why `agent_instance_roles` is its own table
+ *
+ * `setAgentInstances` deletes and re-inserts every roster row, so a column on
+ * `agent_instances` would be wiped by each rename and reorder (the same reason as
+ * v59). It has no foreign key to `agent_instances` for the same reason: the
+ * replace would cascade into it. `pruneAgentInstanceRoles` removes the ids that
+ * really left. `worktree_id` follows the convention `getWorktreeChildTables()`
+ * looks for, so a row follows a worktree id rename and goes with its worktree.
+ *
+ * ## The launch record
+ *
+ * A snapshot of what was resolved, kept as evidence, so `repository_id` and
+ * `role_id` are deliberately not foreign keys: a deleted role or repository
+ * must neither take the evidence along nor block a `force` delete. There is no
+ * body and no secret column. Nothing updates a row, but there is deliberately no
+ * `RAISE(ABORT)` trigger enforcing that: `getWriteGuardedTables` reads one as
+ * "append-only ledger" and the row would no longer follow a worktree id rename.
+ *
+ * The rollback drops the five tables, which is the whole of what this adds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v64_migrations = exports.V64_AGENT_ROLE_TABLES = void 0;
+/** In dependency order. The rollback drops them from the end. */
+exports.V64_AGENT_ROLE_TABLES = [
+    'agent_roles',
+    'agent_role_system_defaults',
+    'agent_role_repository_defaults',
+    'agent_instance_roles',
+    'agent_role_launch_records',
+];
+exports.v64_migrations = [
+    {
+        version: 64,
+        name: 'agent-roles',
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE agent_roles (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL COLLATE NOCASE UNIQUE,
+          body TEXT NOT NULL,
+          body_version INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+
+        CREATE TABLE agent_role_system_defaults (
+          cli_tool_id TEXT PRIMARY KEY,
+          role_id TEXT NOT NULL REFERENCES agent_roles(id) ON DELETE RESTRICT,
+          updated_at INTEGER NOT NULL
+        );
+
+        CREATE TABLE agent_role_repository_defaults (
+          repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+          cli_tool_id TEXT NOT NULL,
+          role_id TEXT REFERENCES agent_roles(id) ON DELETE RESTRICT,
+          updated_at INTEGER NOT NULL,
+          PRIMARY KEY (repository_id, cli_tool_id)
+        );
+
+        CREATE TABLE agent_instance_roles (
+          worktree_id TEXT NOT NULL REFERENCES worktrees(id) ON DELETE CASCADE,
+          instance_id TEXT NOT NULL,
+          role_id TEXT REFERENCES agent_roles(id) ON DELETE RESTRICT,
+          updated_at INTEGER NOT NULL,
+          PRIMARY KEY (worktree_id, instance_id)
+        );
+
+        CREATE TABLE agent_role_launch_records (
+          id TEXT PRIMARY KEY,
+          worktree_id TEXT NOT NULL REFERENCES worktrees(id) ON DELETE CASCADE,
+          instance_id TEXT NOT NULL,
+          cli_tool_id TEXT NOT NULL,
+          phase TEXT NOT NULL CHECK (phase IN ('requested','launched')),
+          session_generation TEXT NOT NULL,
+          source TEXT NOT NULL,
+          repository_id TEXT,
+          role_id TEXT,
+          role_name TEXT,
+          body_version INTEGER,
+          body_fingerprint TEXT,
+          injection_fingerprint TEXT,
+          artifact_fingerprint TEXT,
+          adapter_id TEXT,
+          adapter_version TEXT,
+          wrapper_version TEXT,
+          artifact_path TEXT,
+          effective_agent TEXT,
+          composition_source_fingerprint TEXT,
+          no_role_reason TEXT,
+          recorded_at INTEGER NOT NULL,
+          UNIQUE (worktree_id, instance_id, session_generation, phase)
+        );
+
+        CREATE INDEX idx_agent_role_repository_defaults_role ON agent_role_repository_defaults(role_id);
+        CREATE INDEX idx_agent_instance_roles_role ON agent_instance_roles(role_id);
+        CREATE INDEX idx_agent_role_system_defaults_role ON agent_role_system_defaults(role_id);
+        CREATE INDEX idx_agent_role_launch_records_latest
+          ON agent_role_launch_records(worktree_id, instance_id, phase, recorded_at);
+      `);
+        },
+        down: (db) => {
+            for (const table of [...exports.V64_AGENT_ROLE_TABLES].reverse()) {
+                db.exec(`DROP TABLE IF EXISTS ${table}`);
+            }
+        },
+    },
+];