fix: enforce workspace boundaries for agent tools, block critical compliance turns

- Add 'workspace' PolicyKind with default_deny_workspace_global rule (priority 150)
- Enforce workspace policy in validateToolCall for file tools and shell
- Sandbox shell tool cwd to agent workspace by default, validate via resolveWorkspacePath
- Block subsequent turns when compliance classifies previous turn as critical risk
- Migration 056 widens policy_rules CHECK constraint and inserts default deny rule
- 9 tests covering policy kind, deny/allow rules, validateToolCall blocking, shell workspace param

Author: scarecr0w12

CHANGELOG.md

@@ -35,6 +35,19 @@ Versioning: [Semantic Versioning](https://semver.org/)
   and the database, including retroactive cleanup of entries leaked by prior test runs.
   (`tests/mcp_test.ts`)
 
+- **Agent workspace boundary escape** — non-admin agents could bypass workspace isolation
+  by specifying `workspace: "global"` in file tools (`file_list`, `file_tree`) and shell
+  commands, accessing the host filesystem outside their agent workspace directory. Added a
+  new `workspace` `PolicyKind` with a `default_deny_workspace_global` deny rule (priority 150,
+  migration 056) that blocks `workspace:global` access unless an explicit allow rule exists.
+  The shell tool now defaults to agent workspace and validates `cwd` via
+  `resolveWorkspacePath`. When compliance classifies a turn as `critical` risk, subsequent
+  turns in that session are now blocked rather than only logged.
+  (`src/security/policy.ts`, `src/security/validator.ts`, `packages/gate/src/security/policy.ts`,
+  `packages/gate/src/security/validator.ts`, `src/tools/builtin/shell.ts`,
+  `src/pipeline/builtin.ts`, migration `056_workspace_policy.sql`,
+  `tests/workspace_policy_test.ts`)
+
 ### Changed
 
 - **Gateway health-retry endpoint now functional** — `POST /api/mcp-gateway/health-retry`
@@ -268,6 +281,24 @@ Versioning: [Semantic Versioning](https://semver.org/)
   real CodeFile containers rather than unrelated symbol nodes.
   (`src/codegraph/sync.ts`, `src/codegraph/resolver.ts`)
 
+- **Database corruption defenses** — four-layer protection against SQLite corruption from
+  concurrent server instances, crashes, and unclean shutdowns:
+  1. **Pre-start integrity check** — `runMigrations()` now runs `PRAGMA integrity_check` on all
+     5 databases before applying migrations. If corruption is detected, the server refuses to start
+     with a clear error message pointing to the backups directory.
+  2. **Single-instance PID lock** — a `server.pid` file is checked before any initialization.
+     If another cortex server process is alive and holding the lock, the new instance exits
+     immediately with the running PID. Stale PID files from dead processes are cleaned up
+     automatically.
+  3. **WAL checkpoint on graceful shutdown** — the shutdown handler now checkpoints all databases
+     with `PRAGMA wal_checkpoint(TRUNCATE)`, ensuring WAL data is merged into the main database
+     file before exit.
+  4. **Enhanced `tryRecover()`** — recovery uses `PRAGMA integrity_check` instead of `SELECT 1`
+     for corruption detection, catches `malformed database schema` errors, verifies restored
+     backups pass integrity checks before accepting them, and falls through to older backups when
+     the latest is also corrupted. Recovery instructions are printed when no healthy backup exists.
+  (`src/db/migrate.ts`, `src/server/server.ts`)
+
 ## [0.53.1] - 2026-06-24
 
 ### Fixed

packages/gate/src/security/policy.ts

@@ -1,7 +1,14 @@
 import { getCoreDb } from '../../../../src/db/client.ts';
 import type { InValue } from 'npm:@libsql/client';
 
-export type PolicyKind = 'tool' | 'shell' | 'domain' | 'capability' | 'path' | 'computer';
+export type PolicyKind =
+  | 'tool'
+  | 'shell'
+  | 'domain'
+  | 'capability'
+  | 'path'
+  | 'computer'
+  | 'workspace';
 export type PolicyEffect = 'allow' | 'deny';
 
 export interface PolicyRule {

packages/gate/src/security/validator.ts

@@ -54,6 +54,23 @@ export async function validateToolCall(
   }
 
   if (toolName === 'shell' || toolName === 'code_exec') {
+    const wsArg = args.workspace;
+    if (wsArg === 'global' || wsArg === 'agent') {
+      const wsDecision = await checkPolicy('workspace', String(wsArg));
+      if (!wsDecision.allowed) {
+        await logEvent({
+          event_type: 'policy_check',
+          session_id: sessionId,
+          actor: 'validator',
+          action: `workspace:${toolName}`,
+          summary: `Workspace access denied: ${wsArg}`,
+          started_at: new Date().toISOString(),
+          payload: { tool: toolName, workspace: wsArg, rule: wsDecision.rule?.id },
+        });
+        return { allowed: false, reason: wsDecision.reason };
+      }
+    }
+
     const command = String(args.command ?? args.code ?? '');
     const shellDecision = await checkPolicy('shell', command);
 
@@ -128,8 +145,26 @@ export async function validateToolCall(
     }
   }
 
-  // Path-based policy check for file tools
+  // Workspace policy check for file tools with workspace parameter
   if (FILE_TOOLS.has(toolName)) {
+    const workspaceArg = args.workspace;
+    if (workspaceArg === 'global' || workspaceArg === 'agent') {
+      const wsValue = String(workspaceArg);
+      const wsDecision = await checkPolicy('workspace', wsValue);
+      if (!wsDecision.allowed) {
+        await logEvent({
+          event_type: 'policy_check',
+          session_id: sessionId,
+          actor: 'validator',
+          action: `workspace:${toolName}`,
+          summary: `Workspace access denied: ${wsValue}`,
+          started_at: new Date().toISOString(),
+          payload: { tool: toolName, workspace: wsValue, rule: wsDecision.rule?.id },
+        });
+        return { allowed: false, reason: wsDecision.reason };
+      }
+    }
+
     const pathArg = args.path ?? args.source ?? args.pattern ?? '';
     if (typeof pathArg === 'string' && pathArg) {
       const pathDecision = await checkPolicy('path', pathArg);

src/db/migrate.ts

@@ -83,7 +83,7 @@ const DB_FILES = ['cortex.db', 'memory.db', 'lens.db', 'vault.db', 'plugins.db']
 
 const MAX_BACKUPS = 5;
 
-async function checkpointWal(db: Db): Promise<void> {
+export async function checkpointWal(db: Db): Promise<void> {
   try {
     await db.run('PRAGMA wal_checkpoint(TRUNCATE)');
   } catch {
@@ -145,29 +145,40 @@ async function pruneBackups(): Promise<void> {
 async function tryRecover(dbPath: string): Promise<boolean> {
   if (!await exists(dbPath)) return false;
 
-  // Try opening the DB. SQLite auto-recovers WAL from unclean shutdown.
-  // Only treat as corrupt if it throws SQLITE_CORRUPT.
   let isCorrupt = false;
+  let corruptReason = '';
   try {
     const testClient = createClient({ url: `file:${dbPath}` });
-    await testClient.execute('SELECT 1');
+    const result = await testClient.execute('PRAGMA integrity_check');
+    const rows = result.rows as unknown as Array<{ integrity_check: string }>;
+    for (const row of rows) {
+      if (row.integrity_check !== 'ok') {
+        isCorrupt = true;
+        corruptReason = row.integrity_check;
+        break;
+      }
+    }
     testClient.close();
   } catch (e) {
+    const msg = (e as Error).message ?? '';
     if (
-      (e as Error).message?.includes('SQLITE_CORRUPT') ||
-      (e as Error).message?.includes('disk image is malformed')
+      msg.includes('SQLITE_CORRUPT') ||
+      msg.includes('disk image is malformed') ||
+      msg.includes('malformed database schema')
     ) {
-      console.log(`  ⚠ ${basename(dbPath)} is corrupted (SQLITE_CORRUPT) — will recover`);
+      console.log(`  ⚠ ${basename(dbPath)} is corrupted (${msg.slice(0, 80)}) — will recover`);
       isCorrupt = true;
+      corruptReason = msg;
     } else {
-      // Other errors (permission, etc.) — don't try to recover
-      console.error(`  ✗ ${basename(dbPath)} open failed: ${(e as Error).message}`);
+      console.error(`  ✗ ${basename(dbPath)} open failed: ${msg}`);
       return false;
     }
   }
 
   if (!isCorrupt) return false;
 
+  console.log(`  ⚠ ${basename(dbPath)} integrity failure: ${corruptReason.slice(0, 120)}`);
+
   const entries: Deno.DirEntry[] = [];
   for await (const entry of Deno.readDir(PATHS.backupsDir)) {
     if (entry.isDirectory) entries.push(entry);
@@ -199,18 +210,80 @@ async function tryRecover(dbPath: string): Promise<boolean> {
       }
     }
 
-    return true;
+    // Verify restored backup passes integrity check
+    try {
+      const verifyClient = createClient({ url: `file:${dbPath}` });
+      const verifyResult = await verifyClient.execute('PRAGMA integrity_check');
+      const verifyRows = verifyResult.rows as unknown as Array<{ integrity_check: string }>;
+      const verifyOk = verifyRows.length === 1 && verifyRows[0].integrity_check === 'ok';
+      verifyClient.close();
+      if (verifyOk) {
+        console.log(`  ✓ ${basename(dbPath)} restored from backup — integrity check passed`);
+        return true;
+      } else {
+        console.warn(
+          `  ⚠ Restored ${basename(dbPath)} still has integrity issues — trying older backup`,
+        );
+      }
+    } catch {
+      console.warn(
+        `  ⚠ Restored ${basename(dbPath)} failed to open — trying older backup`,
+      );
+    }
   }
 
   if (isCorrupt) {
     console.error(
-      `  ✗ ${basename(dbPath)} is corrupted and no backup exists — manual recovery required`,
+      `  ✗ ${basename(dbPath)} has corruption and no healthy backup found.`,
+    );
+    console.error(
+      `    To recover manually:`,
+    );
+    if (await exists(PATHS.backupsDir)) {
+      console.error(`    1. Find a healthy backup in ${PATHS.backupsDir}`);
+      console.error(`    2. Copy cortex.db from the backup into ${PATHS.dataDir}`);
+      console.error(`    3. Remove any <dbname>-wal and <dbname>-shm files`);
+      console.error(`    4. Restart the server`);
+    }
+    console.error(
+      `    If no healthy backup exists, delete the corrupted database to start fresh.`,
     );
   }
 
   return false;
 }
 
+async function integrityCheck(db: Db, label: string): Promise<string[]> {
+  try {
+    const rows = await db.all<{ integrity_check: string }>('PRAGMA integrity_check');
+    const errors: string[] = [];
+    for (const row of rows) {
+      const val = row.integrity_check;
+      if (val !== 'ok') errors.push(val);
+    }
+    return errors;
+  } catch (e) {
+    return [`${label}: integrity_check failed — ${(e as Error).message}`];
+  }
+}
+
+async function checkAllDatabases(
+  dbs: Map<string, Db>,
+  labels: Map<string, string>,
+): Promise<boolean> {
+  let allOk = true;
+  for (const [name, db] of dbs) {
+    const label = labels.get(name) ?? name;
+    const errors = await integrityCheck(db, label);
+    if (errors.length > 0) {
+      allOk = false;
+      console.error(`  ✗ ${label} integrity errors:`);
+      for (const err of errors) console.error(`    • ${err}`);
+    }
+  }
+  return allOk;
+}
+
 export async function runMigrations(): Promise<void> {
   await ensureDir(PATHS.dataDir);
   await ensureDir(PATHS.sessionsDir);
@@ -230,6 +303,34 @@ export async function runMigrations(): Promise<void> {
   const vaultDb = await getVaultDb();
   const pluginsDb = await getPluginsDb();
 
+  const integrityLabels = new Map([
+    ['cortex.db', 'cortex.db'],
+    ['memory.db', 'memory.db'],
+    ['lens.db', 'lens.db'],
+    ['vault.db', 'vault.db'],
+    ['plugins.db', 'plugins.db'],
+  ]);
+  const integrityDbs = new Map<string, Db>([
+    ['cortex.db', coreDb],
+    ['memory.db', memoryDb],
+    ['lens.db', lensDb],
+    ['vault.db', vaultDb],
+    ['plugins.db', pluginsDb],
+  ]);
+
+  if (!await checkAllDatabases(integrityDbs, integrityLabels)) {
+    console.error(
+      '\n  Database corruption detected. The server cannot start with corrupted databases.',
+    );
+    console.error(
+      '  To recover: restore from backups in ' + PATHS.backupsDir,
+    );
+    console.error(
+      '  Backups are created automatically before each migration run.',
+    );
+    Deno.exit(1);
+  }
+
   const dbMap = new Map<string, Db>([
     ['cortex.db', coreDb],
     ['memory.db', memoryDb],
@@ -443,6 +544,11 @@ export async function runMigrations(): Promise<void> {
       sqlFile: '055_mcp_gateway_approvals.sql',
       label: 'cortex.db (MCP gateway approvals)',
     },
+    {
+      db: coreDb,
+      sqlFile: '056_workspace_policy.sql',
+      label: 'cortex.db (workspace boundary policy)',
+    },
   ];
 
   for (const { db, sqlFile, label } of targets) {
@@ -471,6 +577,14 @@ export async function runMigrations(): Promise<void> {
   // Run sensitivity backfill if needed (one-time after adding sensitivity columns)
   const { runBackfill } = await import('../security/backfill.ts');
   await runBackfill();
+
+  // Final health check — warn (don't abort) on post-migration issues
+  const postCheckOk = await checkAllDatabases(integrityDbs, integrityLabels);
+  if (!postCheckOk) {
+    console.warn(
+      '  ⚠ Post-migration integrity issues detected. Some features may be degraded.',
+    );
+  }
 }
 
 export async function createAutoAdmin(

src/db/migrations/056_workspace_policy.sql

@@ -0,0 +1,29 @@
+-- Migration 056: Workspace boundary policy rules (cortex.db)
+-- 1. Widen the CHECK constraint on policy_rules.kind to include 'workspace'
+-- 2. Add default deny rule for workspace:global access
+
+-- Widen constraint via table rebuild (SQLite lacks ALTER TABLE DROP CONSTRAINT)
+CREATE TABLE IF NOT EXISTS policy_rules_new (
+  id          TEXT PRIMARY KEY,
+  kind        TEXT NOT NULL CHECK (kind IN ('tool', 'shell', 'domain', 'capability', 'path', 'computer', 'workspace')),
+  effect      TEXT NOT NULL CHECK (effect IN ('allow', 'deny')),
+  pattern     TEXT NOT NULL,
+  reason      TEXT,
+  priority    INTEGER NOT NULL DEFAULT 100,
+  enabled     INTEGER NOT NULL DEFAULT 1,
+  node_id     TEXT,
+  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO policy_rules_new SELECT * FROM policy_rules;
+
+DROP TABLE policy_rules;
+ALTER TABLE policy_rules_new RENAME TO policy_rules;
+
+CREATE INDEX IF NOT EXISTS idx_policy_rules_kind ON policy_rules(kind);
+CREATE INDEX IF NOT EXISTS idx_policy_rules_enabled ON policy_rules(enabled);
+
+-- Add default deny rule for workspace:global (priority 150 between deny rules ~1-10 and default_allow_tools at 200)
+INSERT OR IGNORE INTO policy_rules (id, kind, effect, pattern, reason, priority, enabled, node_id, created_at)
+VALUES ('default_deny_workspace_global', 'workspace', 'deny', 'global',
+        'Global workspace access denied by default — requires explicit allow rule', 150, 1, NULL, datetime('now'));