@celilo/cli 0.20.0 → 0.22.0

package/src/cli/commands/system-migrate.test.ts

@@ -1,11 +1,28 @@
 import { Database } from 'bun:sqlite';
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { closeDb } from '../../db/client';
+import { closeDb, findMigrationsFolder } from '../../db/client';
 import { handleSystemMigrate } from './system-migrate';
 
+/**
+ * The newest migration, read from the journal rather than written down here.
+ *
+ * These assertions used to name `0019_backup_pid` literally, so every
+ * subsequent migration broke a test that has nothing to do with it. What is
+ * under test is that `--status` REPORTS the head and any gap below it, not
+ * which migration happens to be head today.
+ */
+function latestMigrationTag(): string {
+  const journal = JSON.parse(
+    readFileSync(join(findMigrationsFolder(), 'meta', '_journal.json'), 'utf8'),
+  ) as { entries: { tag: string }[] };
+  const tag = journal.entries.at(-1)?.tag;
+  if (!tag) throw new Error('Migration journal is empty');
+  return tag;
+}
+
 describe('handleSystemMigrate', () => {
   let dir: string;
 
@@ -51,7 +68,7 @@ describe('handleSystemMigrate', () => {
       expect(result.success).toBe(true);
       if (result.success) {
         expect(result.message).toMatch(/Applied migrations: \d+/);
-        expect(result.message).toContain('0019_backup_pid');
+        expect(result.message).toContain(latestMigrationTag());
         expect(result.message).toContain('Pending:            none');
         expect(result.message).toContain('columns');
       }
@@ -61,6 +78,7 @@ describe('handleSystemMigrate', () => {
       await handleSystemMigrate();
       closeDb();
       // Rewind one migration, the way an upgrade that never ran would look.
+      const head = latestMigrationTag();
       const raw = new Database(process.env.CELILO_DB_PATH as string);
       raw.run(
         'DELETE FROM `__drizzle_migrations` WHERE created_at = (SELECT MAX(created_at) FROM `__drizzle_migrations`)',
@@ -75,7 +93,10 @@ describe('handleSystemMigrate', () => {
 
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error).toContain('0019_backup_pid');
+        // The rewound migration is named as pending…
+        expect(result.error).toContain(head);
+        // …and the dropped COLUMN is reported independently, which is the
+        // thing a table count cannot see (celilo#604).
         expect(result.error).toContain('backups.pid');
       }
 

package/src/cli/commands/system-update.ts

@@ -28,6 +28,7 @@ import { RegistryClient } from '../../registry/client';
 import { runAudit } from '../../services/audit';
 import { loadAbandonedOperations } from '../../services/audit/abandoned-operations';
 import { fetchLatestCliVersion } from '../../services/audit/cli-version';
+import { unusedPublicDnsProbe } from '../../services/audit/public-dns';
 import { makeJournalReader, readAppliedMigrations } from '../../services/audit/schema';
 import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
 import { runAllHealthChecks, runModuleHealthCheck } from '../../services/health-runner';
@@ -587,6 +588,10 @@ export async function handleSystemUpdate(
     secretsDecryptable: { results: [] },
     servicesReachable: { results: [] },
     machinesReachable: { results: [] },
+    // Public reachability needs a network round trip per name; the update
+    // flow's partial audit does no probing. `system audit` and the scheduled
+    // monitor own this check.
+    publicDns: { records: [], probe: unusedPublicDnsProbe },
     transportReads: { statuses: [], now: new Date(), staleAfterMs: 30 * 60_000 },
     trustedSources: { firewalls: [] },
   };

package/src/cli/completion.ts

@@ -113,6 +113,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'list-subscribers',
       'resync-subscriptions',
       'list-pending',
+      'list-failed',
       'list-unanswered',
       'drain',
       'run',

package/src/cli/index.ts

@@ -32,6 +32,7 @@ import {
   handleEventsEmit,
   handleEventsFail,
   handleEventsInstallDaemon,
+  handleEventsListFailed,
   handleEventsListPending,
   handleEventsListSubscribers,
   handleEventsListUnanswered,
@@ -300,6 +301,7 @@ Subcommands:
   list-subscribers             List persistent bus subscribers
   resync-subscriptions         Rebuild subscribers from deployed modules' manifests (after a restore/migration)
   list-pending [--subscriber]  List pending deliveries
+  list-failed [--subscriber]   List failed/abandoned deliveries with a true total
   drain [--concurrency N]      Process pending deliveries once and return
   run [--poll-ms N]            Run the long-running dispatcher (foreground)
   emit <type> [<payload>]      Emit an event (operator/test path)
@@ -1425,6 +1427,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleEventsResyncSubscriptions();
       case 'list-pending':
         return handleEventsListPending(parsed.args, parsed.flags);
+      case 'list-failed':
+        return handleEventsListFailed(parsed.args, parsed.flags);
       case 'list-unanswered':
         return handleEventsListUnanswered(parsed.args, parsed.flags);
       case 'drain':

package/src/cli/tui/audit-state.ts

@@ -84,6 +84,7 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'secrets_decryptable',
   'services_reachable',
   'machines_reachable',
+  'public_dns',
   'disk_space',
   'transport_reads',
   'trusted_sources',
@@ -105,6 +106,7 @@ export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   secrets_decryptable: 'Secrets',
   services_reachable: 'Service reachability',
   machines_reachable: 'Machine reachability',
+  public_dns: 'Public DNS reachability',
   disk_space: 'Disk space',
   transport_reads: 'Transport readability',
   trusted_sources: 'Trusted networks',

package/src/db/dns-registrations-migration.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Migration gate for celilo#626 — the one class of defect the rest of the
+ * suite is structurally incapable of seeing.
+ *
+ * A `dns_registrations` row written before #464/#466 carried a literal `ip`,
+ * and `refresh_registrations` replayed it every 15 minutes as the address to
+ * publish. Once the ISP re-leased, that republished a dead address forever,
+ * reporting success each tick. Five public names went dark for nine days,
+ * including the apt repo and the module registry, while every in-fleet check
+ * stayed green (the split-horizon resolver answers with a reachable address).
+ *
+ * A thorough e2e gate for exactly this defect already existed and passed
+ * throughout — `modules/celilo-website/e2e/website-deploy-new-hostname.test.ts`
+ * moves the WAN address and fires the real refresh hook. It could only ever
+ * exercise rows the code under test wrote, because e2e always starts from an
+ * empty database. A suite that starts clean can prove the FORWARD invariant
+ * and says nothing about the installed base — which is where the outage was.
+ *
+ * So this test builds a database at the OLD schema, puts an armed legacy row
+ * in it, and runs the real migrator over it. Dropping the column IS the
+ * sweep: every armed row on every fleet disarms with the schema change,
+ * rather than waiting for someone to redeploy the module that owns it.
+ *
+ * See design.md D6.
+ */
+
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { drizzle } from 'drizzle-orm/bun-sqlite';
+import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
+import { findMigrationsFolder } from './client';
+
+/** The last migration before this change — the schema the outage ran on. */
+const LAST_LEGACY_TAG = '0019_backup_pid';
+
+interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+/**
+ * A migrations folder truncated at `LAST_LEGACY_TAG`, so a database can be
+ * built at the pre-change schema using the real migration files rather than a
+ * hand-written approximation that could drift from them.
+ */
+function legacyMigrationsFolder(into: string): string {
+  const source = findMigrationsFolder();
+  const journal = JSON.parse(readFileSync(join(source, 'meta', '_journal.json'), 'utf8')) as {
+    version: string;
+    dialect: string;
+    entries: JournalEntry[];
+  };
+  const cutoff = journal.entries.findIndex((e) => e.tag === LAST_LEGACY_TAG);
+  if (cutoff === -1) throw new Error(`Journal has no entry for ${LAST_LEGACY_TAG}`);
+  const kept = journal.entries.slice(0, cutoff + 1);
+
+  mkdirSync(join(into, 'meta'), { recursive: true });
+  for (const entry of kept) {
+    cpSync(join(source, `${entry.tag}.sql`), join(into, `${entry.tag}.sql`));
+  }
+  writeFileSync(
+    join(into, 'meta', '_journal.json'),
+    JSON.stringify({ ...journal, entries: kept }, null, 2),
+  );
+  return into;
+}
+
+describe('dns_registrations migration over a pre-#464 database', () => {
+  let tempDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-dnsmig-'));
+    dbPath = join(tempDir, 'legacy.db');
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function openLegacyDatabase(): Database {
+    const sqlite = new Database(dbPath, { create: true });
+    sqlite.run('PRAGMA foreign_keys = ON');
+    migrate(drizzle(sqlite), {
+      migrationsFolder: legacyMigrationsFolder(join(tempDir, 'legacy-migrations')),
+    });
+    return sqlite;
+  }
+
+  function seedModule(sqlite: Database, id: string): void {
+    sqlite.run(
+      'INSERT INTO modules (id, name, source_path, version, manifest_data) VALUES (?, ?, ?, ?, ?)',
+      [id, id, `/srv/${id}`, '1.0.0', JSON.stringify({ id })],
+    );
+  }
+
+  function runCurrentMigrations(sqlite: Database): void {
+    migrate(drizzle(sqlite), { migrationsFolder: findMigrationsFolder() });
+  }
+
+  test('the armed address is gone and the registration survives', () => {
+    const sqlite = openLegacyDatabase();
+    seedModule(sqlite, 'namecheap');
+    seedModule(sqlite, 'caddy');
+
+    // The shape an older celilo wrote: a literal address the refresh replayed.
+    // This is what no deploy can produce today, which is why the seed is here
+    // and not in e2e (CLAUDE.md's pre-seeding carve-out).
+    sqlite.run(
+      'INSERT INTO dns_registrations (provider_module_id, consumer_module_id, fqdn, ip) VALUES (?, ?, ?, ?)',
+      ['namecheap', 'caddy', 'apt.celilo.computer', '71.36.112.98'],
+    );
+
+    runCurrentMigrations(sqlite);
+
+    const columns = (
+      sqlite.query('PRAGMA table_info(dns_registrations)').all() as { name: string }[]
+    ).map((c) => c.name);
+    expect(columns).not.toContain('ip');
+    expect(columns).toContain('companion');
+
+    const rows = sqlite
+      .query('SELECT fqdn, provider_module_id, companion FROM dns_registrations')
+      .all() as {
+      fqdn: string;
+      provider_module_id: string;
+      companion: number;
+    }[];
+    expect(rows).toEqual([
+      { fqdn: 'apt.celilo.computer', provider_module_id: 'namecheap', companion: 0 },
+    ]);
+
+    sqlite.close();
+  });
+
+  test('the single consumer becomes the seed of the consumer set', () => {
+    const sqlite = openLegacyDatabase();
+    seedModule(sqlite, 'namecheap');
+    seedModule(sqlite, 'caddy');
+    seedModule(sqlite, 'authentik');
+    sqlite.run(
+      'INSERT INTO dns_registrations (provider_module_id, consumer_module_id, fqdn, ip) VALUES (?, ?, ?, ?)',
+      ['namecheap', 'caddy', 'auth.lunacycle.net', '71.36.112.98'],
+    );
+    sqlite.run(
+      'INSERT INTO dns_registrations (provider_module_id, consumer_module_id, fqdn, ip) VALUES (?, ?, ?, ?)',
+      ['namecheap', 'authentik', 'other.lunacycle.net', null],
+    );
+
+    runCurrentMigrations(sqlite);
+
+    const consumers = sqlite
+      .query(
+        `SELECT r.fqdn AS fqdn, c.module_id AS module_id
+           FROM dns_registration_consumers c
+           JOIN dns_registrations r ON r.id = c.registration_id
+          ORDER BY r.fqdn`,
+      )
+      .all() as { fqdn: string; module_id: string }[];
+    expect(consumers).toEqual([
+      { fqdn: 'auth.lunacycle.net', module_id: 'caddy' },
+      { fqdn: 'other.lunacycle.net', module_id: 'authentik' },
+    ]);
+
+    sqlite.close();
+  });
+
+  test('a migrated row still dies with its provider, and now outlives a co-consumer', () => {
+    const sqlite = openLegacyDatabase();
+    seedModule(sqlite, 'namecheap');
+    seedModule(sqlite, 'caddy');
+    seedModule(sqlite, 'authentik');
+    sqlite.run(
+      'INSERT INTO dns_registrations (provider_module_id, consumer_module_id, fqdn, ip) VALUES (?, ?, ?, ?)',
+      ['namecheap', 'caddy', 'auth.lunacycle.net', '71.36.112.98'],
+    );
+
+    runCurrentMigrations(sqlite);
+
+    // authentik also depends on the name, as it does on the live fleet — the
+    // recovery re-attributed it to caddy, and under the old single-valued
+    // column removing caddy would have cascade-deleted a name still served.
+    const registrationId = (
+      sqlite.query('SELECT id FROM dns_registrations').get() as { id: number }
+    ).id;
+    sqlite.run(
+      'INSERT INTO dns_registration_consumers (registration_id, module_id) VALUES (?, ?)',
+      [registrationId, 'authentik'],
+    );
+
+    sqlite.run('DELETE FROM modules WHERE id = ?', ['caddy']);
+    expect(sqlite.query('SELECT COUNT(*) AS n FROM dns_registrations').get()).toEqual({ n: 1 });
+
+    sqlite.run('DELETE FROM modules WHERE id = ?', ['namecheap']);
+    expect(sqlite.query('SELECT COUNT(*) AS n FROM dns_registrations').get()).toEqual({ n: 0 });
+
+    sqlite.close();
+  });
+});

package/src/db/schema.ts

@@ -592,9 +592,19 @@ export const trustedSources = sqliteTable(
  * has successfully registered via dns_registrar.registerHost. Written
  * framework-side by the capability loader (the only layer that knows
  * both consumer and provider), read back to drive the provider's
- * periodic refresh_registrations hook and the `celilo dns
- * registrations` view. Rows die with either module via FK cascade; the
- * remote DNS record itself stays (Namecheap DDNS has no delete API).
+ * periodic refresh_registrations hook, the `public_dns` reachability
+ * check, and the `celilo dns registrations` view.
+ *
+ * It records WHICH MODULE ASKED FOR WHICH NAME and nothing else. In
+ * particular it does not store the published address: that is observable
+ * on demand from public DNS, and a stored copy is one careless read away
+ * from becoming an instruction again — which is exactly what took five
+ * public names dark for nine days (celilo#626).
+ *
+ * Rows die with their provider by FK cascade. The consumer side is a
+ * SET (`dns_registration_consumers`), not a column: the row must survive
+ * until its LAST consumer is removed. The remote DNS record itself stays
+ * (Namecheap DDNS has no delete API).
  * See designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2).
  */
 export const dnsRegistrations = sqliteTable(
@@ -604,12 +614,15 @@ export const dnsRegistrations = sqliteTable(
     providerModuleId: text('provider_module_id')
       .notNull()
       .references(() => modules.id, { onDelete: 'cascade' }),
-    consumerModuleId: text('consumer_module_id')
-      .notNull()
-      .references(() => modules.id, { onDelete: 'cascade' }),
     fqdn: text('fqdn').notNull(),
-    /** null = provider auto-detected the request's source IP (Namecheap-style). */
-    ip: text('ip'),
+    /**
+     * True when celilo claimed this name on a module's behalf as the
+     * companion of a declared name (`www.<domain>` ↔ `<domain>`) rather
+     * than because a module asked for it. Companions are best effort at
+     * claim time, so the `public_dns` check carries the manual-registrar
+     * remediation for them.
+     */
+    companion: integer('companion', { mode: 'boolean' }).notNull().default(false),
     registeredAt: integer('registered_at', { mode: 'timestamp' })
       .notNull()
       .default(sql`(unixepoch())`),
@@ -623,6 +636,62 @@ export const dnsRegistrations = sqliteTable(
   }),
 );
 
+/**
+ * Which modules currently depend on a DNS registration.
+ *
+ * Was a single `dns_registrations.consumer_module_id`, overwritten by
+ * every re-assert. That is not a label — the FK cascade on it decided
+ * when a LIVE record was forgotten, so recovering the fleet with
+ * `run-hook caddy on_install` re-attributed most names to caddy and
+ * removing caddy would then have cascade-deleted registrations that
+ * authentik and the site modules still served. Keep-first has the mirror
+ * failure. A set is the only model where the row dies exactly when the
+ * last module that wants the name goes away (design.md D5).
+ *
+ * The introducing module is the earliest row by `id`.
+ */
+export const dnsRegistrationConsumers = sqliteTable(
+  'dns_registration_consumers',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    registrationId: integer('registration_id')
+      .notNull()
+      .references(() => dnsRegistrations.id, { onDelete: 'cascade' }),
+    moduleId: text('module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    firstSeenAt: integer('first_seen_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    registrationModuleUnique: uniqueIndex('dns_registration_consumers_unique_idx').on(
+      table.registrationId,
+      table.moduleId,
+    ),
+  }),
+);
+
+/**
+ * Consecutive runs the `public_dns` check could obtain NO evidence about a
+ * subject (a served FQDN, or `system` for the echo service itself).
+ *
+ * A probe that could not run is not a pass. The one genuine external probe the
+ * fleet had was itself unreachable during celilo#626 and recorded that as
+ * *undetermined* with no check item at all, so a real outage produced complete
+ * silence. One blip must still stay quiet — a prober outage once paged three
+ * modules at once — so absences are counted rather than reported, and become
+ * their own finding only once they persist. A subject that answers has its row
+ * dropped, which is what makes the count consecutive.
+ */
+export const publicDnsEvidence = sqliteTable('public_dns_evidence', {
+  subject: text('subject').primaryKey(),
+  undeterminedRuns: integer('undetermined_runs').notNull().default(0),
+  lastCheckedAt: integer('last_checked_at', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+});
+
 /**
  * Internal split-horizon DNS A-record ledger. Mirrors `dns_registrations`
  * but for the dns_internal capability (technitium/knot): the capability

package/src/hooks/define-hook.test.ts

@@ -364,7 +364,7 @@ describe('defineCapabilityFunction', () => {
         async registerHost(request: RegisterHostRequest): Promise<HookResult> {
           return {
             success: true,
-            outputs: { registered_ip: request.ip ?? 'auto' },
+            outputs: { registered_fqdn: request.fqdn },
             duration: 1,
           };
         },
@@ -378,9 +378,9 @@ describe('defineCapabilityFunction', () => {
       logger: makeLogger(),
     });
 
-    const result = await methods.registerHost({ fqdn: 'www.example.com', ip: '1.2.3.4' });
+    const result = await methods.registerHost({ fqdn: 'www.example.com' });
     expect(result.success).toBe(true);
-    expect(result.outputs.registered_ip).toBe('1.2.3.4');
+    expect(result.outputs.registered_fqdn).toBe('www.example.com');
   });
 
   test('works for the firewall capability', async () => {

package/src/hooks/executor.test.ts

@@ -6,6 +6,7 @@ import {
   executeHookScript,
   invokeHook,
   resolveHookScript,
+  resolveHookTimeouts,
   validateHookInputs,
   validateHookOutputs,
 } from './executor';
@@ -212,6 +213,63 @@ describe('Hook Executor', () => {
         }),
       ).rejects.toThrow('Hook execution failed: simulated error');
     });
+
+    // celilo#622: the idle bound must be the caller's to set. The idle timer
+    // polls every 5s, so this costs ~6s of wall clock — it is the only
+    // assertion here that touches a real clock, which is why the *decision*
+    // lives in the pure resolveHookTimeouts below.
+    test('honors a caller-supplied idle timeout instead of the 30s default', async () => {
+      const { logger } = createCapturingLogger();
+      const scriptPath = join(FIXTURES_DIR, 'silent-hook.ts');
+      const context = {
+        config: { silent_ms: 8000 },
+        secrets: {},
+        systems: [],
+        logger,
+        debug: false,
+        screenshotDir: '/tmp',
+        capabilities: {},
+      };
+
+      // 8s of silence against a 1ms idle bound: killed at the first poll.
+      // Under the old hardcoded 30s idle this resolved instead.
+      await expect(executeHookScript(scriptPath, context, 60_000, 1)).rejects.toThrow(
+        'idle timeout exceeded',
+      );
+    }, 20_000);
+  });
+
+  describe('resolveHookTimeouts', () => {
+    test('no declaration: 60s total, 30s idle heuristic', () => {
+      expect(resolveHookTimeouts(undefined, false)).toEqual({
+        timeoutMs: 60_000,
+        idleTimeoutMs: 30_000,
+      });
+    });
+
+    // The bug in one assertion: namecheap declares 120000 and must get 120s,
+    // not 60s — and must NOT still be killed at 30s of silence, which would
+    // honor the declaration in name only and leave it exactly as broken.
+    test('a declared timeout sets the total AND replaces the idle heuristic', () => {
+      expect(resolveHookTimeouts(120_000, false)).toEqual({
+        timeoutMs: 120_000,
+        idleTimeoutMs: 120_000,
+      });
+    });
+
+    test('a declared timeout shorter than the idle default still wins', () => {
+      expect(resolveHookTimeouts(5_000, false)).toEqual({
+        timeoutMs: 5_000,
+        idleTimeoutMs: 5_000,
+      });
+    });
+
+    test('debug mode overrides any declaration', () => {
+      expect(resolveHookTimeouts(120_000, true)).toEqual({
+        timeoutMs: 600_000,
+        idleTimeoutMs: 600_000,
+      });
+    });
   });
 
   describe('invokeHook', () => {

package/src/hooks/executor.ts

@@ -37,7 +37,15 @@ import type { HookContext, HookDefinition, HookLogger, HookResult } from './type
 /** Default total timeout: 60 seconds */
 const DEFAULT_TIMEOUT_MS = 60_000;
 
-/** Default idle timeout: 30 seconds since last log message */
+/**
+ * Default idle timeout: 30 seconds since last log message.
+ *
+ * This is a *heuristic* for hooks that declared no bound of their own — it
+ * catches a wedged hook faster than the total timeout would. It is NOT a
+ * contract, and it must not silently override one: when a hook or a
+ * subscription declares an explicit timeout, that declaration replaces this
+ * heuristic entirely (see `invokeHook`).
+ */
 const IDLE_TIMEOUT_MS = 30_000;
 
 /**
@@ -123,12 +131,15 @@ export function resolveHookScript(modulePath: string, scriptPath: string): strin
  * @param scriptPath - Absolute path to the hook script
  * @param context - Hook context with config, secrets, logger, and inputs
  * @param timeoutMs - Total timeout in milliseconds
+ * @param idleTimeoutMs - Kill after this much silence (no `ctx.logger` call).
+ *   Pass `timeoutMs` to disable the idle heuristic — see `IDLE_TIMEOUT_MS`.
  * @returns Hook result with outputs
  */
 export async function executeHookScript(
   scriptPath: string,
   context: HookContext,
   timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  idleTimeoutMs: number = IDLE_TIMEOUT_MS,
 ): Promise<Record<string, unknown>> {
   if (!existsSync(scriptPath)) {
     throw new Error(`Hook script not found: ${scriptPath}`);
@@ -169,7 +180,7 @@ export async function executeHookScript(
     createTimeoutPromise(timeoutMs, 'total'),
   ];
   if (!context.debug) {
-    promises.push(createIdleTimeoutPromise(() => Date.now() - lastActivity, IDLE_TIMEOUT_MS));
+    promises.push(createIdleTimeoutPromise(() => Date.now() - lastActivity, idleTimeoutMs));
   }
   const result = await Promise.race(promises);
 
@@ -278,6 +289,52 @@ export interface InvokeHookOptions {
    * skip the pre-flight check, matching the pre-Phase-3 behavior.
    */
   requiredCapabilities?: string[];
+  /**
+   * Total timeout for THIS invocation, in milliseconds. Set by the caller
+   * that knows the per-invocation bound — for a bus delivery that's the
+   * subscription's `timeout_ms` (celilo#622). Takes precedence over the
+   * manifest hook's own `timeout`, being the more specific declaration.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Decide the total and idle bounds for one hook invocation.
+ *
+ * Planning function (Rule 10.4) — pure, so the crux below is testable
+ * without waiting on a real clock.
+ *
+ * **Idle-vs-total (celilo#622): an explicit declaration REPLACES the idle
+ * heuristic rather than being capped by it** — the idle bound becomes the
+ * total, which is the same as switching it off. The idle timer measures
+ * silence since the last `ctx.logger` call, which is a proxy for "this hook
+ * told us nothing about how long it needs". Once a hook or subscription
+ * states a bound, that proxy is not merely redundant but wrong: honoring a
+ * declared 120s total while still killing at 30s of silence honors the
+ * declaration in name only. That is exactly how namecheap's ddns
+ * `refresh_registrations` died — it declares `timeout_ms: 120000`, logs once
+ * per name, and a single slow upstream response is 30s of silence.
+ *
+ * The cost is deliberate: a hook that declares a bound and then truly wedges
+ * is now bounded only by that declared total, not killed early. That is the
+ * declaring subscriber's call to make, and the dispatcher kills the handler
+ * subprocess at the same `timeout_ms` regardless.
+ *
+ * @param declaredTimeoutMs - Explicitly declared total, or undefined
+ * @param debug - Debug mode uses a long total and no idle timer at all
+ */
+export function resolveHookTimeouts(
+  declaredTimeoutMs: number | undefined,
+  debug: boolean,
+): { timeoutMs: number; idleTimeoutMs: number } {
+  const timeoutMs = debug
+    ? 600_000 // 10 minutes for interactive debugging
+    : (declaredTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+  return {
+    timeoutMs,
+    idleTimeoutMs: declaredTimeoutMs === undefined ? IDLE_TIMEOUT_MS : timeoutMs,
+  };
 }
 
 /**
@@ -449,15 +506,18 @@ export async function invokeHook(
     }
   }
 
-  // In debug mode, use much longer timeouts for interactive debugging
-  const timeoutMs = debug
-    ? 600_000 // 10 minutes
-    : (definition.timeout ?? DEFAULT_TIMEOUT_MS);
+  // An explicitly declared bound — the subscription's `timeout_ms` for a bus
+  // delivery, else the manifest hook's own `timeout`. The subscription wins:
+  // it is the more specific declaration for this invocation.
+  const { timeoutMs, idleTimeoutMs } = resolveHookTimeouts(
+    options.timeoutMs ?? definition.timeout,
+    debug,
+  );
 
   // Execute
   try {
     logger.info(`Executing hook: ${hookName}`);
-    const outputs = await executeHookScript(scriptPath, context, timeoutMs);
+    const outputs = await executeHookScript(scriptPath, context, timeoutMs, idleTimeoutMs);
 
     // Validate outputs against the contract signature
     const outputError = validateHookOutputs(signature, outputs);