@cluesmith/codev 3.3.1 → 3.3.3

package/dist/agent-farm/db/migrations.js

@@ -0,0 +1,530 @@
+/**
+ * global.db forward-only migrations (Issue #1476).
+ *
+ * The migration sequence used to live inline inside the private
+ * `ensureGlobalDatabase()` path in `db/index.ts`, so migration tests could only
+ * drive hand-maintained *replicas* of it. This module is the single source of
+ * truth both production init and the tests call:
+ *
+ *   - `ensureGlobalDatabase()` calls `runGlobalMigrations(db)` on an existing
+ *     database (fresh installs get the final shape from GLOBAL_SCHEMA and stamp
+ *     every marker up to `GLOBAL_CURRENT_VERSION` instead).
+ *   - `__tests__/spec-1313-migration.test.ts` builds a database at a historical
+ *     version and calls the very same function, so the SQL under test is the SQL
+ *     that ships.
+ *
+ * The runner takes an explicit `db` handle (matching `db/mailbox.ts` /
+ * `db/consolidate.ts`) — it never opens a connection, reads a singleton, or sets
+ * pragmas. Every step is idempotent and gated on its `_migrations` marker, so
+ * calling it repeatedly on the same handle is a no-op. Migrations are
+ * forward-only by project convention; there is no reverse SQL.
+ */
+import { existsSync, readdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Current migration version — bump when adding new migrations. */
+export const GLOBAL_CURRENT_VERSION = 18;
+/**
+ * Run every outstanding global.db migration against `db`.
+ *
+ * Safe to call on any existing database that reached its recorded version through
+ * migrations: each step checks its own `_migrations` marker first, so applied steps
+ * are skipped and the call converges on the `GLOBAL_CURRENT_VERSION` shape.
+ *
+ * NOT for a fresh database. A GLOBAL_SCHEMA-shaped database with no markers would run
+ * v5 against the long-renamed `terminal_sessions.project_path` — which is why
+ * `ensureGlobalDatabase()` stamps every marker on the fresh path instead of running
+ * the chain. That shape is rejected at entry with a named error rather than an opaque
+ * mid-chain SQLite failure.
+ *
+ * @throws if the database carries the post-v9 `workspace_path` shape without the v9
+ * marker to match (a fresh schema that never walked the chain).
+ */
+export function runGlobalMigrations(db, options = {}) {
+    const log = options.log ?? ((message) => console.log(message));
+    const runDir = options.runDir ?? join(homedir(), '.codev', 'run');
+    // Ensure _migrations table exists for tracking
+    db.exec(`CREATE TABLE IF NOT EXISTS _migrations (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )`);
+    // Precondition. Steps v5/v7/v8/v9 read and rebuild the project_path-era tables, so
+    // the chain only makes sense on a database that reached its recorded version through
+    // migrations. A fresh GLOBAL_SCHEMA database with no markers would instead die at v5
+    // with an opaque `no such column: project_path` — so name that shape here. Production
+    // never reaches this (ensureGlobalDatabase stamps every marker on the fresh path); it
+    // exists because the runner is now callable from anywhere.
+    const terminalSessions = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='terminal_sessions'")
+        .get();
+    if (terminalSessions) {
+        const renamed = db.prepare(`PRAGMA table_info(terminal_sessions)`).all()
+            .some((c) => c.name === 'workspace_path');
+        const v9Marker = db.prepare('SELECT version FROM _migrations WHERE version = 9').get();
+        if (renamed && !v9Marker) {
+            throw new Error('runGlobalMigrations: refusing to run on a database whose terminal_sessions is already ' +
+                'workspace_path-shaped but has no v9 migration marker. This is a fresh GLOBAL_SCHEMA ' +
+                'database that never walked the chain — stamp markers 1..GLOBAL_CURRENT_VERSION instead ' +
+                '(see ensureGlobalDatabase), or the chain will fail mid-way on renamed columns.');
+        }
+    }
+    // Migration v2: No-op (previously added columns to port_allocations, now removed by Spec 0098)
+    const v2 = db.prepare('SELECT version FROM _migrations WHERE version = 2').get();
+    if (!v2) {
+        db.prepare('INSERT INTO _migrations (version) VALUES (2)').run();
+    }
+    // Migration v3: Add terminal_sessions table (Spec 0090 TICK-001)
+    const v3 = db.prepare('SELECT version FROM _migrations WHERE version = 3').get();
+    if (!v3) {
+        // Create terminal_sessions table if it doesn't exist
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS terminal_sessions (
+        id TEXT PRIMARY KEY,
+        project_path TEXT NOT NULL,
+        type TEXT NOT NULL CHECK(type IN ('architect', 'builder', 'shell')),
+        role_id TEXT,
+        pid INTEGER,
+        tmux_session TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_path);
+      CREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (3)').run();
+        log('[info] Created terminal_sessions table (Spec 0090 TICK-001)');
+    }
+    // Migration v4: Add file_tabs table (Spec 0099 Phase 4)
+    const v4 = db.prepare('SELECT version FROM _migrations WHERE version = 4').get();
+    if (!v4) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS file_tabs (
+        id TEXT PRIMARY KEY,
+        project_path TEXT NOT NULL,
+        file_path TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_file_tabs_project ON file_tabs(project_path);
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (4)').run();
+        log('[info] Created file_tabs table (Spec 0099 Phase 4)');
+    }
+    // Migration v5: Add known_projects table for persistent project registry
+    const v5 = db.prepare('SELECT version FROM _migrations WHERE version = 5').get();
+    if (!v5) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS known_projects (
+        project_path TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+        // Seed from existing terminal_sessions so current projects appear immediately
+        db.exec(`
+      INSERT OR IGNORE INTO known_projects (project_path, name, last_launched_at)
+      SELECT DISTINCT project_path, '', datetime('now') FROM terminal_sessions;
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (5)').run();
+        log('[info] Created known_projects table');
+    }
+    // Migration v6: Add shepherd columns to terminal_sessions (Spec 0104)
+    const v6 = db.prepare('SELECT version FROM _migrations WHERE version = 6').get();
+    if (!v6) {
+        const cols = ['shepherd_socket TEXT', 'shepherd_pid INTEGER', 'shepherd_start_time INTEGER'];
+        for (const col of cols) {
+            try {
+                db.exec(`ALTER TABLE terminal_sessions ADD COLUMN ${col}`);
+            }
+            catch {
+                // Column already exists (fresh install ran updated schema)
+            }
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (6)').run();
+        log('[info] Added shepherd columns to terminal_sessions (Spec 0104)');
+    }
+    // Migration v7: Drop tmux_session column from terminal_sessions (Spec 0104 Phase 4)
+    const v7 = db.prepare('SELECT version FROM _migrations WHERE version = 7').get();
+    if (!v7) {
+        // SQLite table-rebuild pattern to drop the tmux_session column
+        try {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS terminal_sessions_new (
+          id TEXT PRIMARY KEY,
+          project_path TEXT NOT NULL,
+          type TEXT NOT NULL CHECK(type IN ('architect', 'builder', 'shell')),
+          role_id TEXT,
+          pid INTEGER,
+          shepherd_socket TEXT,
+          shepherd_pid INTEGER,
+          shepherd_start_time INTEGER,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        INSERT OR IGNORE INTO terminal_sessions_new
+          SELECT id, project_path, type, role_id, pid, shepherd_socket, shepherd_pid, shepherd_start_time, created_at
+          FROM terminal_sessions;
+        DROP TABLE terminal_sessions;
+        ALTER TABLE terminal_sessions_new RENAME TO terminal_sessions;
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_path);
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);
+      `);
+        }
+        catch {
+            // Table may already be in the correct schema (fresh install)
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (7)').run();
+        log('[info] Dropped tmux_session column from terminal_sessions (Spec 0104)');
+    }
+    // Migration v8: Rename shepherd_* columns to shellper_* (Spec 0106)
+    const v8 = db.prepare('SELECT version FROM _migrations WHERE version = 8').get();
+    if (!v8) {
+        try {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS terminal_sessions_new (
+          id TEXT PRIMARY KEY,
+          project_path TEXT NOT NULL,
+          type TEXT NOT NULL CHECK(type IN ('architect', 'builder', 'shell')),
+          role_id TEXT,
+          pid INTEGER,
+          shellper_socket TEXT,
+          shellper_pid INTEGER,
+          shellper_start_time INTEGER,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        INSERT OR IGNORE INTO terminal_sessions_new
+          SELECT id, project_path, type, role_id, pid, shepherd_socket, shepherd_pid, shepherd_start_time, created_at
+          FROM terminal_sessions;
+        DROP TABLE terminal_sessions;
+        ALTER TABLE terminal_sessions_new RENAME TO terminal_sessions;
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_path);
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);
+        UPDATE terminal_sessions SET shellper_socket = REPLACE(shellper_socket, 'shepherd-', 'shellper-')
+          WHERE shellper_socket LIKE '%shepherd-%';
+      `);
+        }
+        catch {
+            // Table may already be in the correct schema (fresh install)
+        }
+        // Rename physical socket files on disk
+        try {
+            if (existsSync(runDir)) {
+                const files = readdirSync(runDir);
+                for (const file of files) {
+                    if (file.startsWith('shepherd-') && file.endsWith('.sock')) {
+                        const newName = file.replace('shepherd-', 'shellper-');
+                        try {
+                            renameSync(join(runDir, file), join(runDir, newName));
+                        }
+                        catch {
+                            // Skip files that can't be renamed (missing, permissions, etc.)
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip if run directory doesn't exist or can't be read
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (8)').run();
+        log('[info] Renamed shepherd columns to shellper in terminal_sessions (Spec 0106)');
+    }
+    // Migration v9: Rename project_path → workspace_path in all tables (Spec 0112)
+    // Note: Fresh installs never reach here (handled by the caller), so old column
+    // names are guaranteed.
+    // Wrapped in a transaction for atomicity — all three renames succeed or none do.
+    const v9 = db.prepare('SELECT version FROM _migrations WHERE version = 9').get();
+    if (!v9) {
+        const migrate = db.transaction(() => {
+            // 1. Rename terminal_sessions.project_path → workspace_path
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS terminal_sessions_new (
+          id TEXT PRIMARY KEY,
+          workspace_path TEXT NOT NULL,
+          type TEXT NOT NULL CHECK(type IN ('architect', 'builder', 'shell')),
+          role_id TEXT,
+          pid INTEGER,
+          shellper_socket TEXT,
+          shellper_pid INTEGER,
+          shellper_start_time INTEGER,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        INSERT OR IGNORE INTO terminal_sessions_new
+          SELECT id, project_path, type, role_id, pid, shellper_socket, shellper_pid, shellper_start_time, created_at
+          FROM terminal_sessions;
+        DROP TABLE terminal_sessions;
+        ALTER TABLE terminal_sessions_new RENAME TO terminal_sessions;
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_workspace ON terminal_sessions(workspace_path);
+        CREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);
+      `);
+            // 2. Rename file_tabs.project_path → workspace_path
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS file_tabs_new (
+          id TEXT PRIMARY KEY,
+          workspace_path TEXT NOT NULL,
+          file_path TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        INSERT OR IGNORE INTO file_tabs_new
+          SELECT id, project_path, file_path, created_at
+          FROM file_tabs;
+        DROP TABLE file_tabs;
+        ALTER TABLE file_tabs_new RENAME TO file_tabs;
+        CREATE INDEX IF NOT EXISTS idx_file_tabs_workspace ON file_tabs(workspace_path);
+      `);
+            // 3. Rename known_projects → known_workspaces with project_path → workspace_path
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS known_workspaces (
+          workspace_path TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        INSERT OR IGNORE INTO known_workspaces (workspace_path, name, last_launched_at)
+          SELECT project_path, name, last_launched_at FROM known_projects;
+        DROP TABLE IF EXISTS known_projects;
+      `);
+            db.prepare('INSERT INTO _migrations (version) VALUES (9)').run();
+        });
+        migrate();
+        log('[info] Renamed project_path → workspace_path in global tables (Spec 0112)');
+    }
+    // Migration v10: Add cron_tasks table (Spec 399)
+    const v10 = db.prepare('SELECT version FROM _migrations WHERE version = 10').get();
+    if (!v10) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS cron_tasks (
+        id TEXT PRIMARY KEY,
+        workspace_path TEXT NOT NULL,
+        task_name TEXT NOT NULL,
+        last_run INTEGER,
+        last_result TEXT,
+        last_output TEXT,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        UNIQUE(workspace_path, task_name)
+      );
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (10)').run();
+        log('[info] Created cron_tasks table (Spec 399)');
+    }
+    // Migration v11: Add label column to terminal_sessions (Spec 468)
+    const v11 = db.prepare('SELECT version FROM _migrations WHERE version = 11').get();
+    if (!v11) {
+        try {
+            db.exec(`ALTER TABLE terminal_sessions ADD COLUMN label TEXT`);
+        }
+        catch {
+            // Column may already exist from a fresh install
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (11)').run();
+        log('[info] Added label column to terminal_sessions (Spec 468)');
+    }
+    // Migration v12: Add cwd column to terminal_sessions (Bugfix #506)
+    const v12 = db.prepare('SELECT version FROM _migrations WHERE version = 12').get();
+    if (!v12) {
+        try {
+            db.exec(`ALTER TABLE terminal_sessions ADD COLUMN cwd TEXT`);
+        }
+        catch {
+            // Column may already exist from a fresh install
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (12)').run();
+        log('[info] Added cwd column to terminal_sessions (Bugfix #506)');
+    }
+    // Migration v13: Backfill terminal_sessions.role_id for legacy architect rows (Spec 755)
+    // Pre-v13 rows for architects always stored role_id as NULL because there was only
+    // ever one architect per workspace. Multi-architect support requires the name to be
+    // present in role_id so reconnect can re-key the in-memory map. The idempotent
+    // backfill sets role_id = 'main' for legacy rows; subsequent architect rows write
+    // their explicit name and are unaffected.
+    const v13 = db.prepare('SELECT version FROM _migrations WHERE version = 13').get();
+    if (!v13) {
+        db.prepare(`
+      UPDATE terminal_sessions
+         SET role_id = 'main'
+       WHERE type = 'architect' AND role_id IS NULL
+    `).run();
+        db.prepare('INSERT INTO _migrations (version) VALUES (13)').run();
+        log('[info] Backfilled architect role_id with \'main\' (Spec 755)');
+    }
+    // Migration v14: Absorb the retired state.db tables (Issue #1118).
+    // Creates architect/builders/utils/annotations in global.db at their final
+    // shape. architect/utils/annotations move as-is; builders is RESHAPED with a
+    // workspace_path column + composite PK (workspace_path, id) so the same
+    // builder id can exist in multiple workspaces. Idempotent via
+    // `CREATE TABLE IF NOT EXISTS`. The one-time data migration of legacy
+    // state.db files is a separate, marker-gated step run at Tower boot
+    // (db/consolidate.ts) — NOT here — so opening global.db never moves data.
+    const v14 = db.prepare('SELECT version FROM _migrations WHERE version = 14').get();
+    if (!v14) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS architect (
+        workspace_path TEXT NOT NULL,
+        id TEXT NOT NULL,
+        pid INTEGER NOT NULL,
+        port INTEGER NOT NULL,
+        cmd TEXT NOT NULL,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        terminal_id TEXT,
+        session_id TEXT,
+        PRIMARY KEY (workspace_path, id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_architect_workspace ON architect(workspace_path);
+
+      CREATE TABLE IF NOT EXISTS builders (
+        workspace_path TEXT NOT NULL,
+        id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        port INTEGER NOT NULL DEFAULT 0,
+        pid INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'spawning'
+          CHECK(status IN ('spawning', 'implementing', 'blocked', 'pr', 'complete')),
+        phase TEXT NOT NULL DEFAULT '',
+        worktree TEXT NOT NULL,
+        branch TEXT NOT NULL,
+        type TEXT NOT NULL DEFAULT 'spec'
+          CHECK(type IN ('spec', 'task', 'protocol', 'shell', 'worktree', 'bugfix', 'pir')),
+        task_text TEXT,
+        protocol_name TEXT,
+        issue_number TEXT,
+        terminal_id TEXT,
+        spawned_by_architect TEXT,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (workspace_path, id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_builders_status ON builders(status);
+      CREATE INDEX IF NOT EXISTS idx_builders_port ON builders(port);
+      CREATE TRIGGER IF NOT EXISTS builders_updated_at
+        AFTER UPDATE ON builders
+        FOR EACH ROW
+        BEGIN
+          UPDATE builders SET updated_at = datetime('now')
+            WHERE workspace_path = NEW.workspace_path AND id = NEW.id;
+        END;
+
+      CREATE TABLE IF NOT EXISTS utils (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        port INTEGER NOT NULL DEFAULT 0,
+        pid INTEGER NOT NULL DEFAULT 0,
+        terminal_id TEXT,
+        started_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS annotations (
+        id TEXT PRIMARY KEY,
+        file TEXT NOT NULL,
+        port INTEGER NOT NULL DEFAULT 0,
+        pid INTEGER NOT NULL DEFAULT 0,
+        parent_type TEXT NOT NULL CHECK(parent_type IN ('architect', 'builder', 'util')),
+        parent_id TEXT,
+        started_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (14)').run();
+        log('[info] Absorbed state.db tables into global.db (Issue #1118)');
+    }
+    // Migration v15: Add mailbox table (Spec 1313 — mailbox-first delivery).
+    // Additive new table: every `afx send` is persisted here before the send
+    // response returns, so nothing is lost to a Tower crash/restart/shutdown.
+    // Rows address AGENTS (to_agent), not PTYs, so a respawned terminal drains its
+    // predecessor's mail. No rows to migrate — the retired SendBuffer was in-memory.
+    // Idempotent via CREATE TABLE / CREATE INDEX IF NOT EXISTS (fresh installs
+    // already created it from GLOBAL_SCHEMA and reach the marker as a no-op).
+    const v15 = db.prepare('SELECT version FROM _migrations WHERE version = 15').get();
+    if (!v15) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS mailbox (
+        id TEXT PRIMARY KEY,
+        workspace_path TEXT NOT NULL,
+        to_agent TEXT NOT NULL,
+        terminal_id TEXT,
+        from_agent TEXT,
+        from_workspace TEXT,
+        body TEXT NOT NULL,
+        formatted_message TEXT NOT NULL,
+        no_enter INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'held'
+          CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),
+        reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),
+        supersede_key TEXT,
+        escalated INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        resolved_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_mailbox_workspace_status ON mailbox(workspace_path, status);
+      CREATE INDEX IF NOT EXISTS idx_mailbox_agent_drain ON mailbox(workspace_path, to_agent, status);
+      CREATE INDEX IF NOT EXISTS idx_mailbox_supersede ON mailbox(supersede_key);
+    `);
+        db.prepare('INSERT INTO _migrations (version) VALUES (15)').run();
+        log('[info] Created mailbox table (Spec 1313)');
+    }
+    // Migration v16: Add command column to terminal_sessions (Spec 1313).
+    // The render-gate resolves an agent's classifier profile from its launch
+    // command (PtySession.command). Shellper-backed sessions were created with
+    // command: '' and the profile fell back to reading `.builder-start.sh` —
+    // which only builder worktrees have. Architects run in the workspace root
+    // (no launch script), so they never resolved and every `afx send architect`
+    // held `no-profile`. Persisting the command lets the reconcile/reconnect
+    // paths restore identity after a Tower restart, so architects resolve
+    // directly and survive restart (builders keep the launch-script backstop).
+    // Mirrors the label (v11) / cwd (v12) column adds.
+    const v16 = db.prepare('SELECT version FROM _migrations WHERE version = 16').get();
+    if (!v16) {
+        // Only skip the ALTER when the column genuinely exists already (fresh install
+        // ran GLOBAL_SCHEMA). A blanket try/catch would let a REAL alter failure be
+        // recorded as "migrated" — and since saveTerminalSession's INSERT now names
+        // `command`, every future write would then fail against a table missing it.
+        const hasCommand = db.prepare(`PRAGMA table_info(terminal_sessions)`).all()
+            .some((c) => c.name === 'command');
+        if (!hasCommand) {
+            db.exec(`ALTER TABLE terminal_sessions ADD COLUMN command TEXT`);
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (16)').run();
+        log('[info] Added command column to terminal_sessions (Spec 1313 restart-safe render-gate identity)');
+    }
+    // Migration v17: Add not_before column to mailbox (Spec 1313 round 3 — durable `--delay`).
+    // `afx send --delay` now persists its row at REQUEST time with not_before = now + delay*1000
+    // and defers delivery through the render gate, so a delayed send survives a Tower restart
+    // (the conscious reversal of Spec 1307's drop-on-restart semantics). A row is deliverable
+    // only when `not_before IS NULL OR not_before <= now`; null means deliver-ASAP (every
+    // pre-round-3 row). PRAGMA-gated ADD COLUMN mirroring v16 — a blanket try/catch would let a
+    // real ALTER failure be recorded as "migrated" and every subsequent mailbox insert (which
+    // now names not_before) would then fail against a table missing it. Do NOT edit v15 in place:
+    // dev machines on this branch already applied it, so the column must arrive as its own step.
+    const v17 = db.prepare('SELECT version FROM _migrations WHERE version = 17').get();
+    if (!v17) {
+        const hasNotBefore = db.prepare(`PRAGMA table_info(mailbox)`).all()
+            .some((c) => c.name === 'not_before');
+        if (!hasNotBefore) {
+            db.exec(`ALTER TABLE mailbox ADD COLUMN not_before INTEGER`);
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (17)').run();
+        log('[info] Added not_before column to mailbox (Spec 1313 durable --delay)');
+    }
+    // Migration v18: Add detail column to mailbox (Issue #1482 — the gate verdict's detail).
+    // The render gate already distinguishes a legitimately-occupied composer (`user-text` — a
+    // human at the line, the safe and intended hold) from a composer it CANNOT verify
+    // (`no-region-end`/`no-composer-marker` — a drifted profile, a torn frame, or a dims
+    // divergence, which will never clear on its own). That distinction lived only in memory on
+    // `DeliveryOutcome.detail`, so every operator surface — `afx inbox`, the send response, the
+    // held/escalation logs, the owner starvation notice — showed a bare `busy` for both. The two
+    // cases have DIFFERENT remedies, so the row has to carry which one it is.
+    //
+    // Deliberately NO CHECK constraint, unlike the sibling `reason` column: SQLite cannot add one
+    // via ALTER TABLE, so a CHECK present in GLOBAL_SCHEMA and absent here would make a fresh
+    // install and an upgraded install structurally different — the exact convergence the
+    // migration suite asserts. The value set is enforced in TypeScript (`MailboxGateDetail`).
+    // Same PRAGMA-gated ADD COLUMN shape as v16/v17: a blanket try/catch would let a real ALTER
+    // failure be recorded as "migrated", and every subsequent mailbox write (which now names
+    // `detail`) would then fail against a table missing it.
+    const v18 = db.prepare('SELECT version FROM _migrations WHERE version = 18').get();
+    if (!v18) {
+        const hasDetail = db.prepare(`PRAGMA table_info(mailbox)`).all()
+            .some((c) => c.name === 'detail');
+        if (!hasDetail) {
+            db.exec(`ALTER TABLE mailbox ADD COLUMN detail TEXT`);
+        }
+        db.prepare('INSERT INTO _migrations (version) VALUES (18)').run();
+        log('[info] Added detail column to mailbox (Issue #1482 gate-verdict detail)');
+    }
+}
+//# sourceMappingURL=migrations.js.map

package/dist/agent-farm/db/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../../src/agent-farm/db/migrations.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/db/schema.d.ts

@@ -19,5 +19,5 @@ export declare const LOCAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT
  * Global registry schema (global.db)
  * Stores terminal sessions and migrations across all workspaces
  */
-export declare const GLOBAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT EXISTS _migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Terminal sessions (Spec 0090 TICK-001)\n-- Tracks all terminal sessions across all workspaces for persistence and reconciliation\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,                    -- terminal UUID from PtyManager\n  workspace_path TEXT NOT NULL,           -- workspace this terminal belongs to\n  type TEXT NOT NULL                      -- 'architect', 'builder', 'shell'\n    CHECK(type IN ('architect', 'builder', 'shell')),\n  role_id TEXT,                           -- builder ID or shell ID (null for architect)\n  pid INTEGER,                            -- process ID of the terminal\n  shellper_socket TEXT,                   -- Unix socket path for shellper process\n  shellper_pid INTEGER,                   -- shellper process PID\n  shellper_start_time INTEGER,            -- shellper process start time (epoch ms)\n  label TEXT,                             -- custom display label (Spec 468)\n  cwd TEXT,                               -- working directory of the terminal (Bugfix #506)\n  command TEXT,                           -- launch command; render-gate identity seam (Spec 1313)\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_workspace ON terminal_sessions(workspace_path);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);\n\n-- File tabs (Spec 0099 Phase 4)\nCREATE TABLE IF NOT EXISTS file_tabs (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  file_path TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_file_tabs_workspace ON file_tabs(workspace_path);\n\n-- Known workspaces (persistent workspace registry)\nCREATE TABLE IF NOT EXISTS known_workspaces (\n  workspace_path TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Cron tasks (Spec 399)\n-- Tracks scheduled task state across all workspaces\nCREATE TABLE IF NOT EXISTS cron_tasks (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  task_name TEXT NOT NULL,\n  last_run INTEGER,\n  last_result TEXT,\n  last_output TEXT,\n  enabled INTEGER NOT NULL DEFAULT 1,\n  UNIQUE(workspace_path, task_name)\n);\n\n-- ===========================================================================\n-- Issue #1118: tables absorbed from the retired per-workspace state.db.\n-- architect/utils/annotations move as-is; builders is RESHAPED to be\n-- workspace-scoped (composite PK), mirroring architect (Bugfix #826) \u2014 builder\n-- ids are <protocol>-<issueNumber>, unique within a workspace but reused across\n-- repos, so a single shared table must disambiguate by workspace_path.\n-- ===========================================================================\n\n-- Architect sessions (Spec 755 multi-architect; Bugfix #826 workspace-scoped;\n-- Issue #832 session_id). id is the architect's name ('main', siblings).\nCREATE TABLE IF NOT EXISTS architect (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  pid INTEGER NOT NULL,\n  port INTEGER NOT NULL,\n  cmd TEXT NOT NULL,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  terminal_id TEXT,\n  session_id TEXT,\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_architect_workspace ON architect(workspace_path);\n\n-- Builder sessions. Issue #1118: workspace_path + composite PK so the same\n-- builder id can exist in multiple workspaces without collision.\nCREATE TABLE IF NOT EXISTS builders (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'spawning'\n    CHECK(status IN ('spawning', 'implementing', 'blocked', 'pr', 'complete')),\n  phase TEXT NOT NULL DEFAULT '',\n  worktree TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  type TEXT NOT NULL DEFAULT 'spec'\n    CHECK(type IN ('spec', 'task', 'protocol', 'shell', 'worktree', 'bugfix', 'pir')),\n  task_text TEXT,\n  protocol_name TEXT,\n  issue_number TEXT,\n  terminal_id TEXT,\n  spawned_by_architect TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_builders_status ON builders(status);\nCREATE INDEX IF NOT EXISTS idx_builders_port ON builders(port);\n\nCREATE TRIGGER IF NOT EXISTS builders_updated_at\n  AFTER UPDATE ON builders\n  FOR EACH ROW\n  BEGIN\n    UPDATE builders SET updated_at = datetime('now')\n      WHERE workspace_path = NEW.workspace_path AND id = NEW.id;\n  END;\n\n-- Utility terminals (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS utils (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  terminal_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Annotations / file viewers (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS annotations (\n  id TEXT PRIMARY KEY,\n  file TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  parent_type TEXT NOT NULL CHECK(parent_type IN ('architect', 'builder', 'util')),\n  parent_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Mailbox (Spec 1313): durable home for every 'afx send'.\n-- Persist-first delivery \u2014 a row is written before the send response returns, so\n-- nothing is lost to a Tower crash/restart/shutdown (the retired in-memory\n-- SendBuffer lost held messages on both). Rows address AGENTS (to_agent within\n-- workspace_path), not PTYs, so a respawned terminal drains its predecessor's\n-- mail. Delivery is authorized elsewhere by the render-gate (Phases 2/4); this\n-- table is pure durable state. Timestamps are epoch-ms integers (not SQLite\n-- datetime) so ordering and age math are trivial. Additive new table \u2014 fresh\n-- installs get it here; existing installs get it from migration v15.\nCREATE TABLE IF NOT EXISTS mailbox (\n  id TEXT PRIMARY KEY,                    -- uuid\n  workspace_path TEXT NOT NULL,           -- addressing scope\n  to_agent TEXT NOT NULL,                 -- recipient agent identity (drains across respawn)\n  terminal_id TEXT,                       -- last-known PTY hint (nullable; not the identity)\n  from_agent TEXT,\n  from_workspace TEXT,\n  body TEXT NOT NULL,                     -- raw message (never logged)\n  formatted_message TEXT NOT NULL,        -- what gets written to the PTY\n  no_enter INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'held'\n    CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),\n  reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),  -- why-held; null once delivered\n  supersede_key TEXT,                     -- cron-only; null for direct sends\n  escalated INTEGER NOT NULL DEFAULT 0,   -- set once escalation age crossed (visibility only)\n  not_before INTEGER,                     -- epoch ms; delayed-send due time (Spec 1313 round 3, --delay). null = deliver ASAP; a row is deliverable only when not_before IS NULL OR not_before <= now\n  created_at INTEGER NOT NULL,            -- epoch ms (enqueue order per agent)\n  updated_at INTEGER NOT NULL,\n  resolved_at INTEGER                     -- delivered/superseded/dismissed timestamp\n);\n\nCREATE INDEX IF NOT EXISTS idx_mailbox_workspace_status ON mailbox(workspace_path, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_agent_drain ON mailbox(workspace_path, to_agent, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_supersede ON mailbox(supersede_key);\n";
+export declare const GLOBAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT EXISTS _migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Terminal sessions (Spec 0090 TICK-001)\n-- Tracks all terminal sessions across all workspaces for persistence and reconciliation\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,                    -- terminal UUID from PtyManager\n  workspace_path TEXT NOT NULL,           -- workspace this terminal belongs to\n  type TEXT NOT NULL                      -- 'architect', 'builder', 'shell'\n    CHECK(type IN ('architect', 'builder', 'shell')),\n  role_id TEXT,                           -- builder ID or shell ID (null for architect)\n  pid INTEGER,                            -- process ID of the terminal\n  shellper_socket TEXT,                   -- Unix socket path for shellper process\n  shellper_pid INTEGER,                   -- shellper process PID\n  shellper_start_time INTEGER,            -- shellper process start time (epoch ms)\n  label TEXT,                             -- custom display label (Spec 468)\n  cwd TEXT,                               -- working directory of the terminal (Bugfix #506)\n  command TEXT,                           -- launch command; render-gate identity seam (Spec 1313)\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_workspace ON terminal_sessions(workspace_path);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);\n\n-- File tabs (Spec 0099 Phase 4)\nCREATE TABLE IF NOT EXISTS file_tabs (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  file_path TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_file_tabs_workspace ON file_tabs(workspace_path);\n\n-- Known workspaces (persistent workspace registry)\nCREATE TABLE IF NOT EXISTS known_workspaces (\n  workspace_path TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Cron tasks (Spec 399)\n-- Tracks scheduled task state across all workspaces\nCREATE TABLE IF NOT EXISTS cron_tasks (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  task_name TEXT NOT NULL,\n  last_run INTEGER,\n  last_result TEXT,\n  last_output TEXT,\n  enabled INTEGER NOT NULL DEFAULT 1,\n  UNIQUE(workspace_path, task_name)\n);\n\n-- ===========================================================================\n-- Issue #1118: tables absorbed from the retired per-workspace state.db.\n-- architect/utils/annotations move as-is; builders is RESHAPED to be\n-- workspace-scoped (composite PK), mirroring architect (Bugfix #826) \u2014 builder\n-- ids are <protocol>-<issueNumber>, unique within a workspace but reused across\n-- repos, so a single shared table must disambiguate by workspace_path.\n-- ===========================================================================\n\n-- Architect sessions (Spec 755 multi-architect; Bugfix #826 workspace-scoped;\n-- Issue #832 session_id). id is the architect's name ('main', siblings).\nCREATE TABLE IF NOT EXISTS architect (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  pid INTEGER NOT NULL,\n  port INTEGER NOT NULL,\n  cmd TEXT NOT NULL,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  terminal_id TEXT,\n  session_id TEXT,\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_architect_workspace ON architect(workspace_path);\n\n-- Builder sessions. Issue #1118: workspace_path + composite PK so the same\n-- builder id can exist in multiple workspaces without collision.\nCREATE TABLE IF NOT EXISTS builders (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'spawning'\n    CHECK(status IN ('spawning', 'implementing', 'blocked', 'pr', 'complete')),\n  phase TEXT NOT NULL DEFAULT '',\n  worktree TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  type TEXT NOT NULL DEFAULT 'spec'\n    CHECK(type IN ('spec', 'task', 'protocol', 'shell', 'worktree', 'bugfix', 'pir')),\n  task_text TEXT,\n  protocol_name TEXT,\n  issue_number TEXT,\n  terminal_id TEXT,\n  spawned_by_architect TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_builders_status ON builders(status);\nCREATE INDEX IF NOT EXISTS idx_builders_port ON builders(port);\n\nCREATE TRIGGER IF NOT EXISTS builders_updated_at\n  AFTER UPDATE ON builders\n  FOR EACH ROW\n  BEGIN\n    UPDATE builders SET updated_at = datetime('now')\n      WHERE workspace_path = NEW.workspace_path AND id = NEW.id;\n  END;\n\n-- Utility terminals (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS utils (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  terminal_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Annotations / file viewers (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS annotations (\n  id TEXT PRIMARY KEY,\n  file TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  parent_type TEXT NOT NULL CHECK(parent_type IN ('architect', 'builder', 'util')),\n  parent_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Mailbox (Spec 1313): durable home for every 'afx send'.\n-- Persist-first delivery \u2014 a row is written before the send response returns, so\n-- nothing is lost to a Tower crash/restart/shutdown (the retired in-memory\n-- SendBuffer lost held messages on both). Rows address AGENTS (to_agent within\n-- workspace_path), not PTYs, so a respawned terminal drains its predecessor's\n-- mail. Delivery is authorized elsewhere by the render-gate (Phases 2/4); this\n-- table is pure durable state. Timestamps are epoch-ms integers (not SQLite\n-- datetime) so ordering and age math are trivial. Additive new table \u2014 fresh\n-- installs get it here; existing installs get it from migration v15.\nCREATE TABLE IF NOT EXISTS mailbox (\n  id TEXT PRIMARY KEY,                    -- uuid\n  workspace_path TEXT NOT NULL,           -- addressing scope\n  to_agent TEXT NOT NULL,                 -- recipient agent identity (drains across respawn)\n  terminal_id TEXT,                       -- last-known PTY hint (nullable; not the identity)\n  from_agent TEXT,\n  from_workspace TEXT,\n  body TEXT NOT NULL,                     -- raw message (never logged)\n  formatted_message TEXT NOT NULL,        -- what gets written to the PTY\n  no_enter INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'held'\n    CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),\n  reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),  -- why-held; null once delivered\n  detail TEXT,                            -- Issue #1482: the gate verdict's detail behind a busy hold ('user-text' = a human at the line; 'no-region-end'/'no-composer-marker' = the classifier could not verify). Null for non-gate holds and once delivered. NO CHECK on purpose -- SQLite cannot ALTER one in, so migration v18 could not match it and a fresh install would diverge from an upgraded one; the value set is enforced in TypeScript (MailboxGateDetail)\n  supersede_key TEXT,                     -- cron-only; null for direct sends\n  escalated INTEGER NOT NULL DEFAULT 0,   -- set once escalation age crossed (visibility only)\n  not_before INTEGER,                     -- epoch ms; delayed-send due time (Spec 1313 round 3, --delay). null = deliver ASAP; a row is deliverable only when not_before IS NULL OR not_before <= now\n  created_at INTEGER NOT NULL,            -- epoch ms (enqueue order per agent)\n  updated_at INTEGER NOT NULL,\n  resolved_at INTEGER                     -- delivered/superseded/dismissed timestamp\n);\n\nCREATE INDEX IF NOT EXISTS idx_mailbox_workspace_status ON mailbox(workspace_path, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_agent_drain ON mailbox(workspace_path, to_agent, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_supersede ON mailbox(supersede_key);\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/agent-farm/db/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0gGAqFxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,4nPA4KzB,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0gGAqFxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,wkQA6KzB,CAAC"}

package/dist/agent-farm/db/schema.js

@@ -265,6 +265,7 @@ CREATE TABLE IF NOT EXISTS mailbox (
   status TEXT NOT NULL DEFAULT 'held'
     CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),
   reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),  -- why-held; null once delivered
+  detail TEXT,                            -- Issue #1482: the gate verdict's detail behind a busy hold ('user-text' = a human at the line; 'no-region-end'/'no-composer-marker' = the classifier could not verify). Null for non-gate holds and once delivered. NO CHECK on purpose -- SQLite cannot ALTER one in, so migration v18 could not match it and a fresh install would diverge from an upgraded one; the value set is enforced in TypeScript (MailboxGateDetail)
   supersede_key TEXT,                     -- cron-only; null for direct sends
   escalated INTEGER NOT NULL DEFAULT 0,   -- set once escalation age crossed (visibility only)
   not_before INTEGER,                     -- epoch ms; delayed-send due time (Spec 1313 round 3, --delay). null = deliver ASAP; a row is deliverable only when not_before IS NULL OR not_before <= now

package/dist/agent-farm/db/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqF3B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4K5B,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqF3B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6K5B,CAAC"}

package/dist/agent-farm/db/types.d.ts

@@ -84,6 +84,27 @@ export type MailboxStatus = 'held' | 'delivered' | 'superseded' | 'dismissed';
  *   - `no-live-pty` — the recipient agent has no live terminal right now
  */
 export type MailboxReason = 'busy' | 'no-profile' | 'no-live-pty';
+/**
+ * The render gate's classification detail behind a `busy` hold (Issue #1482). Persisted
+ * beside {@link MailboxReason} so every operator surface can tell the two apart:
+ *   - `user-text`           — a draft or menu occupies the composer. A human is at the line;
+ *                             this is the SAFE, intended hold and it clears when they finish.
+ *   - `no-region-end`       — a composer marker with no rule/status line beneath it to bound
+ *                             the region (a partial/mid-repaint frame, or a mirror rendered at
+ *                             dims the real TUI never adopted).
+ *   - `no-composer-marker`  — no recognized marker at all (a wrapper/boot screen, a drifted
+ *                             profile, or an unrenderable frame).
+ * The latter two are the DEFECT class: the classifier could not verify anything, so the mail
+ * will not deliver on its own. `GateVerdict.detail`'s fourth value, `empty`, is never persisted
+ * — a clean verdict delivers the row (and delivery nulls both columns).
+ *
+ * Null for every non-gate hold (`no-live-pty`, `no-profile`) and for the post-classify
+ * token/settle re-holds, so a stale detail can never outlive the verdict that produced it.
+ *
+ * The DB column carries NO CHECK constraint (see `GLOBAL_SCHEMA` / migration v18); this type
+ * is the enforcement.
+ */
+export type MailboxGateDetail = 'user-text' | 'no-region-end' | 'no-composer-marker';
 /**
  * Database row type for the mailbox table (Spec 1313).
  *
@@ -105,6 +126,7 @@ export interface DbMailbox {
     no_enter: number;
     status: MailboxStatus;
     reason: MailboxReason | null;
+    detail: MailboxGateDetail | null;
     supersede_key: string | null;
     escalated: number;
     not_before: number | null;