@north-light/crouter 0.3.154

package/dist/core/__tests__/migration.test.js

@@ -0,0 +1,717 @@
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
+import { canvasDbPath, ensureHome } from '../canvas/paths.js';
+import { CANVAS_EXTENSION_NAMES, customExtensionPaths } from '../canvas/extensions.js';
+import { updateNode } from '../canvas/canvas.js';
+import { spawn, spawnSync } from 'node:child_process';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const RUNTIME_COLUMNS = ['intent', 'pi_pid', 'window', 'tmux_session'];
+const RACE_FIXTURE = join(HERE, 'fixtures', 'metadata-migration-race.ts');
+let home;
+async function waitForPath(path) {
+    for (;;) {
+        if (existsSync(path))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+async function spawnMigrationRace(path, marker) {
+    const child = spawn(process.execPath, ['--import', 'tsx/esm', RACE_FIXTURE, path, marker], { env: { ...process.env, CRTR_HOME: home } });
+    return {
+        done: new Promise((resolve, reject) => {
+            child.on('error', reject);
+            child.on('exit', (code, signal) => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                const detail = signal === null ? `exit ${code}` : `signal ${signal}`;
+                reject(new Error(`migration race fixture failed (${detail})`));
+            });
+        }),
+    };
+}
+function userVersion(db) {
+    return db.prepare('PRAGMA user_version').get()
+        .user_version;
+}
+function nodeColumns(db) {
+    return db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name);
+}
+function migrateToVersion(db, targetVersion) {
+    const current = userVersion(db);
+    for (let version = current; version < targetVersion; version++) {
+        MIGRATIONS[version](db);
+        db.exec(`PRAGMA user_version = ${version + 1}`);
+    }
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-migration-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    // Fresh db + dirs per test for isolation.
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('opening a fresh home migrates to the latest user_version', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+});
+test('a v14 canvas normalizes historical canvas paths while retaining custom launch extras', () => {
+    const metaPath = join(home, 'nodes', 'saved', 'meta.json');
+    mkdirSync(join(home, 'nodes', 'saved'), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify({
+        node_id: 'saved', name: 'saved', created: '2026-01-01T00:00:00.000Z', cwd: '/tmp',
+        kind: 'developer', mode: 'base', lifecycle: 'terminal', status: 'idle',
+        launch: { extensions: [
+                ...CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`),
+                '/plugins/canvas-inbox-watcher.js',
+            ] },
+    }));
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 14);
+    migrate(raw);
+    assert.equal(userVersion(raw), MIGRATIONS.length, 'the retired v14 version advances safely without its runtime');
+    raw.close();
+    const saved = JSON.parse(readFileSync(metaPath, 'utf8'));
+    assert.deepEqual(saved.launch.extensions, ['/plugins/canvas-inbox-watcher.js']);
+});
+test('a v14 migration is protected against concurrent writeback by normal updateNode writes', async () => {
+    const metaPath = join(home, 'nodes', 'saved', 'meta.json');
+    mkdirSync(join(home, 'nodes', 'saved'), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify({
+        node_id: 'saved',
+        name: 'saved',
+        created: '2026-01-01T00:00:00.000Z',
+        cwd: '/tmp',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'idle',
+        launch: {
+            extensions: [...CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`), '/plugins/canvas-inbox-watcher.js'],
+        },
+    }));
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 14);
+    const marker = `${metaPath}.ready`;
+    rmSync(marker, { force: true });
+    const { done } = await spawnMigrationRace(metaPath, marker);
+    await waitForPath(marker);
+    const update = updateNode('saved', { name: 'saved-raced' });
+    assert.equal(update.name, 'saved-raced');
+    await done;
+    const settled = JSON.parse(readFileSync(metaPath, 'utf8'));
+    assert.equal(customExtensionPaths(settled.launch.extensions).length, settled.launch.extensions.length);
+    assert.deepEqual(settled.launch.extensions, ['/plugins/canvas-inbox-watcher.js'], 'concurrent migration + metadata writes cannot restore retired hook prefixes');
+    assert.equal(settled.name, 'saved-raced');
+    raw.close();
+});
+test('a fresh db has the four additive runtime columns', () => {
+    // Build a v0 db by hand: the baseline tables only, user_version 0, no runtime
+    // columns — exactly the shape of the live fleet before this phase.
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id    TEXT PRIMARY KEY,
+      name       TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      mode       TEXT NOT NULL DEFAULT 'base',
+      lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+      status     TEXT NOT NULL DEFAULT 'active',
+      cwd        TEXT NOT NULL,
+      parent     TEXT,
+      created    TEXT NOT NULL
+    );
+    CREATE TABLE edges (
+      type     TEXT NOT NULL,
+      from_id  TEXT NOT NULL,
+      to_id    TEXT NOT NULL,
+      active   INTEGER NOT NULL DEFAULT 1,
+      created  TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id)
+    );
+  `);
+    raw.exec('PRAGMA user_version = 0;');
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created) VALUES (?,?,?,?,?,?)')
+        .run('n1', 'N1', 'general', 'done', '/tmp/work', '2020-01-01T00:00:00Z');
+    raw
+        .prepare('INSERT INTO edges (type, from_id, to_id, created) VALUES (?,?,?,?)')
+        .run('subscribes_to', 'n1', 'n1', '2020-01-01T00:00:00Z');
+    // Precondition: genuinely a v0 db with no runtime columns.
+    assert.equal(userVersion(raw), 0);
+    assert.ok(!nodeColumns(raw).includes('intent'));
+    raw.close();
+    // openDb() runs the migration runner forward.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Runtime columns now exist.
+    const cols = nodeColumns(db);
+    for (const c of RUNTIME_COLUMNS) {
+        assert.ok(cols.includes(c), `expected nodes.${c} after migration`);
+    }
+    // Pre-existing data is intact — no loss, no mutation of existing columns.
+    const row = db
+        .prepare('SELECT node_id, status, cwd FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(row.node_id, 'n1');
+    assert.equal(row.status, 'done');
+    assert.equal(row.cwd, '/tmp/work');
+    const edgeCount = db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+    assert.equal(edgeCount, 1);
+    // The new columns are seeded NULL for the migrated row — nothing observed.
+    const rt = db
+        .prepare('SELECT intent, pi_pid, "window", tmux_session FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(rt['intent'], null);
+    assert.equal(rt['pi_pid'], null);
+    assert.equal(rt['window'], null);
+    assert.equal(rt['tmux_session'], null);
+});
+// --- v4: edges FK ON DELETE CASCADE (the one irreversible rebuild) ------------
+/** Build a hand-rolled db at exactly v3 (baseline tables + the four runtime
+ *  columns, edges with NO foreign key, `user_version = 3`) — the shape the live
+ *  fleet reaches just before v4. Caller seeds it, we close it; the next openDb()
+ *  runs only v4 over it. */
+function buildV3Db() {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id    TEXT PRIMARY KEY,
+      name       TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      mode       TEXT NOT NULL DEFAULT 'base',
+      lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+      status     TEXT NOT NULL DEFAULT 'active',
+      cwd        TEXT NOT NULL,
+      parent     TEXT,
+      created    TEXT NOT NULL,
+      intent       TEXT,
+      pi_pid       INTEGER,
+      window       TEXT,
+      tmux_session TEXT
+    );
+    CREATE TABLE edges (
+      type     TEXT NOT NULL,
+      from_id  TEXT NOT NULL,
+      to_id    TEXT NOT NULL,
+      active   INTEGER NOT NULL DEFAULT 1,
+      created  TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id)
+    );
+    PRAGMA user_version = 3;
+  `);
+    return raw;
+}
+function insertNode(db, id) {
+    db.prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created) VALUES (?,?,?,?,?,?)').run(id, id, 'general', 'active', '/tmp/work', '2020-01-01T00:00:00Z');
+}
+function insertEdge(db, type, from, to) {
+    db.prepare('INSERT INTO edges (type, from_id, to_id, created) VALUES (?,?,?,?)').run(type, from, to, '2020-01-01T00:00:00Z');
+}
+function edgeCount(db) {
+    return db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+}
+test('v4 migrates a db with a pre-existing orphan edge without throwing', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    insertNode(raw, 'n2');
+    insertEdge(raw, 'subscribes_to', 'n1', 'n2'); // non-orphan: both endpoints exist
+    insertEdge(raw, 'spawned_by', 'n1', 'ghost'); // ORPHAN: 'ghost' has no node row
+    assert.equal(userVersion(raw), 3);
+    assert.equal(edgeCount(raw), 2);
+    raw.close();
+    // openDb() runs v4. It must NOT throw on the orphan, and must drop it.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length); // migrated forward to the head
+    // The orphan edge is filtered; the non-orphan edge + its count are preserved.
+    assert.equal(edgeCount(db), 1);
+    const surviving = db
+        .prepare('SELECT type, from_id, to_id FROM edges')
+        .get();
+    assert.equal(surviving.type, 'subscribes_to');
+    assert.equal(surviving.from_id, 'n1');
+    assert.equal(surviving.to_id, 'n2');
+});
+test('v4 leaves the FK live: an edge to a missing node is rejected', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Inserting an edge whose endpoint has no node row now violates the FK.
+    assert.throws(() => db
+        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
+        .run('spawned_by', 'n1', 'missing', 1, '2020-01-01T00:00:00Z'), /FOREIGN KEY|constraint/i);
+    // A fully-valid edge (both endpoints present) still inserts fine.
+    insertNode(db, 'n3');
+    assert.doesNotThrow(() => db
+        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
+        .run('subscribes_to', 'n1', 'n3', 1, '2020-01-01T00:00:00Z'));
+});
+test('v4 deleting a node cascade-deletes its edges', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'a');
+    insertNode(raw, 'b');
+    insertEdge(raw, 'subscribes_to', 'a', 'b');
+    insertEdge(raw, 'spawned_by', 'b', 'a');
+    raw.close();
+    const db = openDb();
+    assert.equal(edgeCount(db), 2);
+    // Delete one endpoint — every edge touching it cascades away.
+    db.prepare('DELETE FROM nodes WHERE node_id = ?').run('a');
+    assert.equal(edgeCount(db), 0);
+});
+test('v4 is idempotent on re-open', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    insertEdge(raw, 'subscribes_to', 'n1', 'n1');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.equal(edgeCount(db), 1);
+    // Re-running migrate() directly is a no-op (gate skips applied steps); the
+    // edges table is NOT rebuilt again.
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.equal(edgeCount(db), 1);
+    // Re-opening from disk is likewise a no-op — the FK + data persist.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    assert.equal(edgeCount(db2), 1);
+});
+function buildV4DbWithLaterColumns() {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id    TEXT PRIMARY KEY,
+      name       TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      mode       TEXT NOT NULL DEFAULT 'base',
+      lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+      status     TEXT NOT NULL DEFAULT 'active',
+      cwd        TEXT NOT NULL,
+      parent     TEXT,
+      created    TEXT NOT NULL,
+      intent       TEXT,
+      pi_pid       INTEGER,
+      window       TEXT,
+      tmux_session TEXT,
+      pane         TEXT,
+      host_kind    TEXT
+    );
+    CREATE TABLE edges (
+      type     TEXT NOT NULL,
+      from_id  TEXT NOT NULL,
+      to_id    TEXT NOT NULL,
+      active   INTEGER NOT NULL DEFAULT 1,
+      created  TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id)
+    );
+    PRAGMA user_version = 4;
+  `);
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created, pane, host_kind) VALUES (?,?,?,?,?,?,?,?)')
+        .run('stale', 'Stale', 'general', 'idle', '/tmp/work', '2020-01-01T00:00:00Z', '%9', 'broker');
+    return raw;
+}
+test('bug #99: a stale v4 db with later columns already present migrates cleanly', () => {
+    const raw = buildV4DbWithLaterColumns();
+    assert.equal(userVersion(raw), 4);
+    assert.equal(nodeColumns(raw).includes('pane'), true, 'precondition: pane already exists even though user_version is stale');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    const cols = nodeColumns(db);
+    assert.ok(cols.includes('pane'), 'pane survives the migration');
+    assert.ok(cols.includes('host_kind'), 'host_kind survives the migration');
+    const row = db
+        .prepare('SELECT pane, host_kind FROM nodes WHERE node_id = ?')
+        .get('stale');
+    assert.equal(row.pane, '%9');
+    assert.equal(row.host_kind, 'broker');
+});
+// --- v22: legacy schedules → crons ------------------------------------------
+function buildV21Db() {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 21);
+    insertNode(raw, 'owner');
+    insertNode(raw, 'target');
+    raw.prepare('UPDATE nodes SET profile_id = ? WHERE node_id = ?').run('work', 'owner');
+    return raw;
+}
+function insertLegacySchedule(db, row) {
+    db.prepare(`
+    INSERT INTO triggers (
+      trigger_id, owner_id, node_id, action, action_mode, trigger_type,
+      fire_at, recur, payload, when_script, eval_every, next_eval_at,
+      timeout_at, eval_state, created
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'idle', '2020-01-01T00:00:00Z')
+  `).run(row.id, row.ownerId ?? 'owner', row.nodeId, row.action, row.actionMode, row.timing, row.fireAt ?? null, row.recur ?? null, row.payload === null ? null : JSON.stringify(row.payload), row.whenScript ?? null, row.evalEvery ?? null, row.nextEvalAt ?? null, row.timeoutAt ?? null);
+}
+test('v22 converts existing schedules into self-contained crons and removes the retired table', () => {
+    const raw = buildV21Db();
+    insertLegacySchedule(raw, {
+        id: 'scheduled-message',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2026-01-01T00:00:00.000Z',
+        payload: { body: 'check CI', label: 'CI check', tier: 'urgent' },
+    });
+    insertLegacySchedule(raw, {
+        id: 'fresh-revive',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'fresh_revive',
+        timing: 'at',
+        fireAt: '2026-01-02T00:00:00.000Z',
+        payload: null,
+    });
+    insertLegacySchedule(raw, {
+        id: 'conditional-message',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'when',
+        payload: { body: 'ready at last', label: 'ci watch' },
+        whenScript: 'test -f ready',
+        evalEvery: JSON.stringify({ every: '5m' }),
+        nextEvalAt: '2026-01-03T00:00:00.000Z',
+        timeoutAt: '2026-01-04T00:00:00.000Z',
+    });
+    insertLegacySchedule(raw, {
+        id: 'armed-deadline',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'deadline_message',
+        timing: 'at',
+        fireAt: '2026-01-06T00:00:00.000Z',
+        payload: { body: 'timed out — decide without me' },
+    });
+    insertLegacySchedule(raw, {
+        id: 'recurring-birth',
+        nodeId: null,
+        action: 'new',
+        actionMode: 'node_birth',
+        timing: 'every',
+        fireAt: '2026-01-05T00:00:00.000Z',
+        recur: JSON.stringify({ every: '6h' }),
+        payload: { kind: 'general', mode: 'base', cwd: '/tmp/work', prompt: 'go', parent: 'owner' },
+    });
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name);
+    assert.ok(!tables.includes('triggers'));
+    const cron = (id) => db.prepare('SELECT * FROM crons WHERE cron_id = ?').get(id);
+    const message = cron('scheduled-message');
+    assert.equal(message.name, 'CI check');
+    assert.equal(message.anchor_node, 'target');
+    assert.equal(message.cwd, '/tmp/work');
+    assert.equal(message.profile, 'work');
+    assert.equal(message.tier, 'urgent');
+    assert.match(message.command, /crtr node message send --to 'target' --tier 'urgent'/);
+    assert.match(message.command, /check CI/);
+    const revive = cron('fresh-revive');
+    assert.equal(revive.command, "crtr node lifecycle revive 'target' --fresh");
+    const conditional = cron('conditional-message');
+    assert.equal(conditional.cancel_on_wake, 0, 'only a deadline message is cancel-on-wake');
+    assert.equal(conditional.recur, JSON.stringify({ every: '5m' }));
+    assert.equal(conditional.expires_at, '2026-01-04T00:00:00.000Z');
+    assert.match(conditional.command, /test -f ready/);
+    // The action's exit status must reach the cron, so the self-cancel is CHAINED
+    // off it rather than run unconditionally on its own line. (What the chain
+    // actually DOES when run is proved by execution below, not by this shape.)
+    assert.match(conditional.command, /\n} && crtr cron cancel "\$CRTR_CRON_ID"/);
+    const deadline = cron('armed-deadline');
+    assert.equal(deadline.cancel_on_wake, 1, 'a deadline message is cancelled by any wake');
+    assert.equal(deadline.tier, 'urgent', 'a deadline message is forced urgent');
+    assert.equal(deadline.anchor_node, 'target');
+    assert.match(deadline.command, /--tier 'urgent'/);
+    const birth = cron('recurring-birth');
+    assert.equal(birth.anchor_node, null);
+    assert.equal(birth.recur, JSON.stringify({ every: '6h' }));
+    assert.match(birth.command, /crtr node new --kind 'general'/);
+    assert.match(birth.command, /go/);
+});
+// The v22 migration runs on EVERY openDb(), so it must never fail on data shape:
+// a throw would make every crtr process unable to open the canvas forever. These
+// cases are all shapes the retired schema declared legal.
+function insertNodeAt(db, id, cwd, created, parent) {
+    db.prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, parent, created) VALUES (?,?,?,?,?,?,?)').run(id, id, 'general', 'active', cwd, parent, created);
+}
+test('v22 converts the legal edge rows and records the ones it cannot express', () => {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    migrateToVersion(raw, 21);
+    insertNodeAt(raw, 'ambient', '/tmp/ambient', '2019-01-01T00:00:00Z', null);
+    insertNodeAt(raw, 'owner', '/tmp/work', '2020-01-01T00:00:00Z', 'ambient');
+    insertNodeAt(raw, 'target', '/tmp/work', '2020-01-01T00:00:00Z', 'ambient');
+    // A crashed-then-pruned armer: `owner_id` deliberately carries no FK, so this
+    // detached row is expected, not corrupt.
+    insertLegacySchedule(raw, {
+        id: 'pruned-owner',
+        ownerId: 'ghost',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2026-02-01T00:00:00.000Z',
+        payload: { body: 'still due' },
+    });
+    // Already past its fire time: converts, then the cron expiry pass reaps it.
+    insertLegacySchedule(raw, {
+        id: 'expired',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2020-06-01T00:00:00.000Z',
+        payload: { body: 'long overdue' },
+    });
+    // `until` is one-shot: a fire time and no recurrence.
+    insertLegacySchedule(raw, {
+        id: 'one-shot-until',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'until',
+        fireAt: '2026-03-01T00:00:00.000Z',
+        payload: { body: 'deadline policy' },
+    });
+    // A body-less predicate: the retired daemon sent the gate's stdout as the body.
+    insertLegacySchedule(raw, {
+        id: 'gate-stdout-body',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'when',
+        payload: { label: 'ci watch' },
+        whenScript: 'gh run view --json status',
+        evalEvery: JSON.stringify({ every: '5m' }),
+        nextEvalAt: '2026-01-03T00:00:00.000Z',
+        timeoutAt: '2026-01-04T00:00:00.000Z',
+    });
+    // `payload` was nullable: a NULL payload must not fail the open.
+    insertLegacySchedule(raw, {
+        id: 'null-payload',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2026-04-01T00:00:00.000Z',
+        payload: null,
+    });
+    // Two deadlines for one node: illegal under the retired unique index (dropped
+    // here to seed the drifted shape), so only drifted data reaches here. INSERT OR REPLACE would silently evict the first;
+    // the loser must be recorded instead.
+    raw.exec('DROP INDEX idx_triggers_deadline');
+    insertLegacySchedule(raw, {
+        id: 'deadline-first',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'deadline_message',
+        timing: 'at',
+        fireAt: '2026-05-01T00:00:00.000Z',
+        payload: { body: 'first deadline' },
+    });
+    insertLegacySchedule(raw, {
+        id: 'deadline-rival',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'deadline_message',
+        timing: 'at',
+        fireAt: '2026-05-02T00:00:00.000Z',
+        payload: { body: 'rival deadline' },
+    });
+    // Genuinely unconvertible: skipped and recorded, never fatal.
+    insertLegacySchedule(raw, {
+        id: 'unknown-timing',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'whenever',
+        payload: { body: 'nope' },
+    });
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length, 'the schema advances despite the unconvertible row');
+    const cron = (id) => db.prepare('SELECT * FROM crons WHERE cron_id = ?').get(id);
+    const pruned = cron('pruned-owner');
+    assert.equal(pruned.cwd, '/tmp/ambient', 'a pruned armer falls back to the ambient root cwd');
+    assert.equal(pruned.profile, null);
+    assert.equal(cron('expired').fire_at, '2020-06-01T00:00:00.000Z');
+    assert.equal(cron('one-shot-until').recur, null);
+    const gated = cron('gate-stdout-body');
+    assert.match(gated.command, /CRTR_GATE_STDOUT="\$\(/);
+    assert.match(gated.command, /printf '%s\\n' "\$CRTR_GATE_STDOUT" \| crtr node message send --to 'target'/);
+    assert.match(cron('null-payload').command, /no body was recorded/);
+    assert.equal(cron('unknown-timing'), undefined, 'the unconvertible row is dropped, not fatal');
+    const ledger = db.prepare('SELECT value FROM canvas_meta WHERE key = ?').get('migration.v22.skipped');
+    assert.deepEqual(JSON.parse(ledger.value).map((entry) => entry.trigger_id).sort(), ['deadline-rival', 'unknown-timing'], 'both the unconvertible row and the evicted duplicate deadline are named');
+    assert.notEqual(cron('deadline-first'), undefined, 'the first deadline survives the duplicate');
+});
+test('v22 re-run over already-converted crons converges instead of colliding on the primary key', () => {
+    const raw = buildV21Db();
+    insertLegacySchedule(raw, {
+        id: 'scheduled-message',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2026-01-01T00:00:00.000Z',
+        payload: { body: 'check CI' },
+    });
+    // What an interrupted pre-fix run left behind: the cron row committed while
+    // `user_version` stayed at 21, so the next open re-runs the step.
+    raw.prepare(`
+    INSERT INTO crons (cron_id, name, created_by, command, fire_at, cwd, sink, created, updated)
+    VALUES ('scheduled-message', 'stale', 'owner', 'echo stale', '2026-01-01T00:00:00.000Z', '/tmp/work', '{}', '2020-01-01T00:00:00Z', '2020-01-01T00:00:00Z')
+  `).run();
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    const row = db.prepare('SELECT command FROM crons WHERE cron_id = ?').get('scheduled-message');
+    assert.match(row.command, /crtr node message send --to 'target'/, 'the re-run replaces the half-written row');
+    // Opening again is a plain no-op at the latest version.
+    closeDb();
+    assert.equal(userVersion(openDb()), MIGRATIONS.length);
+});
+test('a failing migration step rolls back its writes and leaves user_version untouched', () => {
+    const raw = buildV21Db();
+    insertLegacySchedule(raw, {
+        id: 'scheduled-message',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'at',
+        fireAt: '2026-01-01T00:00:00.000Z',
+        payload: { body: 'check CI' },
+    });
+    insertLegacySchedule(raw, {
+        id: 'unknown-timing',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'whenever',
+        payload: { body: 'nope' },
+    });
+    // Break the step mid-flight: the skip ledger has nowhere to land, so v22
+    // throws AFTER it has already inserted the convertible row.
+    raw.exec('DROP TABLE canvas_meta');
+    assert.throws(() => migrate(raw));
+    assert.equal(userVersion(raw), 21, 'the version stays at the last fully-applied step');
+    const crons = raw.prepare('SELECT COUNT(*) AS n FROM crons').get().n;
+    assert.equal(crons, 0, 'every write from the failed step rolled back');
+    const triggers = raw.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='triggers'").get();
+    assert.notEqual(triggers, undefined, 'the retired table survives so the step can be retried');
+    raw.close();
+});
+test('v22 recovers a db wedged by an interrupted pre-atomicity run', () => {
+    const raw = buildV21Db();
+    // The wedge the old bare-migration path could produce: crons committed, the
+    // retired table already dropped, `user_version` never bumped past 21.
+    raw.prepare(`
+    INSERT INTO crons (cron_id, name, created_by, command, fire_at, cwd, sink, created, updated)
+    VALUES ('half-written', 'half', 'owner', 'echo hi', '2026-01-01T00:00:00.000Z', '/tmp/work', '{}', '2020-01-01T00:00:00Z', '2020-01-01T00:00:00Z')
+  `).run();
+    raw.exec('DROP TABLE triggers');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length, 'the schema advances rather than failing every open');
+    assert.notEqual(db.prepare('SELECT 1 FROM crons WHERE cron_id = ?').get('half-written'), undefined);
+});
+// The generated cron scripts are the migration's real product, so the M4
+// contract (a failed action must NOT self-cancel and must exit nonzero) is
+// proved by RUNNING them under bash with a stub `crtr` on PATH. A string match
+// cannot see a heredoc that swallows the chained cancel; `bash -n` cannot either.
+function runMigratedScript(script, opts) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-cron-script-'));
+    const bin = join(dir, 'bin');
+    mkdirSync(bin);
+    const log = join(dir, 'crtr.log');
+    writeFileSync(join(bin, 'crtr'), `#!/bin/sh\nprintf 'ARGS: %s\\n' "$*" >> "${log}"\nif [ "$1" = 'node' ]; then { printf 'BODY<'; cat; printf '>\\n'; } >> "${log}"; fi\nexit \${CRTR_STUB_EXIT:-0}\n`, { mode: 0o755 });
+    if (opts.gateReady === true)
+        writeFileSync(join(dir, 'ready'), '');
+    const result = spawnSync('bash', ['-c', script], {
+        cwd: dir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            PATH: `${bin}:${process.env['PATH'] ?? ''}`,
+            CRTR_CRON_ID: 'conditional-message',
+            CRTR_STUB_EXIT: String(opts.crtrExit ?? 0),
+        },
+    });
+    const written = existsSync(log) ? readFileSync(log, 'utf8') : '';
+    rmSync(dir, { recursive: true, force: true });
+    return { code: result.status ?? -1, log: written };
+}
+test('a migrated predicate script delivers its exact body and self-cancels only when the action succeeds', () => {
+    const raw = buildV21Db();
+    insertLegacySchedule(raw, {
+        id: 'conditional-message',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'when',
+        payload: { body: 'ready at last' },
+        whenScript: 'test -f ready',
+        evalEvery: JSON.stringify({ every: '5m' }),
+        nextEvalAt: '2026-01-03T00:00:00.000Z',
+        timeoutAt: '2026-01-04T00:00:00.000Z',
+    });
+    insertLegacySchedule(raw, {
+        id: 'gate-stdout-body',
+        nodeId: 'target',
+        action: 'msg',
+        actionMode: 'inbox_message',
+        timing: 'when',
+        payload: {},
+        whenScript: 'test -f ready && echo "build 1234 is green"',
+        evalEvery: JSON.stringify({ every: '5m' }),
+        nextEvalAt: '2026-01-03T00:00:00.000Z',
+        timeoutAt: '2026-01-04T00:00:00.000Z',
+    });
+    raw.close();
+    const db = openDb();
+    const script = (id) => db.prepare('SELECT command FROM crons WHERE cron_id = ?').get(id).command;
+    const stored = script('conditional-message');
+    const satisfied = runMigratedScript(stored, { gateReady: true });
+    assert.equal(satisfied.code, 0);
+    assert.match(satisfied.log, /BODY<ready at last\n>/, 'the heredoc body is delivered verbatim');
+    assert.doesNotMatch(satisfied.log, /CRTR_MIGRATED/, 'no heredoc delimiter leaks into the body');
+    assert.match(satisfied.log, /ARGS: cron cancel conditional-message/, 'a successful action self-cancels');
+    const failed = runMigratedScript(stored, { gateReady: true, crtrExit: 3 });
+    assert.notEqual(failed.code, 0, 'a failed action propagates a nonzero exit to the on-failure path');
+    assert.doesNotMatch(failed.log, /cron cancel/, 'a failed action leaves the cron armed');
+    const unsatisfied = runMigratedScript(stored, { gateReady: false });
+    assert.equal(unsatisfied.code, 0, 'an unsatisfied gate is a clean no-op');
+    assert.equal(unsatisfied.log, '', 'nothing is enacted while the gate is closed');
+    const fromGate = runMigratedScript(script('gate-stdout-body'), { gateReady: true });
+    assert.equal(fromGate.code, 0);
+    assert.match(fromGate.log, /BODY<build 1234 is green\n>/, "a body-less predicate sends the gate's stdout");
+    assert.match(fromGate.log, /ARGS: cron cancel/);
+});