switchman-dev 0.1.5 → 0.1.7

package/src/core/db.js

@@ -5,12 +5,16 @@
 
 import { createHash, createHmac, randomBytes } from 'node:crypto';
 import { DatabaseSync } from 'node:sqlite';
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs';
-import { join, resolve } from 'path';
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
+import { join, posix, resolve } from 'path';
+import { matchesPathPatterns } from './ignore.js';
+import { buildModuleDependencyIndexForPath, buildSemanticIndexForPath, classifySubsystemsForPath, listTrackedFiles } from './semantic.js';
 
 const SWITCHMAN_DIR = '.switchman';
 const DB_FILE = 'switchman.db';
 const AUDIT_KEY_FILE = 'audit.key';
+const MIGRATION_STATE_FILE = 'migration-state.json';
+const CURRENT_SCHEMA_VERSION = 5;
 
 // How long (ms) a writer will wait for a lock before giving up.
 // 5 seconds is generous for a CLI tool with 3-10 concurrent agents.
@@ -50,6 +54,22 @@ function normalizeWorktreePath(path) {
   }
 }
 
+function normalizeClaimedFilePath(filePath) {
+  const rawPath = String(filePath || '').replace(/\\/g, '/').trim();
+  const normalized = posix.normalize(rawPath.replace(/^\.\/+/, ''));
+  if (
+    normalized === '' ||
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../') ||
+    rawPath.startsWith('/') ||
+    /^[A-Za-z]:\//.test(rawPath)
+  ) {
+    throw new Error('Claimed file paths must stay inside the repository.');
+  }
+  return normalized;
+}
+
 function makeId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -72,6 +92,39 @@ function getTableColumns(db, tableName) {
   return db.prepare(`PRAGMA table_info(${tableName})`).all().map((column) => column.name);
 }
 
+function getSchemaVersion(db) {
+  return Number(db.prepare('PRAGMA user_version').get()?.user_version || 0);
+}
+
+function setSchemaVersion(db, version) {
+  db.exec(`PRAGMA user_version=${Number(version) || 0}`);
+}
+
+function getMigrationStatePath(repoRoot) {
+  return join(getSwitchmanDir(repoRoot), MIGRATION_STATE_FILE);
+}
+
+function readMigrationState(repoRoot) {
+  const path = getMigrationStatePath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error(`Switchman migration state is unreadable at ${path}. Remove or repair it before reopening the database.`);
+  }
+}
+
+function writeMigrationState(repoRoot, state) {
+  writeFileSync(getMigrationStatePath(repoRoot), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function clearMigrationState(repoRoot) {
+  const path = getMigrationStatePath(repoRoot);
+  if (existsSync(path)) {
+    rmSync(path, { force: true });
+  }
+}
+
 function getAuditSecret(repoRoot) {
   const keyPath = join(getSwitchmanDir(repoRoot), AUDIT_KEY_FILE);
   if (!existsSync(keyPath)) {
@@ -120,7 +173,7 @@ function signAuditEntry(secret, entryHash) {
   return createHmac('sha256', secret).update(entryHash).digest('hex');
 }
 
-function ensureSchema(db) {
+function applySchemaVersion1(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS tasks (
       id           TEXT PRIMARY KEY,
@@ -292,6 +345,8 @@ function ensureSchema(db) {
       created_at         TEXT NOT NULL DEFAULT (datetime('now')),
       updated_at         TEXT NOT NULL DEFAULT (datetime('now')),
       last_attempt_at    TEXT,
+      backoff_until      TEXT,
+      escalated_at       TEXT,
       started_at         TEXT,
       finished_at        TEXT
     );
@@ -376,11 +431,162 @@ function ensureSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_merge_queue_pipeline_id ON merge_queue(source_pipeline_id);
     CREATE INDEX IF NOT EXISTS idx_merge_queue_events_item ON merge_queue_events(queue_item_id);
   `);
+}
+
+function applySchemaVersion2(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS operation_journal (
+      id             TEXT PRIMARY KEY,
+      scope_type     TEXT NOT NULL,
+      scope_id       TEXT NOT NULL,
+      operation_type TEXT NOT NULL,
+      status         TEXT NOT NULL DEFAULT 'running',
+      details        TEXT,
+      started_at     TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at     TEXT NOT NULL DEFAULT (datetime('now')),
+      finished_at    TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_operation_journal_scope
+      ON operation_journal(scope_type, scope_id, started_at);
+    CREATE INDEX IF NOT EXISTS idx_operation_journal_status
+      ON operation_journal(status, started_at);
+  `);
 
   migrateLegacyAuditLog(db);
   migrateLegacyActiveTasks(db);
 }
 
+function applySchemaVersion3(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS temp_resources (
+      id            TEXT PRIMARY KEY,
+      scope_type    TEXT NOT NULL,
+      scope_id      TEXT NOT NULL,
+      operation_id  TEXT,
+      resource_type TEXT NOT NULL,
+      path          TEXT NOT NULL,
+      branch        TEXT,
+      status        TEXT NOT NULL DEFAULT 'active',
+      details       TEXT,
+      created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      released_at   TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_temp_resources_scope
+      ON temp_resources(scope_type, scope_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_temp_resources_status
+      ON temp_resources(status, created_at);
+    CREATE INDEX IF NOT EXISTS idx_temp_resources_path
+      ON temp_resources(path);
+    CREATE INDEX IF NOT EXISTS idx_temp_resources_operation
+      ON temp_resources(operation_id);
+  `);
+}
+
+function applySchemaVersion4(db) {
+  const mergeQueueColumns = getTableColumns(db, 'merge_queue');
+  if (mergeQueueColumns.length > 0 && !mergeQueueColumns.includes('backoff_until')) {
+    db.exec(`ALTER TABLE merge_queue ADD COLUMN backoff_until TEXT`);
+  }
+  if (mergeQueueColumns.length > 0 && !mergeQueueColumns.includes('escalated_at')) {
+    db.exec(`ALTER TABLE merge_queue ADD COLUMN escalated_at TEXT`);
+  }
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_merge_queue_backoff_until ON merge_queue(backoff_until);
+    CREATE INDEX IF NOT EXISTS idx_merge_queue_escalated_at ON merge_queue(escalated_at);
+  `);
+}
+
+function applySchemaVersion5(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS policy_overrides (
+      id                TEXT PRIMARY KEY,
+      pipeline_id       TEXT NOT NULL,
+      requirement_keys  TEXT NOT NULL DEFAULT '[]',
+      task_types        TEXT NOT NULL DEFAULT '[]',
+      status            TEXT NOT NULL DEFAULT 'active',
+      reason            TEXT NOT NULL,
+      approved_by       TEXT,
+      details           TEXT,
+      created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+      revoked_at        TEXT,
+      revoked_by        TEXT,
+      revoked_reason    TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_policy_overrides_pipeline
+      ON policy_overrides(pipeline_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_policy_overrides_status
+      ON policy_overrides(status, created_at);
+  `);
+}
+
+function ensureSchemaMigrated(db) {
+  const repoRoot = db.__switchmanRepoRoot;
+  if (!repoRoot) {
+    throw new Error('Database repo root is not configured.');
+  }
+
+  const recordedState = readMigrationState(repoRoot);
+  const currentVersion = getSchemaVersion(db);
+
+  if (currentVersion > CURRENT_SCHEMA_VERSION) {
+    throw new Error(`Switchman database schema version ${currentVersion} is newer than this CLI supports (${CURRENT_SCHEMA_VERSION}). Upgrade Switchman before opening this repo.`);
+  }
+
+  if (recordedState?.status === 'running') {
+    throw new Error(`Switchman detected an interrupted database migration from version ${recordedState.from_version} to ${recordedState.to_version}. Resolve the migration state in ${getMigrationStatePath(repoRoot)} before reopening the database.`);
+  }
+
+  if (currentVersion === CURRENT_SCHEMA_VERSION) {
+    if (recordedState) {
+      clearMigrationState(repoRoot);
+    }
+    return;
+  }
+
+  writeMigrationState(repoRoot, {
+    status: 'running',
+    from_version: currentVersion,
+    to_version: CURRENT_SCHEMA_VERSION,
+    started_at: new Date().toISOString(),
+  });
+
+  try {
+    withImmediateTransaction(db, () => {
+      if (currentVersion < 1) {
+        applySchemaVersion1(db);
+      }
+      if (currentVersion < 2) {
+        applySchemaVersion2(db);
+      }
+      if (currentVersion < 3) {
+        applySchemaVersion3(db);
+      }
+      if (currentVersion < 4) {
+        applySchemaVersion4(db);
+      }
+      if (currentVersion < 5) {
+        applySchemaVersion5(db);
+      }
+      setSchemaVersion(db, CURRENT_SCHEMA_VERSION);
+    });
+    clearMigrationState(repoRoot);
+  } catch (err) {
+    writeMigrationState(repoRoot, {
+      status: 'failed',
+      from_version: currentVersion,
+      to_version: CURRENT_SCHEMA_VERSION,
+      failed_at: new Date().toISOString(),
+      error: String(err?.message || err),
+    });
+    throw err;
+  }
+}
+
 function normalizeScopeRoot(pattern) {
   return String(pattern || '')
     .replace(/\\/g, '/')
@@ -426,6 +632,84 @@ function buildSpecOverlap(sourceSpec = null, affectedSpec = null) {
   };
 }
 
+function taskSpecMatchesObject(taskSpec = null, object = null) {
+  if (!taskSpec || !object) return false;
+  const allowedPaths = Array.isArray(taskSpec.allowed_paths) ? taskSpec.allowed_paths.filter(Boolean) : [];
+  if (allowedPaths.length > 0 && matchesPathPatterns(object.file_path, allowedPaths)) {
+    return true;
+  }
+
+  const subsystemTags = Array.isArray(taskSpec.subsystem_tags) ? taskSpec.subsystem_tags.filter(Boolean) : [];
+  return subsystemTags.some((tag) => (object.subsystem_tags || []).includes(tag));
+}
+
+function taskSpecMatchesFilePath(taskSpec = null, filePath = null) {
+  if (!taskSpec || !filePath) return false;
+  const allowedPaths = Array.isArray(taskSpec.allowed_paths) ? taskSpec.allowed_paths.filter(Boolean) : [];
+  if (allowedPaths.length > 0 && matchesPathPatterns(filePath, allowedPaths)) {
+    return true;
+  }
+
+  const subsystemTags = Array.isArray(taskSpec.subsystem_tags) ? taskSpec.subsystem_tags.filter(Boolean) : [];
+  const fileSubsystems = classifySubsystemsForPath(filePath);
+  return subsystemTags.some((tag) => fileSubsystems.includes(tag));
+}
+
+function buildSemanticDependencyOverlap(db, sourceSpec, affectedSpec, changedFiles = []) {
+  const repoRoot = db.__switchmanRepoRoot;
+  if (!repoRoot || !sourceSpec || !affectedSpec || changedFiles.length === 0) {
+    return [];
+  }
+
+  const changedObjects = buildSemanticIndexForPath(repoRoot, changedFiles).objects || [];
+  const sourceObjects = changedObjects.filter((object) =>
+    changedFiles.includes(object.file_path)
+    && taskSpecMatchesObject(sourceSpec, object),
+  );
+  const trackedSourceFiles = listTrackedFiles(repoRoot, { sourceOnly: true });
+  const semanticCandidateFiles = [...new Set([...trackedSourceFiles, ...changedFiles])];
+  const affectedObjects = buildSemanticIndexForPath(repoRoot, semanticCandidateFiles).objects
+    .filter((object) => taskSpecMatchesObject(affectedSpec, object));
+  const affectedKeys = new Set(affectedObjects.map((object) => `${object.kind}:${object.name}`));
+  const overlaps = sourceObjects
+    .filter((object) => affectedKeys.has(`${object.kind}:${object.name}`))
+    .map((object) => ({
+      overlap_type: ['interface', 'type'].includes(object.kind) ? 'contract' : 'exported_object',
+      kind: object.kind,
+      name: object.name,
+      file_path: object.file_path,
+      area: object.area || null,
+    }));
+
+  const sourceChangedFiles = changedFiles.filter((filePath) => taskSpecMatchesFilePath(sourceSpec, filePath));
+  if (sourceChangedFiles.length === 0) return overlaps;
+
+  const moduleDependencies = buildModuleDependencyIndexForPath(repoRoot, { filePaths: semanticCandidateFiles }).dependencies || [];
+  const sharedModuleDependents = moduleDependencies.filter((dependency) =>
+    sourceChangedFiles.includes(dependency.imported_path)
+    && taskSpecMatchesFilePath(affectedSpec, dependency.file_path)
+    && !sourceChangedFiles.includes(dependency.file_path)
+  );
+  const dependentFiles = [...new Set(sharedModuleDependents.map((item) => item.file_path))];
+  const sharedModulePaths = [...new Set(sharedModuleDependents.map((item) => item.imported_path))];
+
+  if (dependentFiles.length > 0) {
+    overlaps.push({
+      overlap_type: 'shared_module',
+      kind: 'module',
+      name: sharedModulePaths[0],
+      file_path: sharedModulePaths[0],
+      area: sharedModuleDependents[0]?.area || null,
+      dependent_files: dependentFiles,
+      module_paths: sharedModulePaths,
+      subsystem_tags: [...new Set(sharedModuleDependents.flatMap((item) => item.subsystem_tags || []))],
+      dependent_areas: [...new Set(sharedModuleDependents.map((item) => item.area).filter(Boolean))],
+    });
+  }
+
+  return overlaps;
+}
+
 function buildLeaseScopeReservations(lease, taskSpec) {
   if (!taskSpec) return [];
 
@@ -890,7 +1174,7 @@ function resolveDependencyInvalidationsForAffectedTaskTx(db, affectedTaskId, res
   `).run(resolvedBy || null, resolvedBy || null, affectedTaskId);
 }
 
-function syncDependencyInvalidationsForLeaseTx(db, leaseId, source = 'write') {
+function syncDependencyInvalidationsForLeaseTx(db, leaseId, source = 'write', context = {}) {
   const execution = getLeaseExecutionContext(db, leaseId);
   if (!execution?.task || !execution.task_spec) {
     return [];
@@ -912,7 +1196,8 @@ function syncDependencyInvalidationsForLeaseTx(db, leaseId, source = 'write') {
     if ((affectedSpec.pipeline_id || null) === sourcePipelineId) continue;
 
     const overlap = buildSpecOverlap(sourceSpec, affectedSpec);
-    if (overlap.shared_subsystems.length === 0 && overlap.shared_scopes.length === 0) continue;
+    const semanticOverlap = buildSemanticDependencyOverlap(db, sourceSpec, affectedSpec, context.changed_files || []);
+    if (overlap.shared_subsystems.length === 0 && overlap.shared_scopes.length === 0 && semanticOverlap.length === 0) continue;
 
     const affectedWorktree = affectedTask.worktree || null;
     for (const subsystemTag of overlap.shared_subsystems) {
@@ -933,6 +1218,8 @@ function syncDependencyInvalidationsForLeaseTx(db, leaseId, source = 'write') {
           source,
           source_task_title: sourceTask.title,
           affected_task_title: affectedTask.title,
+          source_task_priority: Number(sourceTask.priority || 0),
+          affected_task_priority: Number(affectedTask.priority || 0),
         },
       });
     }
@@ -955,6 +1242,100 @@ function syncDependencyInvalidationsForLeaseTx(db, leaseId, source = 'write') {
           source,
           source_task_title: sourceTask.title,
           affected_task_title: affectedTask.title,
+          source_task_priority: Number(sourceTask.priority || 0),
+          affected_task_priority: Number(affectedTask.priority || 0),
+        },
+      });
+    }
+
+    const semanticContractOverlap = semanticOverlap.filter((item) => item.overlap_type === 'contract');
+    const semanticObjectOverlap = semanticOverlap.filter((item) => item.overlap_type === 'exported_object');
+    const sharedModuleOverlap = semanticOverlap.filter((item) => item.overlap_type === 'shared_module');
+
+    if (semanticContractOverlap.length > 0) {
+      desired.push({
+        source_lease_id: leaseId,
+        source_task_id: sourceTask.id,
+        source_pipeline_id: sourcePipelineId,
+        source_worktree: sourceWorktree,
+        affected_task_id: affectedTask.id,
+        affected_pipeline_id: affectedSpec.pipeline_id || null,
+        affected_worktree: affectedWorktree,
+        status: 'stale',
+        reason_type: 'semantic_contract_drift',
+        subsystem_tag: null,
+        source_scope_pattern: null,
+        affected_scope_pattern: null,
+        details: {
+          source,
+          source_task_title: sourceTask.title,
+          affected_task_title: affectedTask.title,
+          source_task_priority: Number(sourceTask.priority || 0),
+          affected_task_priority: Number(affectedTask.priority || 0),
+          contract_names: [...new Set(semanticContractOverlap.map((item) => item.name))],
+          contract_kinds: [...new Set(semanticContractOverlap.map((item) => item.kind))],
+          contract_files: [...new Set(semanticContractOverlap.map((item) => item.file_path))],
+          revalidation_set: 'contract',
+          severity: 'blocked',
+        },
+      });
+    }
+
+    if (semanticObjectOverlap.length > 0) {
+      desired.push({
+        source_lease_id: leaseId,
+        source_task_id: sourceTask.id,
+        source_pipeline_id: sourcePipelineId,
+        source_worktree: sourceWorktree,
+        affected_task_id: affectedTask.id,
+        affected_pipeline_id: affectedSpec.pipeline_id || null,
+        affected_worktree: affectedWorktree,
+        status: 'stale',
+        reason_type: 'semantic_object_overlap',
+        subsystem_tag: null,
+        source_scope_pattern: null,
+        affected_scope_pattern: null,
+        details: {
+          source,
+          source_task_title: sourceTask.title,
+          affected_task_title: affectedTask.title,
+          source_task_priority: Number(sourceTask.priority || 0),
+          affected_task_priority: Number(affectedTask.priority || 0),
+          object_names: [...new Set(semanticObjectOverlap.map((item) => item.name))],
+          object_kinds: [...new Set(semanticObjectOverlap.map((item) => item.kind))],
+          object_files: [...new Set(semanticObjectOverlap.map((item) => item.file_path))],
+          revalidation_set: 'semantic_object',
+          severity: 'warn',
+        },
+      });
+    }
+
+    if (sharedModuleOverlap.length > 0) {
+      desired.push({
+        source_lease_id: leaseId,
+        source_task_id: sourceTask.id,
+        source_pipeline_id: sourcePipelineId,
+        source_worktree: sourceWorktree,
+        affected_task_id: affectedTask.id,
+        affected_pipeline_id: affectedSpec.pipeline_id || null,
+        affected_worktree: affectedWorktree,
+        status: 'stale',
+        reason_type: 'shared_module_drift',
+        subsystem_tag: null,
+        source_scope_pattern: null,
+        affected_scope_pattern: null,
+        details: {
+          source,
+          source_task_title: sourceTask.title,
+          affected_task_title: affectedTask.title,
+          source_task_priority: Number(sourceTask.priority || 0),
+          affected_task_priority: Number(affectedTask.priority || 0),
+          module_paths: [...new Set(sharedModuleOverlap.flatMap((item) => item.module_paths || [item.file_path]).filter(Boolean))],
+          dependent_files: [...new Set(sharedModuleOverlap.flatMap((item) => item.dependent_files || []))],
+          dependent_areas: [...new Set(sharedModuleOverlap.flatMap((item) => item.dependent_areas || []).filter(Boolean))],
+          dependent_subsystems: [...new Set(sharedModuleOverlap.flatMap((item) => item.subsystem_tags || []).filter(Boolean))],
+          revalidation_set: 'shared_module',
+          severity: 'warn',
         },
       });
     }
@@ -1262,7 +1643,7 @@ export function initDb(repoRoot) {
   db.__switchmanRepoRoot = repoRoot;
   db.__switchmanAuditSecret = getAuditSecret(repoRoot);
   configureDb(db, { initialize: true });
-  withBusyRetry(() => ensureSchema(db));
+  withBusyRetry(() => ensureSchemaMigrated(db));
   return db;
 }
 
@@ -1275,7 +1656,7 @@ export function openDb(repoRoot) {
   db.__switchmanRepoRoot = repoRoot;
   db.__switchmanAuditSecret = getAuditSecret(repoRoot);
   configureDb(db);
-  withBusyRetry(() => ensureSchema(db));
+  withBusyRetry(() => ensureSchemaMigrated(db));
   return db;
 }
 
@@ -1422,6 +1803,7 @@ export function enqueueMergeItem(db, {
   targetBranch = 'main',
   maxRetries = 1,
   submittedBy = null,
+  eventDetails = null,
 } = {}) {
   const itemId = id || makeId('mq');
   db.prepare(`
@@ -1450,6 +1832,7 @@ export function enqueueMergeItem(db, {
       source_worktree: sourceWorktree || null,
       source_pipeline_id: sourcePipelineId || null,
       target_branch: targetBranch || 'main',
+      ...(eventDetails || {}),
     }),
   });
 
@@ -1502,10 +1885,350 @@ export function logMergeQueueEvent(db, itemId, {
   `).run(itemId, eventType, status || null, details == null ? null : String(details));
 }
 
+export function listOperationJournal(db, {
+  scopeType = null,
+  scopeId = null,
+  status = null,
+  limit = 50,
+} = {}) {
+  const clauses = [];
+  const params = [];
+  if (scopeType) {
+    clauses.push('scope_type=?');
+    params.push(scopeType);
+  }
+  if (scopeId) {
+    clauses.push('scope_id=?');
+    params.push(scopeId);
+  }
+  if (status) {
+    clauses.push('status=?');
+    params.push(status);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+  return db.prepare(`
+    SELECT *
+    FROM operation_journal
+    ${where}
+    ORDER BY datetime(started_at) DESC, id DESC
+    LIMIT ?
+  `).all(...params, limit);
+}
+
+export function startOperationJournalEntry(db, {
+  id = null,
+  scopeType,
+  scopeId,
+  operationType,
+  details = null,
+} = {}) {
+  const entryId = id || makeId('op');
+  db.prepare(`
+    INSERT INTO operation_journal (id, scope_type, scope_id, operation_type, status, details)
+    VALUES (?, ?, ?, ?, 'running', ?)
+  `).run(entryId, scopeType, scopeId, operationType, details == null ? null : String(details));
+  return db.prepare(`
+    SELECT *
+    FROM operation_journal
+    WHERE id=?
+  `).get(entryId);
+}
+
+export function finishOperationJournalEntry(db, entryId, {
+  status = 'completed',
+  details = null,
+} = {}) {
+  db.prepare(`
+    UPDATE operation_journal
+    SET status=?,
+        details=COALESCE(?, details),
+        updated_at=datetime('now'),
+        finished_at=datetime('now')
+    WHERE id=?
+  `).run(status, details == null ? null : String(details), entryId);
+  return db.prepare(`
+    SELECT *
+    FROM operation_journal
+    WHERE id=?
+  `).get(entryId);
+}
+
+export function listTempResources(db, {
+  scopeType = null,
+  scopeId = null,
+  operationId = null,
+  resourceType = null,
+  status = null,
+  limit = 100,
+} = {}) {
+  const clauses = [];
+  const params = [];
+  if (scopeType) {
+    clauses.push('scope_type=?');
+    params.push(scopeType);
+  }
+  if (scopeId) {
+    clauses.push('scope_id=?');
+    params.push(scopeId);
+  }
+  if (operationId) {
+    clauses.push('operation_id=?');
+    params.push(operationId);
+  }
+  if (resourceType) {
+    clauses.push('resource_type=?');
+    params.push(resourceType);
+  }
+  if (status) {
+    clauses.push('status=?');
+    params.push(status);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+  return db.prepare(`
+    SELECT *
+    FROM temp_resources
+    ${where}
+    ORDER BY datetime(created_at) DESC, id DESC
+    LIMIT ?
+  `).all(...params, limit);
+}
+
+export function getPolicyOverride(db, overrideId) {
+  const entry = db.prepare(`
+    SELECT *
+    FROM policy_overrides
+    WHERE id=?
+  `).get(overrideId);
+  if (!entry) return null;
+  return {
+    ...entry,
+    requirement_keys: (() => {
+      try {
+        return JSON.parse(entry.requirement_keys || '[]');
+      } catch {
+        return [];
+      }
+    })(),
+    task_types: (() => {
+      try {
+        return JSON.parse(entry.task_types || '[]');
+      } catch {
+        return [];
+      }
+    })(),
+    details: (() => {
+      try {
+        return entry.details ? JSON.parse(entry.details) : null;
+      } catch {
+        return null;
+      }
+    })(),
+  };
+}
+
+export function listPolicyOverrides(db, {
+  pipelineId = null,
+  status = null,
+  limit = 100,
+} = {}) {
+  const clauses = [];
+  const params = [];
+  if (pipelineId) {
+    clauses.push('pipeline_id=?');
+    params.push(pipelineId);
+  }
+  if (status) {
+    clauses.push('status=?');
+    params.push(status);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+  return db.prepare(`
+    SELECT *
+    FROM policy_overrides
+    ${where}
+    ORDER BY datetime(created_at) DESC, id DESC
+    LIMIT ?
+  `).all(...params, limit).map((entry) => ({
+    ...entry,
+    requirement_keys: (() => {
+      try {
+        return JSON.parse(entry.requirement_keys || '[]');
+      } catch {
+        return [];
+      }
+    })(),
+    task_types: (() => {
+      try {
+        return JSON.parse(entry.task_types || '[]');
+      } catch {
+        return [];
+      }
+    })(),
+    details: (() => {
+      try {
+        return entry.details ? JSON.parse(entry.details) : null;
+      } catch {
+        return null;
+      }
+    })(),
+  }));
+}
+
+export function createPolicyOverride(db, {
+  pipelineId,
+  requirementKeys = [],
+  taskTypes = [],
+  reason,
+  approvedBy = null,
+  details = null,
+} = {}) {
+  if (!pipelineId) throw new Error('pipelineId is required for a policy override.');
+  if (!reason || !String(reason).trim()) throw new Error('A policy override reason is required.');
+
+  const overrideId = makeId('po');
+  const normalizedRequirementKeys = [...new Set((requirementKeys || []).map((value) => String(value || '').trim()).filter(Boolean))];
+  const normalizedTaskTypes = [...new Set((taskTypes || []).map((value) => String(value || '').trim()).filter(Boolean))];
+
+  return withImmediateTransaction(db, () => {
+    db.prepare(`
+      INSERT INTO policy_overrides (
+        id, pipeline_id, requirement_keys, task_types, status, reason, approved_by, details
+      )
+      VALUES (?, ?, ?, ?, 'active', ?, ?, ?)
+    `).run(
+      overrideId,
+      pipelineId,
+      JSON.stringify(normalizedRequirementKeys),
+      JSON.stringify(normalizedTaskTypes),
+      String(reason).trim(),
+      approvedBy || null,
+      details == null ? null : JSON.stringify(details),
+    );
+    logAuditEventTx(db, {
+      eventType: 'policy_override_created',
+      status: 'warn',
+      reasonCode: 'policy_override',
+      details: JSON.stringify({
+        override_id: overrideId,
+        pipeline_id: pipelineId,
+        requirement_keys: normalizedRequirementKeys,
+        task_types: normalizedTaskTypes,
+        reason: String(reason).trim(),
+        approved_by: approvedBy || null,
+        details: details || null,
+      }),
+    });
+    return getPolicyOverride(db, overrideId);
+  });
+}
+
+export function revokePolicyOverride(db, overrideId, {
+  revokedBy = null,
+  reason = null,
+} = {}) {
+  return withImmediateTransaction(db, () => {
+    const existing = getPolicyOverride(db, overrideId);
+    if (!existing) {
+      throw new Error(`Policy override ${overrideId} does not exist.`);
+    }
+    if (existing.status !== 'active') {
+      return existing;
+    }
+    db.prepare(`
+      UPDATE policy_overrides
+      SET status='revoked',
+          revoked_at=datetime('now'),
+          revoked_by=?,
+          revoked_reason=?
+      WHERE id=?
+    `).run(revokedBy || null, reason || null, overrideId);
+    logAuditEventTx(db, {
+      eventType: 'policy_override_revoked',
+      status: 'info',
+      reasonCode: 'policy_override_revoked',
+      details: JSON.stringify({
+        override_id: overrideId,
+        pipeline_id: existing.pipeline_id,
+        revoked_by: revokedBy || null,
+        revoked_reason: reason || null,
+      }),
+    });
+    return getPolicyOverride(db, overrideId);
+  });
+}
+
+export function createTempResource(db, {
+  id = null,
+  scopeType,
+  scopeId,
+  operationId = null,
+  resourceType,
+  path,
+  branch = null,
+  details = null,
+  status = 'active',
+} = {}) {
+  const resourceId = id || makeId('res');
+  db.prepare(`
+    INSERT INTO temp_resources (
+      id, scope_type, scope_id, operation_id, resource_type, path, branch, status, details
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    resourceId,
+    scopeType,
+    scopeId,
+    operationId || null,
+    resourceType,
+    path,
+    branch || null,
+    status,
+    details == null ? null : String(details),
+  );
+  return db.prepare(`
+    SELECT *
+    FROM temp_resources
+    WHERE id=?
+  `).get(resourceId);
+}
+
+export function updateTempResource(db, resourceId, {
+  status = null,
+  path = null,
+  branch = null,
+  details = null,
+} = {}) {
+  db.prepare(`
+    UPDATE temp_resources
+    SET status=COALESCE(?, status),
+        path=COALESCE(?, path),
+        branch=COALESCE(?, branch),
+        details=COALESCE(?, details),
+        updated_at=datetime('now'),
+        released_at=CASE
+          WHEN COALESCE(?, status) = 'active' THEN NULL
+          ELSE COALESCE(released_at, datetime('now'))
+        END
+    WHERE id=?
+  `).run(
+    status,
+    path,
+    branch,
+    details == null ? null : String(details),
+    status,
+    resourceId,
+  );
+  return db.prepare(`
+    SELECT *
+    FROM temp_resources
+    WHERE id=?
+  `).get(resourceId);
+}
+
 export function startMergeQueueItem(db, itemId) {
   return withImmediateTransaction(db, () => {
     const item = getMergeQueueItem(db, itemId);
-    if (!item || !['queued', 'retrying'].includes(item.status)) {
+    if (!item || !['queued', 'retrying', 'held', 'wave_blocked', 'escalated'].includes(item.status)) {
       return null;
     }
 
@@ -1515,7 +2238,7 @@ export function startMergeQueueItem(db, itemId) {
           started_at=COALESCE(started_at, datetime('now')),
           last_attempt_at=datetime('now'),
           updated_at=datetime('now')
-      WHERE id=? AND status IN ('queued', 'retrying')
+      WHERE id=? AND status IN ('queued', 'retrying', 'held', 'wave_blocked', 'escalated')
     `).run(itemId);
 
     logMergeQueueEvent(db, itemId, {
@@ -1534,6 +2257,7 @@ export function markMergeQueueState(db, itemId, {
   nextAction = null,
   mergedCommit = null,
   incrementRetry = false,
+  backoffUntil = undefined,
 } = {}) {
   const terminal = ['merged', 'blocked', 'failed', 'canceled'].includes(status);
   db.prepare(`
@@ -1544,6 +2268,15 @@ export function markMergeQueueState(db, itemId, {
         next_action=?,
         merged_commit=COALESCE(?, merged_commit),
         retry_count=retry_count + ?,
+        backoff_until=CASE
+          WHEN ? THEN ?
+          WHEN ? = 'retrying' THEN backoff_until
+          ELSE NULL
+        END,
+        escalated_at=CASE
+          WHEN ? = 'escalated' THEN COALESCE(escalated_at, datetime('now'))
+          ELSE NULL
+        END,
         updated_at=datetime('now'),
         finished_at=CASE WHEN ? THEN datetime('now') ELSE finished_at END
     WHERE id=?
@@ -1554,6 +2287,10 @@ export function markMergeQueueState(db, itemId, {
     nextAction || null,
     mergedCommit || null,
     incrementRetry ? 1 : 0,
+    backoffUntil !== undefined ? 1 : 0,
+    backoffUntil || null,
+    status,
+    status,
     terminal ? 1 : 0,
     itemId,
   );
@@ -1575,7 +2312,7 @@ export function markMergeQueueState(db, itemId, {
 
 export function retryMergeQueueItem(db, itemId) {
   const item = getMergeQueueItem(db, itemId);
-  if (!item || !['blocked', 'failed'].includes(item.status)) {
+  if (!item || !['blocked', 'failed', 'held', 'wave_blocked', 'escalated', 'retrying'].includes(item.status)) {
     return null;
   }
 
@@ -1585,6 +2322,8 @@ export function retryMergeQueueItem(db, itemId) {
         last_error_code=NULL,
         last_error_summary=NULL,
         next_action=NULL,
+        backoff_until=NULL,
+        escalated_at=NULL,
         finished_at=NULL,
         updated_at=datetime('now')
     WHERE id=?
@@ -1598,6 +2337,35 @@ export function retryMergeQueueItem(db, itemId) {
   return getMergeQueueItem(db, itemId);
 }
 
+export function escalateMergeQueueItem(db, itemId, {
+  summary = null,
+  nextAction = null,
+} = {}) {
+  const item = getMergeQueueItem(db, itemId);
+  if (!item || ['merged', 'canceled'].includes(item.status)) {
+    return null;
+  }
+
+  const desiredSummary = summary || item.last_error_summary || 'Operator escalation requested before this queue item lands.';
+  const desiredNextAction = nextAction || item.next_action || `Run \`switchman explain queue ${itemId}\` to review the risk, then \`switchman queue retry ${itemId}\` when you are ready to land it again.`;
+
+  if (
+    item.status === 'escalated'
+    && (item.last_error_summary || null) === desiredSummary
+    && (item.next_action || null) === desiredNextAction
+  ) {
+    return item;
+  }
+
+  return markMergeQueueState(db, itemId, {
+    status: 'escalated',
+    lastErrorCode: 'queue_escalated_manual',
+    lastErrorSummary: desiredSummary,
+    nextAction: desiredNextAction,
+    backoffUntil: null,
+  });
+}
+
 export function removeMergeQueueItem(db, itemId) {
   const item = getMergeQueueItem(db, itemId);
   if (!item) return null;
@@ -1755,7 +2523,7 @@ export function listDependencyInvalidations(db, { status = 'stale', pipelineId =
   }));
 }
 
-export function touchBoundaryValidationState(db, leaseId, source = 'write') {
+export function touchBoundaryValidationState(db, leaseId, source = 'write', context = {}) {
   return withImmediateTransaction(db, () => {
     const state = computeBoundaryValidationStateTx(db, leaseId, { touched: true, source });
     if (state) {
@@ -1774,7 +2542,7 @@ export function touchBoundaryValidationState(db, leaseId, source = 'write') {
       });
     }
 
-    const invalidations = syncDependencyInvalidationsForLeaseTx(db, leaseId, source);
+    const invalidations = syncDependencyInvalidationsForLeaseTx(db, leaseId, source, context);
     if (invalidations.length > 0) {
       logAuditEventTx(db, {
         eventType: 'dependency_invalidations_updated',
@@ -1786,6 +2554,8 @@ export function touchBoundaryValidationState(db, leaseId, source = 'write') {
           source,
           stale_count: invalidations.length,
           affected_task_ids: [...new Set(invalidations.map((item) => item.affected_task_id))],
+          reason_types: [...new Set(invalidations.map((item) => item.reason_type))],
+          revalidation_sets: [...new Set(invalidations.map((item) => item.details?.revalidation_set).filter(Boolean))],
         }),
       });
     }
@@ -1934,19 +2704,29 @@ export function reapStaleLeases(db, staleAfterMinutes = DEFAULT_STALE_LEASE_MINU
 export function claimFiles(db, taskId, worktree, filePaths, agent) {
   return withImmediateTransaction(db, () => {
     const lease = resolveActiveLeaseTx(db, taskId, worktree, agent);
-    const findActiveClaim = db.prepare(`
+    const activeClaims = db.prepare(`
       SELECT *
       FROM file_claims
-      WHERE file_path=? AND released_at IS NULL
-      LIMIT 1
-    `);
+      WHERE released_at IS NULL
+      ORDER BY id ASC
+    `).all();
+    const activeClaimByPath = new Map();
+    for (const claim of activeClaims) {
+      const normalizedPath = normalizeClaimedFilePath(claim.file_path);
+      if (!activeClaimByPath.has(normalizedPath)) {
+        activeClaimByPath.set(normalizedPath, claim);
+      }
+    }
+
+    const normalizeAndDeduplicate = [...new Set(filePaths.map((filePath) => normalizeClaimedFilePath(filePath)))];
+    const findClaimOwner = (normalizedPath) => activeClaimByPath.get(normalizedPath) || null;
     const insert = db.prepare(`
       INSERT INTO file_claims (task_id, lease_id, file_path, worktree, agent)
       VALUES (?, ?, ?, ?, ?)
     `);
 
-    for (const fp of filePaths) {
-      const existing = findActiveClaim.get(fp);
+    for (const normalizedPath of normalizeAndDeduplicate) {
+      const existing = findClaimOwner(normalizedPath);
       if (existing) {
         const sameLease = existing.lease_id === lease.id;
         const sameLegacyOwner = existing.lease_id == null && existing.task_id === taskId && existing.worktree === worktree;
@@ -1958,6 +2738,7 @@ export function claimFiles(db, taskId, worktree, filePaths, agent) {
               SET lease_id=?, agent=COALESCE(?, agent)
               WHERE id=?
             `).run(lease.id, agent || null, existing.id);
+            activeClaimByPath.set(normalizedPath, { ...existing, lease_id: lease.id, agent: agent || existing.agent });
           }
           continue;
         }
@@ -1965,14 +2746,21 @@ export function claimFiles(db, taskId, worktree, filePaths, agent) {
         throw new Error('One or more files are already actively claimed by another task.');
       }
 
-      insert.run(taskId, lease.id, fp, worktree, agent || null);
+      insert.run(taskId, lease.id, normalizedPath, worktree, agent || null);
+      activeClaimByPath.set(normalizedPath, {
+        task_id: taskId,
+        lease_id: lease.id,
+        file_path: normalizedPath,
+        worktree,
+        agent: agent || null,
+      });
       logAuditEventTx(db, {
         eventType: 'file_claimed',
         status: 'allowed',
         worktree,
         taskId,
         leaseId: lease.id,
-        filePath: fp,
+        filePath: normalizedPath,
       });
     }
 
@@ -2030,19 +2818,27 @@ export function getCompletedFileClaims(db, worktree = null) {
 }
 
 export function checkFileConflicts(db, filePaths, excludeWorktree) {
+  const normalizedPaths = [...new Set(filePaths.map((filePath) => normalizeClaimedFilePath(filePath)))];
   const conflicts = [];
-  const stmt = db.prepare(`
+  const claims = db.prepare(`
     SELECT fc.*, t.title as task_title, l.id as lease_id, l.status as lease_status
     FROM file_claims fc
     JOIN tasks t ON fc.task_id = t.id
     LEFT JOIN leases l ON fc.lease_id = l.id
-    WHERE fc.file_path=?
-      AND fc.released_at IS NULL
+    WHERE fc.released_at IS NULL
       AND fc.worktree != ?
       AND t.status NOT IN ('done','failed')
-  `);
-  for (const fp of filePaths) {
-    const existing = stmt.get(fp, excludeWorktree || '');
+  `).all(excludeWorktree || '');
+  const claimByNormalizedPath = new Map();
+  for (const claim of claims) {
+    const normalizedPath = normalizeClaimedFilePath(claim.file_path);
+    if (!claimByNormalizedPath.has(normalizedPath)) {
+      claimByNormalizedPath.set(normalizedPath, claim);
+    }
+  }
+
+  for (const fp of normalizedPaths) {
+    const existing = claimByNormalizedPath.get(fp);
     if (existing) conflicts.push({ file: fp, claimedBy: existing });
   }
   return conflicts;