@north-light/crouter 0.3.179 → 0.3.181

package/dist/core/__tests__/cron-held-settlement.test.js

@@ -0,0 +1,222 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/cron-held-settlement.test.ts
+//
+// The owed-gate (exit 75) settlement branch: a scheduled run exiting
+// EX_TEMPFAIL declares "this occurrence is owed but not currently eligible."
+// The row is PARKED (held=1, occurrence not spent) instead of disposed — no
+// failure, no escalation, no delivery, no on-change hash, no one-shot
+// consumption — and a poke (`pokeHeldCrons`) re-dues every held active row
+// now. These pin the branch's truth table: the exact class of scheduling
+// defect that otherwise fails silently weeks later.
+import { after, afterEach, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { closeDb, openDb } from '../canvas/db.js';
+import { armCron, cancelCron, getCron, listCronRuns, pokeHeldCrons, setCronState, } from '../canvas/crons.js';
+import { executeCron, runDueCrons } from '../../daemon/cron-run.js';
+const HELD_DELIVERED = 'deferred (exit 75) — held for poke';
+const HELD_FAR_FUTURE = '9999-12-31T23:59:59.999Z';
+let home;
+let realHome;
+function arm(overrides) {
+    armCron({
+        name: overrides.cron_id,
+        created_by: null,
+        fire_at: new Date(Date.now() - 1_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: null,
+        cancel_on_wake: false,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'silent',
+        sink: '{}',
+        tier: 'normal',
+        ...overrides,
+    });
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-cron-held-'));
+    realHome = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+});
+afterEach(() => {
+    closeDb();
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (realHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = realHome;
+});
+test('a recurring exit-75 run parks: held, backstop untouched, no disposition', async () => {
+    // on-change makes the skipped disposition observable: were the branch to
+    // fall through, a failed run would escalate (pause + node) and the hash
+    // bookkeeping would write last_output_hash.
+    arm({
+        cron_id: 'gate-recurring',
+        command: 'exit 75',
+        recur: JSON.stringify({ every: '1h' }),
+        on_output: 'on-change',
+    });
+    const settlements = runDueCrons(Date.now());
+    assert.equal(settlements.length, 1, 'the due gated run was admitted');
+    // The pre-run advance already wrote the natural next slot — the backstop.
+    const backstop = getCron('gate-recurring').fire_at;
+    await Promise.all(settlements);
+    const row = getCron('gate-recurring');
+    assert.equal(row.held, true);
+    assert.equal(row.fire_at, backstop, 'settlement must not touch the pre-advanced slot');
+    assert.equal(row.state, 'active', 'held is not a failure — no pause, no escalation');
+    assert.equal(row.run_state, 'idle');
+    assert.equal(row.last_output_hash, null, 'on-change bookkeeping is skipped for a held run');
+    const runs = listCronRuns('gate-recurring');
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].exit_code, 75);
+    assert.equal(runs[0].delivered, HELD_DELIVERED);
+    cancelCron('gate-recurring');
+});
+test('a held one-shot without expires is retained at the far-future backstop', async () => {
+    arm({ cron_id: 'gate-oneshot', command: 'exit 75' });
+    await Promise.all(runDueCrons(Date.now()));
+    const row = getCron('gate-oneshot');
+    assert.notEqual(row, null, 'the occurrence is not spent — the one-shot is not consumed');
+    assert.equal(row.held, true);
+    assert.equal(row.fire_at, HELD_FAR_FUTURE, 'poke-only: never due on the clock');
+    cancelCron('gate-oneshot');
+});
+test('a held one-shot with --expires waits at expiry, then is deleted unfired', async () => {
+    const expiresAt = new Date(Date.now() + 1_000).toISOString();
+    arm({ cron_id: 'gate-oneshot-expires', command: 'exit 75', expires_at: expiresAt });
+    await Promise.all(runDueCrons(Date.now()));
+    const row = getCron('gate-oneshot-expires');
+    assert.equal(row.held, true);
+    assert.equal(row.fire_at, expiresAt, 'expiry bounds the wait');
+    // Past the bound: expiry runs before due processing, so the row is deleted
+    // without ever firing blind at its expiry instant.
+    const afterExpiry = runDueCrons(new Date(expiresAt).getTime() + 1_000);
+    assert.equal(afterExpiry.length, 0, 'the expired row never fired');
+    await Promise.all(afterExpiry);
+    assert.equal(getCron('gate-oneshot-expires'), null, 'deleted unfired at expiry');
+});
+test('a poke re-dues held active rows, skips paused ones, stamps every row', async () => {
+    arm({ cron_id: 'poke-active', command: 'exit 75', recur: JSON.stringify({ every: '1h' }) });
+    await Promise.all(runDueCrons(Date.now()));
+    arm({ cron_id: 'poke-paused', command: 'exit 75', recur: JSON.stringify({ every: '1h' }) });
+    await Promise.all(runDueCrons(Date.now()));
+    setCronState('poke-paused', 'paused');
+    const pausedBackstop = getCron('poke-paused').fire_at;
+    arm({ cron_id: 'poke-ordinary', command: 'exit 0', fire_at: new Date(Date.now() + 3_600_000).toISOString() });
+    const nowIso = new Date().toISOString();
+    assert.equal(pokeHeldCrons(nowIso), 1, 'only the held ACTIVE row unparks');
+    const active = getCron('poke-active');
+    assert.equal(active.held, false);
+    assert.equal(active.fire_at, nowIso, 'unparked: due now');
+    const paused = getCron('poke-paused');
+    assert.equal(paused.held, true, 'pause is user-owned — a poke never unparks a paused row');
+    assert.equal(paused.fire_at, pausedBackstop);
+    for (const id of ['poke-active', 'poke-paused', 'poke-ordinary']) {
+        assert.equal(getCron(id).last_poke_at, nowIso, `last_poke_at stamps every row (${id})`);
+        cancelCron(id);
+    }
+});
+test('a poke never unparks a row whose gate check is in flight', async () => {
+    // A held recurring row at its backstop slot: due selection pre-advances
+    // fire_at, then leases the run. A poke landing mid-run must not touch the
+    // row — unparking would overwrite the advanced slot with `now`, and a
+    // PASSING gate (ordinary settlement only clears `held`) would then fire a
+    // second time on the next tick.
+    arm({ cron_id: 'poke-inflight', command: 'sleep 0.3; exit 0', recur: JSON.stringify({ every: '1h' }) });
+    openDb().prepare('UPDATE crons SET held = 1 WHERE cron_id = ?').run('poke-inflight');
+    const settlements = runDueCrons(Date.now());
+    assert.equal(settlements.length, 1, 'the held row past its backstop is due');
+    const advanced = getCron('poke-inflight').fire_at;
+    await delay(50);
+    const nowIso = new Date().toISOString();
+    assert.equal(pokeHeldCrons(nowIso), 0, 'a leased row is stamped, never unparked');
+    await Promise.all(settlements);
+    const row = getCron('poke-inflight');
+    assert.equal(row.held, false, 'the passing gate resolved — ordinary settlement clears held');
+    assert.equal(row.fire_at, advanced, 'the pre-advanced slot survives the poke — no double fire');
+    assert.equal(row.last_poke_at, nowIso);
+    cancelCron('poke-inflight');
+});
+test('a row paused mid-run parks on exit 75 even when a poke stamped it', async () => {
+    // Pause lands while the gate check is in flight, then a poke stamps every
+    // row (skipping the paused row's unpark). The settling 75 must PARK, not
+    // re-due: a re-due would leave a past-due unheld row that `cron resume`
+    // fires blind even though its gate never passed.
+    arm({ cron_id: 'paused-midrun', command: 'sleep 0.3; exit 75', recur: JSON.stringify({ every: '1h' }) });
+    const settlements = runDueCrons(Date.now());
+    assert.equal(settlements.length, 1);
+    const backstop = getCron('paused-midrun').fire_at;
+    await delay(50);
+    setCronState('paused-midrun', 'paused');
+    pokeHeldCrons(new Date().toISOString());
+    await Promise.all(settlements);
+    const row = getCron('paused-midrun');
+    assert.equal(row.state, 'paused');
+    assert.equal(row.held, true, 'paused mid-run parks — resume re-checks the gate, never fires it blind');
+    assert.equal(row.fire_at, backstop, 'the pre-advanced backstop survives');
+    cancelCron('paused-midrun');
+});
+test('a poke landing mid-run re-dues the settling row instead of parking it (F2)', async () => {
+    arm({ cron_id: 'gate-midrun-poke', command: 'sleep 0.3; exit 75' });
+    const settlement = executeCron(getCron('gate-midrun-poke'), { outOfBand: false });
+    await delay(50);
+    // The gate check is in flight: the poke's WHERE held=1 misses it.
+    assert.equal(pokeHeldCrons(new Date().toISOString()), 0);
+    const record = await settlement;
+    assert.equal(record?.exit_code, 75);
+    const row = getCron('gate-midrun-poke');
+    assert.equal(row.held, false, 're-dued, not parked — the poke is not lost');
+    assert.notEqual(row.fire_at, HELD_FAR_FUTURE);
+    assert.ok(Math.abs(new Date(row.fire_at).getTime() - Date.now()) < 5_000, `re-dued to settle time, got ${row.fire_at}`);
+    cancelCron('gate-midrun-poke');
+});
+test('an out-of-band exit 75 reports the result and never touches scheduling state (F3)', async () => {
+    const futureFire = new Date(Date.now() + 3_600_000).toISOString();
+    arm({ cron_id: 'oob-75', command: 'exit 75', recur: JSON.stringify({ every: '1h' }), fire_at: futureFire });
+    const record = await executeCron(getCron('oob-75'), { outOfBand: true });
+    assert.equal(record?.exit_code, 75);
+    assert.notEqual(record?.delivered, HELD_DELIVERED, 'a manual verification is not an owed gate');
+    const row = getCron('oob-75');
+    assert.equal(row.held, false);
+    assert.equal(row.fire_at, futureFire);
+    cancelCron('oob-75');
+});
+test('a timeout kill is a real failure even when the command would exit 75 (F3)', async () => {
+    arm({
+        cron_id: 'timeout-75',
+        command: 'sleep 3; exit 75',
+        recur: JSON.stringify({ every: '1h' }),
+        run_timeout_s: 1,
+    });
+    await Promise.all(runDueCrons(Date.now()));
+    const row = getCron('timeout-75');
+    assert.equal(row.held, false, 'a timed-out run takes the failure path, never the held branch');
+    const runs = listCronRuns('timeout-75');
+    assert.equal(runs[0].exit_code, -1);
+    assert.notEqual(runs[0].delivered, HELD_DELIVERED);
+    cancelCron('timeout-75');
+});
+test('an ordinary scheduled settlement clears held (the backstop run resolves the gate)', async () => {
+    arm({ cron_id: 'clear-held', command: 'exit 0', recur: JSON.stringify({ every: '1h' }) });
+    // Simulate a parked row whose backstop slot has arrived: held rows are
+    // deliberately NOT filtered out of the due query.
+    openDb().prepare('UPDATE crons SET held = 1 WHERE cron_id = ?').run('clear-held');
+    const settlements = runDueCrons(Date.now());
+    assert.equal(settlements.length, 1, 'a held row past its backstop is due');
+    await Promise.all(settlements);
+    assert.equal(getCron('clear-held').held, false, 'the resolved gate unparks the row');
+    cancelCron('clear-held');
+});

package/dist/core/__tests__/helpers/harness.js

@@ -103,9 +103,8 @@ function cleanBaseEnv() {
             e[k] = v;
     for (const k of CANVAS_ENV_KEYS)
         delete e[k];
-    // Contain per-invocation bootstrap + auto-update side effects (they write to
+    // Contain per-invocation scope-init + auto-update side effects (they write to
     // ~/.crouter / ~/.claude / ~/.pi, NOT under CRTR_HOME — HOME is contained too).
-    e['CRTR_NO_BOOTSTRAP'] = '1';
     e['CRTR_NO_AUTO_UPDATE'] = '1';
     e['CRTR_NO_EXPORTS'] = '1';
     e['CRTR_NO_AUTO_INIT'] = '1';

package/dist/core/__tests__/phase4-review-store.test.js

@@ -29,6 +29,7 @@ function row(overrides = {}) {
         created: '2026-01-01T00:00:00.000Z',
         captured_at: '2026-01-01T00:00:00.000Z',
         opened_at: null,
+        submit_requested_at: null,
         output_path: null,
         subtitle: null,
         approved_at: null,

package/dist/core/__tests__/serial/command-plugins.test.js

@@ -30,6 +30,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverCommandContributions, effectiveCommandPlugins, validatePluginCommands, } from '../../command-plugins/discovery.js';
 import { composeExternalSubtrees, adaptPluginContributions } from '../../command-plugins/compose.js';
+import { collectHelpAddenda } from '../../command-plugins/help-addenda.js';
 import { resolveCommandRegistry } from '../../command-manifests/registry.js';
 import { defineRoot } from '../../command.js';
 import { renderRoot, renderBranch, renderLeafArgv } from '../../help.js';
@@ -379,7 +380,7 @@ describe('end-to-end CLI invocation', () => {
         resetScopeCache();
         return execFileSync(process.execPath, [cli, ...args], {
             cwd: emptyStart,
-            env: { ...process.env, HOME: home, CRTR_NO_BOOTSTRAP: '1', CRTR_FRONT_DOOR: '' },
+            env: { ...process.env, HOME: home, CRTR_FRONT_DOOR: '' },
             encoding: 'utf8',
         });
     };
@@ -511,6 +512,92 @@ describe('typed validation issues', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// Plugin help addenda — the append-only product-guidance seam. An addendum
+// that quietly stops rendering is exactly the silent-absence class: pin that a
+// valid entry survives validation and is collected attributed, and that the
+// STRICT gates (install/bundle, which pass coreCommandPaths) reject a key
+// naming no core command path while the tolerant compose path still mounts the
+// plugin's tree. The help-render lookup receives the gate's exact inputs, so a
+// map rejected at ingress renders nothing — render never disagrees with the
+// install report.
+// ---------------------------------------------------------------------------
+describe('plugin help addenda', () => {
+    const gate = (paths) => ({
+        reservedCoreNames: RESERVED,
+        coreCommandPaths: new Set(paths),
+    });
+    test('a helpAddenda entry survives validation and is collected attributed to its plugin', () => {
+        const m = commandsJson();
+        m['helpAddenda'] = { cron: 'Gate on the device: exit 75 parks the occurrence.' };
+        installPlugin(userRoot, 'northlight-fixture', { manifest: m });
+        resetScopeCache();
+        const p = listInstalledPluginsInRoot('user', userRoot).find((x) => x.name === 'northlight-fixture');
+        const v = validatePluginCommands(p, RESERVED);
+        assert.equal(v.issues.length, 0, JSON.stringify(v.issues));
+        assert.deepEqual(v.manifest?.helpAddenda, { cron: 'Gate on the device: exit 75 parks the occurrence.' });
+        // The help-render lookup: attributed, and empty for an unaddended path.
+        assert.deepEqual(collectHelpAddenda('cron', gate(['cron', 'node']), emptyStart), [
+            { plugin: 'northlight-fixture', text: 'Gate on the device: exit 75 parks the occurrence.' },
+        ]);
+        assert.deepEqual(collectHelpAddenda('node', gate(['cron', 'node']), emptyStart), []);
+    });
+    test('a key naming no core command path fails the strict gate and renders nothing, even beside a valid key', () => {
+        const m = commandsJson();
+        m['helpAddenda'] = {
+            cron: 'a valid target beside the typo',
+            'cronn add': 'a typo that must fail at install, never silently at render',
+        };
+        installPlugin(userRoot, 'p', { manifest: m });
+        resetScopeCache();
+        const p = listInstalledPluginsInRoot('user', userRoot).find((x) => x.name === 'p');
+        // Strict (install/bundle/doctor): the typo is a typed issue, zero contributions.
+        const strict = validatePluginCommands(p, RESERVED, new Set(['cron', 'cron add']));
+        assert.ok(strict.issues.some((i) => i.code === 'command_help_addendum_invalid'), JSON.stringify(strict.issues));
+        assert.equal(strict.contributions.length, 0);
+        assert.equal(strict.manifest, undefined);
+        // Tolerant (runtime compose): an already-installed plugin's typo'd addendum
+        // must not drop its whole command tree.
+        const tolerant = validatePluginCommands(p, RESERVED);
+        assert.equal(tolerant.issues.length, 0, JSON.stringify(tolerant.issues));
+        assert.equal(tolerant.contributions.length, 1);
+        // The render lookup reproduces the GATE verdict, not the compose one: the
+        // rejected map contributes nothing — including its valid key — so render
+        // can never show what the install report said was rejected.
+        assert.deepEqual(collectHelpAddenda('cron', gate(['cron', 'cron add']), emptyStart), []);
+    });
+    test('an installed addendum renders through the real help path as an attributed block', async () => {
+        const m = commandsJson();
+        m['helpAddenda'] = { cron: 'ADDENDUM RENDERED THROUGH THE REAL HELP PATH' };
+        installPlugin(userRoot, 'northlight-fixture', { manifest: m });
+        resetScopeCache();
+        // Pin the durable wiring, not the lookup: runCli → renderNodeWithAddenda →
+        // collectHelpAddenda → <plugin-help> serialization. This is the exact
+        // silent-absence class — the dynamic import or the append could regress
+        // with every lookup-level assertion still green.
+        const { resolveRoot } = await import('../../../build-root.js');
+        const { runCli } = await import('../../command.js');
+        const root = await resolveRoot('cron');
+        const chunks = [];
+        const realWrite = process.stdout.write.bind(process.stdout);
+        const realCwd = process.cwd();
+        process.chdir(emptyStart); // startDir with no project scope — user scope is the fixture HOME
+        process.stdout.write = ((chunk) => {
+            chunks.push(String(chunk));
+            return true;
+        });
+        try {
+            await runCli(root, ['node', 'crtr', 'cron', '-h']);
+        }
+        finally {
+            process.stdout.write = realWrite;
+            process.chdir(realCwd);
+        }
+        const out = chunks.join('');
+        assert.ok(out.includes('<plugin-help plugin="northlight-fixture">'), out.slice(-400));
+        assert.ok(out.includes('ADDENDUM RENDERED THROUGH THE REAL HELP PATH'), out.slice(-400));
+    });
+});
+// ---------------------------------------------------------------------------
 // Lifecycle surfaces — the validator's verdict must reach the caller WITHOUT
 // executing the plugin binary, and a cross-plugin top-level collision must not
 // read as a pass on any claimant.

package/dist/core/__tests__/session-model.test.js

@@ -98,11 +98,13 @@ test('a welcome is a COMPLETE catch-up: a re-welcome drops a dead broker s level
     const s0 = fold(initialSessionState(), [
         welcome(),
         { type: 'extension_ui_request', id: 'u1', method: 'setStatus', statusKey: 'gone', statusText: 'stale' },
-        { type: 'queue_update', steering: ['one'], followUp: [] },
+        { type: 'queue_update', steering: ['one', 'two'], followUp: [], steeringIds: ['id-1'] },
     ]);
     assert.equal(s0.display.statuses['gone'], 'stale');
-    assert.deepEqual(s0.queued, ['one']);
-    assert.equal(s0.engine?.pendingMessageCount, 1);
+    // Broker-enriched ids zip positionally; a position without one (older broker,
+    // short array) still renders as a bare-text entry.
+    assert.deepEqual(s0.queued, [{ id: 'id-1', text: 'one' }, { text: 'two' }]);
+    assert.equal(s0.engine?.pendingMessageCount, 2);
     // A fresh broker (post-revive) welcomes with its OWN levels and an empty queue,
     // and emits no queue_update to overwrite the panel — so the welcome must.
     const s1 = reduce(s0, welcome());

package/dist/core/bootstrap.d.ts

@@ -1,5 +1 @@
-export declare const OFFICIAL_MARKETPLACE_NAME = "crouter-official-marketplace";
-export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs/crouter-official-marketplace.git";
-export declare const OFFICIAL_MARKETPLACE_REF = "main";
-export declare function ensureOfficialMarketplace(argv: string[]): void;
 export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -1,14 +1,8 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js';
-import { ensureDir, pathExists, removePath, nowIso } from './fs-utils.js';
-import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
-import { clone } from './git.js';
-import { readMarketplaceManifest } from './manifest.js';
+import { ensureScopeInitialized } from './config.js';
 import { CRTR_DIR_NAME } from '../types.js';
-export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
-export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
-export const OFFICIAL_MARKETPLACE_REF = 'main';
 const SKIP_SUBCOMMANDS = new Set([
     'help',
     '--help',
@@ -22,54 +16,6 @@ function shouldSkipForArgv(argv) {
         return true;
     return SKIP_SUBCOMMANDS.has(sub);
 }
-export function ensureOfficialMarketplace(argv) {
-    try {
-        if (process.env.CRTR_NO_BOOTSTRAP === '1')
-            return;
-        if (shouldSkipForArgv(argv))
-            return;
-        const state = readState('user');
-        if (state.bootstrap_done === true)
-            return;
-        const cfg = readConfig('user');
-        if (cfg.marketplaces[OFFICIAL_MARKETPLACE_NAME] !== undefined) {
-            updateState('user', (s) => {
-                s.bootstrap_done = true;
-            });
-            return;
-        }
-        const root = userScopeRoot();
-        ensureScopeInitialized('user', root);
-        const mktsDir = join(root, 'marketplaces');
-        ensureDir(mktsDir);
-        const dest = join(mktsDir, OFFICIAL_MARKETPLACE_NAME);
-        if (pathExists(dest)) {
-            removePath(dest);
-        }
-        clone(OFFICIAL_MARKETPLACE_URL, dest, { depth: 1, ref: OFFICIAL_MARKETPLACE_REF });
-        const manifest = readMarketplaceManifest(dest);
-        if (manifest === null) {
-            removePath(dest);
-            return;
-        }
-        updateConfig('user', (c) => {
-            c.marketplaces[OFFICIAL_MARKETPLACE_NAME] = {
-                url: OFFICIAL_MARKETPLACE_URL,
-                ref: OFFICIAL_MARKETPLACE_REF,
-                installed_at: nowIso(),
-            };
-        });
-        updateState('user', (s) => {
-            s.bootstrap_done = true;
-        });
-    }
-    catch (e) {
-        if (process.env.CRTR_DEBUG === '1') {
-            const msg = e instanceof Error ? e.message : String(e);
-            process.stderr.write(`crtr: bootstrap error: ${msg}\n`);
-        }
-    }
-}
 export function ensureProjectScope(argv) {
     try {
         if (process.env.CRTR_NO_AUTO_INIT === '1')

package/dist/core/canvas/crons.d.ts

@@ -26,6 +26,19 @@ export interface Cron {
     sink: string;
     tier: string;
     last_output_hash: string | null;
+    /** True while the row is PARKED by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A poke re-dues the row now; otherwise a
+     *  recurring row re-checks at its already-advanced natural slot and a held
+     *  one-shot waits at its backstop `fire_at` (expires_at, else far future).
+     *  Deliberately NOT part of the due query — a held row is non-due by
+     *  `fire_at`, not by a new predicate. */
+    held: boolean;
+    /** UTC ISO of the last `POST /v1/crons/poke` receipt, written to EVERY row
+     *  on poke. Settlement compares a 75-exiting run's start against it: a poke
+     *  that arrived mid-run re-dues instead of parking (the in-flight gate check
+     *  could not have seen the eligibility change). */
+    last_poke_at: string | null;
     state: CronState;
     run_state: CronRunState;
     run_pid: number | null;
@@ -194,9 +207,48 @@ export declare function dueClockCrons(nowIso: string): Cron[];
  *  `outOfBand` stamps the lease as a `cron run` (manual verification) so the
  *  overlap pass leaves it alone — see `dueOverlapCrons`. */
 export declare function acquireCronRunLease(cron_id: string, leaseOwner: string, pid: number, startedAtIso: string, outOfBand: boolean): boolean;
+/** What a settling run does with the row's `held` state, applied in the SAME
+ *  UPDATE that releases the lease — one write boundary, so no tick can observe
+ *  `run_state='idle'` with the held transition not yet applied.
+ *    clear — an ordinary scheduled disposition settlement (success, real
+ *            failure): the gate resolved, so a parked row unparks.
+ *    park  — the exit-75 owed-gate disposition: held=1. A one-shot also moves
+ *            `fire_at` to its backstop (`fireAt`); a recurring row keeps its
+ *            pre-run-advanced natural slot.
+ *    redue — a poke arrived while this gate check was in flight (start <
+ *            last_poke_at): fire_at=now, held=0 — re-check next tick.
+ *  Omitted entirely = leave `held` untouched (a replaced run, an out-of-band
+ *  run, an unobserved crashed run — the gate is still unresolved). */
+export type HeldSettle = {
+    kind: 'clear';
+} | {
+    kind: 'park';
+    fireAt?: string;
+} | {
+    kind: 'redue';
+    nowIso: string;
+};
 /** Release the run lease back to idle (run settled, or stale-lease recovery
- *  for a dead pid). */
-export declare function releaseCronRunLease(cron_id: string): void;
+ *  for a dead pid), applying the settlement's `held` disposition in the same
+ *  statement. */
+export declare function releaseCronRunLease(cron_id: string, held?: HeldSettle): void;
+/** The daemon-level eligibility poke (`POST /v1/crons/poke`): "something
+ *  changed; re-check now". One write boundary, two statements:
+ *    1. stamp `last_poke_at` on EVERY row — this is what reaches a gate check
+ *       in flight right now, which statement 2 deliberately skips: its exit-75
+ *       settlement sees the stamp and re-dues itself (the F2 branch in
+ *       cron-run.ts);
+ *    2. re-due every held active IDLE row now (fire_at=now, held=0). A leased
+ *       row is excluded: its running gate check settles against the stamp —
+ *       75 re-dues, and success means the gate resolved and the occurrence
+ *       fired, poke satisfied. Unparking mid-run would overwrite the row's
+ *       pre-advanced backstop slot with `now`, so a PASSING gate would fire a
+ *       second time on the next tick.
+ *  Paused rows are not unparked — pause is user-owned and freezes everything;
+ *  a paused held row keeps its state and unparks via a later poke/backstop
+ *  after resume (it still receives the stamp, harmlessly). Returns the
+ *  unparked count. Idempotent and free when nothing is held. */
+export declare function pokeHeldCrons(nowIso: string): number;
 /** Recurring crons whose NEXT fire has arrived while their previous run is
  *  still leased — the overlap-policy pass. One-shots never appear here (a
  *  one-shot has exactly one fire, already consumed by its running lease).

package/dist/core/canvas/crons.js

@@ -46,6 +46,8 @@ function cronFrom(r) {
         sink: r['sink'],
         tier: r['tier'],
         last_output_hash: r['last_output_hash'] ?? null,
+        held: Number(r['held']) !== 0,
+        last_poke_at: r['last_poke_at'] ?? null,
         state: r['state'],
         run_state: r['run_state'],
         run_pid: r['run_pid'] ?? null,
@@ -286,14 +288,56 @@ export function acquireCronRunLease(cron_id, leaseOwner, pid, startedAtIso, outO
     return Number(res.changes) > 0;
 }
 /** Release the run lease back to idle (run settled, or stale-lease recovery
- *  for a dead pid). */
-export function releaseCronRunLease(cron_id) {
+ *  for a dead pid), applying the settlement's `held` disposition in the same
+ *  statement. */
+export function releaseCronRunLease(cron_id, held) {
+    let heldSql = '';
+    const heldParams = [];
+    if (held !== undefined) {
+        if (held.kind === 'clear') {
+            heldSql = ', held = 0';
+        }
+        else if (held.kind === 'park') {
+            heldSql = held.fireAt !== undefined ? ', held = 1, fire_at = ?' : ', held = 1';
+            if (held.fireAt !== undefined)
+                heldParams.push(held.fireAt);
+        }
+        else {
+            heldSql = ', held = 0, fire_at = ?';
+            heldParams.push(held.nowIso);
+        }
+    }
     openDb()
         .prepare(`UPDATE crons
        SET run_state = 'idle', run_started_at = NULL, run_pid = NULL, run_pid_identity = NULL,
-           run_lease_owner = NULL, run_out_of_band = 0, updated = ?
+           run_lease_owner = NULL, run_out_of_band = 0, updated = ?${heldSql}
        WHERE cron_id = ?`)
-        .run(new Date().toISOString(), cron_id);
+        .run(new Date().toISOString(), ...heldParams, cron_id);
+}
+/** The daemon-level eligibility poke (`POST /v1/crons/poke`): "something
+ *  changed; re-check now". One write boundary, two statements:
+ *    1. stamp `last_poke_at` on EVERY row — this is what reaches a gate check
+ *       in flight right now, which statement 2 deliberately skips: its exit-75
+ *       settlement sees the stamp and re-dues itself (the F2 branch in
+ *       cron-run.ts);
+ *    2. re-due every held active IDLE row now (fire_at=now, held=0). A leased
+ *       row is excluded: its running gate check settles against the stamp —
+ *       75 re-dues, and success means the gate resolved and the occurrence
+ *       fired, poke satisfied. Unparking mid-run would overwrite the row's
+ *       pre-advanced backstop slot with `now`, so a PASSING gate would fire a
+ *       second time on the next tick.
+ *  Paused rows are not unparked — pause is user-owned and freezes everything;
+ *  a paused held row keeps its state and unparks via a later poke/backstop
+ *  after resume (it still receives the stamp, harmlessly). Returns the
+ *  unparked count. Idempotent and free when nothing is held. */
+export function pokeHeldCrons(nowIso) {
+    return withCanvasWrite((db) => {
+        db.prepare('UPDATE crons SET last_poke_at = ?').run(nowIso);
+        const res = db
+            .prepare("UPDATE crons SET fire_at = ?, held = 0, updated = ? WHERE held = 1 AND state = 'active' AND run_state = 'idle'")
+            .run(nowIso, nowIso);
+        return Number(res.changes);
+    });
 }
 /** Recurring crons whose NEXT fire has arrived while their previous run is
  *  still leased — the overlap-policy pass. One-shots never appear here (a

package/dist/core/canvas/db.js

@@ -1131,6 +1131,27 @@ ALTER TABLE review_comments
 function dropConsultOutbox(db) {
     db.exec('DROP TABLE IF EXISTS consult_outbox');
 }
+/** v31 — a human's submit intent recorded on a still-open review, so the
+ *  approval can wait for the companion to stop working. Deliberately a column
+ *  and not a new `state` value: through the wait the review IS open — comments
+ *  still land, ranges still remap, and cancellation still applies. */
+function addReviewSubmitRequested(db) {
+    db.exec('ALTER TABLE reviews ADD COLUMN submit_requested_at TEXT');
+}
+/** v32 — held crons (the exit-75 owed-gate disposition). `held` marks a row
+ *  whose last scheduled run exited 75 ("owed but not currently eligible"):
+ *  the occurrence was not spent and the row waits for an eligibility poke or
+ *  its natural backstop slot. `last_poke_at` records the most recent
+ *  `POST /v1/crons/poke` receipt on EVERY row, closing the race where a poke
+ *  lands while a gate check is in flight (the settling run compares its start
+ *  against it and re-dues instead of parking). Deliberately not part of the
+ *  due query: a held row is non-due by `fire_at`, never by a new predicate. */
+function addCronHeldColumns(db) {
+    db.exec(`
+ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
+`);
+}
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
  *  `user_version` tracks how many have been applied. Append only. */
 export const MIGRATIONS = [
@@ -1166,6 +1187,8 @@ export const MIGRATIONS = [
     /* v28 */ addReviewCommentTables,
     /* v29 */ addReviewCommentAnchorState,
     /* v30 */ dropConsultOutbox,
+    /* v31 */ addReviewSubmitRequested,
+    /* v32 */ addCronHeldColumns,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not
  *  be wrapped by `migrate()` — `node:sqlite` rejects a nested BEGIN. Index 3

package/dist/core/command-manifests/manifest.d.ts

@@ -5,6 +5,10 @@ export interface ValidatedCommandManifest {
     timeouts?: ManifestTimeouts;
     /** Top-level branches, each ready to mount at parent []. */
     roots: DeclBranch<DeclLeaf>[];
+    /** Core command path (space-joined, e.g. "cron add") → attributed addendum
+     *  text appended beneath that core command's help. Append-only product
+     *  guidance — a plugin can never alter core contract text. */
+    helpAddenda?: Readonly<Record<string, string>>;
 }
 export interface CommandManifestValidation {
     /** The validated, materialized manifest (present only if all issues are fixed). */
@@ -21,4 +25,11 @@ export interface CommandManifestValidation {
 export declare function validateCommandManifest(raw: unknown, options: {
     transport: TransportKind;
     reservedCoreNames: ReadonlySet<string>;
+    /** Every core command path (space-joined). Supplied at the strict gates
+     *  (install, bundle parse, doctor/inspect reports) so a helpAddenda key
+     *  naming no core command fails there — and by the help-render lookup
+     *  (`collectHelpAddenda`), which reproduces the gate's verdict so render
+     *  and ingress report can never disagree. Omitted only on the tolerant
+     *  compose path, where mounting ignores addenda entirely. */
+    coreCommandPaths?: ReadonlySet<string>;
 }): CommandManifestValidation;