@celilo/cli 4.1.0 → 5.0.1

package/src/hooks/capability-loader.ts

@@ -36,6 +36,7 @@ import {
   NETWORK_ZONES,
   capabilities,
   modules,
+  privateRoutes,
   secrets,
   systemConfig,
   webRoutes,
@@ -45,7 +46,10 @@ import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildControlPlaneApi } from '../services/api-principal-enrolment';
 import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
-import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
+import {
+  emitPrivateRoutesChangedAndWait,
+  emitWebRoutesChangedAndWait,
+} from '../services/celilo-events';
 import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
@@ -95,12 +99,33 @@ import { loadHookConfigMap } from './load-hook-config';
  * success anyway, so a consumer could report "ready" while caddy never learned
  * the hostname — no site block, no cert, TLS internal_error for clients.
  */
-async function requireProviderReconcile(consumingModuleId: string, what: string): Promise<void> {
-  const reconcile = await emitWebRoutesChangedAndWait(consumingModuleId);
+/**
+ * Which ingress a reconcile is being required for. The two differ only in the
+ * event type they emit and the names their failures carry, so they share this
+ * function rather than each keeping a copy — a private ingress that silently
+ * stopped waiting would look exactly like one with nothing to wait for
+ * (providers-converge-declared-state, slice 2).
+ */
+const INGRESS = {
+  public_web: { capability: 'public_web', provider: 'caddy', emit: emitWebRoutesChangedAndWait },
+  private_web: {
+    capability: 'private_web',
+    provider: 'caddy-internal',
+    emit: emitPrivateRoutesChangedAndWait,
+  },
+} as const;
+
+async function requireProviderReconcile(
+  consumingModuleId: string,
+  what: string,
+  ingress: keyof typeof INGRESS = 'public_web',
+): Promise<void> {
+  const { capability, provider, emit } = INGRESS[ingress];
+  const reconcile = await emit(consumingModuleId);
 
   if (reconcile.noDispatcher) {
     throw new Error(
-      `public_web ${what} for ${consumingModuleId} was persisted but NOT delivered to the provider (caddy): no event dispatcher is running, so caddy never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
+      `${capability} ${what} for ${consumingModuleId} was persisted but NOT delivered to the provider (${provider}): no event dispatcher is running, so ${provider} never reconciled and the hostname has no site block or cert. Run this through \`celilo module deploy\` (which runs the dispatcher) rather than a bare hook.`,
     );
   }
   // The handler's own words, when it left any. A crash is retried, so its
@@ -110,13 +135,20 @@ async function requireProviderReconcile(consumingModuleId: string, what: string)
   const because = reconcile.lastError ? ` The provider reported: ${reconcile.lastError}` : '';
 
   if (reconcile.timedOut) {
+    // "0 ok, 0 failed" reads as "nobody consumed it", which sends the reader to
+    // the dispatcher (celilo#1398/#1399) when the truth is that the provider's
+    // deliveries were STILL RUNNING at the deadline (celilo#1416). Say which.
+    const inFlight =
+      reconcile.stillRunning > 0
+        ? `${reconcile.stillRunning} delivery(ies) still running`
+        : `${reconcile.succeeded} ok, ${reconcile.failed} failed`;
     throw new Error(
-      `public_web reconcile for ${consumingModuleId} (${what}) did not finish within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} change event(s)) — caddy did not confirm the change is live.${because}`,
+      `${capability} reconcile for ${consumingModuleId} (${what}) did not finish within its ${Math.round(reconcile.budgetMs / 1000)}s budget (${inFlight} of ${reconcile.events} change event(s)) — ${provider} did not confirm the change is live.${because}`,
     );
   }
   if (reconcile.failed > 0) {
     throw new Error(
-      `public_web reconcile for ${consumingModuleId} (${what}): ${reconcile.failed} delivery(ies) failed — caddy could not apply the change, so the hostname is not served as declared.${because}`,
+      `${capability} reconcile for ${consumingModuleId} (${what}): ${reconcile.failed} delivery(ies) failed — ${provider} could not apply the change, so the hostname is not served as declared.${because}`,
     );
   }
   // ISS-0087: a change WAS persisted and the dispatcher IS alive, yet ZERO
@@ -126,7 +158,7 @@ async function requireProviderReconcile(consumingModuleId: string, what: string)
   // changed and nobody served it — a failure.
   if (reconcile.events > 0 && reconcile.succeeded === 0) {
     throw new Error(
-      `public_web ${what} for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — caddy has no reconcile_routes subscription on the bus, so the change is persisted yet never served. Ensure a public_web provider (caddy) is deployed and subscribed.`,
+      `${capability} ${what} for ${consumingModuleId} changed (${reconcile.events} event(s)) but NO provider reconciled it — ${provider} has no reconcile_routes subscription on the bus, so the change is persisted yet never served. Ensure a ${capability} provider (${provider}) is deployed and subscribed.`,
     );
   }
 }
@@ -175,11 +207,13 @@ export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFacto
       legacyFactoryName: 'default',
     },
     // MODULE-provided, unlike its sibling public_web above, which the framework
-    // implements (createPublicWeb) against celilo's `web_routes` table. The
-    // asymmetry is deliberate: a private route stored in `web_routes` would be
-    // picked up by the PUBLIC caddy, which derives its served hostnames from
-    // every row of that table — so the provider keeps its own routes and celilo
-    // core holds no private-ingress business at all (celilo#846).
+    // implements (createPublicWeb). The two ingresses are separate TABLES, not
+    // separate owners: core owns `private_routes` as it owns `web_routes`
+    // (migration 0034), and that separation — not the provider keeping its own
+    // config — is what stops the PUBLIC caddy, which derives its served
+    // hostnames from every row of `web_routes`, from sweeping a private route
+    // into the public ingress (celilo#846). What stays module-side is the
+    // RENDER: caddy-internal decides what its Caddyfile says.
     private_web: {
       script: 'scripts/private-web-functions.ts',
       legacyFactoryName: 'default',
@@ -499,6 +533,26 @@ export async function loadCapabilityFunctions(
           // same seam. A jailed hook cannot write into its own web root, so a
           // module-provided web provider needs the state overlay to honor it.
           consumerStateWebRoot: resolveModuleStateWebRoot(consumingModuleId, db),
+          // THE PRIVATE INGRESS'S DECLARED ROWS, for the provider that serves
+          // them. Scoped to private_web deliberately: these are one
+          // capability's declared state, and handing them to every
+          // module-provided capability would put the private route table in
+          // reach of modules that have no business reading it.
+          ...(capName === 'private_web'
+            ? {
+                privateRoutes: buildPrivateRouteOps(db),
+                // The same seam public_web has (see `onRoutesChanged` below):
+                // the capability persists the row and hands the converge to
+                // the provider's `reconcile_routes` subscription, then AWAITS
+                // that delivery so `registerReverseProxy` still returns only
+                // once the route is live (design D7). One primitive, two
+                // triggers — the subscription is the second, not a
+                // replacement for the call.
+                onRoutesChanged: async () => {
+                  await requireProviderReconcile(consumingModuleId, 'route change', 'private_web');
+                },
+              }
+            : {}),
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -817,6 +871,51 @@ export async function loadCapabilityFunctions(
     debugLog('public_web: not registered in DB, skipping');
   }
 
+  // THE PRIVATE INGRESS, symmetric with the public one above (design D7 of
+  // providers-converge-declared-state). Its provider gets a view of the rows it
+  // serves and the converge that places what it renders — the same two things
+  // caddy gets, for the same reason, now that its routes are core-owned state
+  // rather than its own module-config JSON.
+  //
+  // Consumers never see either: only the module that PROVIDES private_web.
+  const privateWebProviders = db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, 'private_web'))
+    .all();
+  const privateWebProvider = privateWebProviders[0];
+  if (privateWebProvider && consumingModuleId === privateWebProvider.moduleId) {
+    result.private_routes = buildPrivateRouteOps(db);
+    debugLog(`private_routes: injected for provider ${consumingModuleId}`);
+
+    const providerModuleId = privateWebProvider.moduleId;
+    const privateConverge: ProviderConvergeView = {
+      // The private ingress serves no consumer-built static sites today: every
+      // row it renders is a reverse proxy. Answering honestly rather than
+      // throwing keeps the shape identical to the public provider's, so one
+      // renderer contract covers both (design D1).
+      resolveConsumerSite: async (moduleId: string) => ({
+        unavailable: `the private ingress serves no static sites, so '${moduleId}' has none here`,
+      }),
+      converge: async (artifacts) => {
+        const { convergeProviderConfig, resolveStaticContentRetention } = await import(
+          '../services/provider-converge'
+        );
+        const result = await convergeProviderConfig(db, providerModuleId, {
+          ...artifacts,
+          retention: resolveStaticContentRetention(db, providerModuleId),
+        });
+        return {
+          success: result.success,
+          ...(result.error ? { error: result.error } : {}),
+          unresolved: result.unresolved,
+        };
+      },
+    };
+    result.provider_converge = privateConverge;
+    debugLog(`provider_converge: injected for private provider ${consumingModuleId}`);
+  }
+
   // Framework-granted, so unlike everything above there is no provider row to
   // look up and no script to import — celilo IS the management server whose
   // principals these are (web-ui-console D7b).
@@ -1488,6 +1587,74 @@ async function buildFirewallChain(
   return { chain: currentUpstream, self };
 }
 
+/**
+ * Route ops for the private_web PROVIDER, over `private_routes`.
+ *
+ * The private ingress's rows are core-owned declared state now, exactly as
+ * `web_routes` is for public_web (design D1 of
+ * providers-converge-declared-state). They used to live in caddy-internal's
+ * `routes` module-config JSON, which is why the two ingresses could not share
+ * plumbing: celilo had nothing to render, converge or audit.
+ *
+ * SEPARATE TABLE, and that is the whole safety property. The public provider
+ * derives the hostnames it serves from every row of ITS table, so a private
+ * route sharing that table is one missing WHERE clause from being served
+ * publicly with a public certificate (celilo#846). Injected only into the
+ * private_web provider's own capability functions, the same way the route view
+ * reaches caddy and no one else.
+ *
+ * Rows go out in the snake_case shape the provider's renderer already speaks,
+ * so the module needs no translation layer and its existing route tests keep
+ * asserting the same objects.
+ */
+function buildPrivateRouteOps(db: DbClient) {
+  const toRecord = (row: typeof privateRoutes.$inferSelect) => ({
+    module_id: row.moduleId,
+    slug: row.slug,
+    type: row.type,
+    path: row.path,
+    hostname: row.hostname,
+    ...(row.targetHost ? { target_host: row.targetHost } : {}),
+    ...(row.targetPort ? { target_port: row.targetPort } : {}),
+    ...(row.websocket ? { websocket: row.websocket } : {}),
+  });
+
+  return {
+    all: () => db.select().from(privateRoutes).all().map(toRecord),
+    /**
+     * Replace the whole set.
+     *
+     * The provider keeps the full route list in memory for the life of one
+     * hook run and hands it back whole, which is the semantics its config key
+     * had. Honouring that here keeps the change to the module small and the
+     * two halves easy to reason about.
+     *
+     * ponytail: whole-set replace, in one transaction so a reader never sees
+     * an empty ingress. If two providers ever write this table concurrently,
+     * this becomes per-row upsert plus a delete of what the writer dropped.
+     */
+    replaceAll: (rows: ReturnType<typeof toRecord>[]) => {
+      db.transaction((tx) => {
+        tx.delete(privateRoutes).run();
+        for (const row of rows) {
+          tx.insert(privateRoutes)
+            .values({
+              slug: row.slug,
+              moduleId: row.module_id,
+              type: row.type,
+              path: row.path,
+              hostname: row.hostname,
+              targetHost: row.target_host ?? null,
+              targetPort: row.target_port ?? null,
+              websocket: row.websocket ?? false,
+            })
+            .run();
+        }
+      });
+    },
+  };
+}
+
 /**
  * Build RouteOps for the public_web capability implementation.
  * Wraps database operations so the capability never touches the DB directly.

package/src/hooks/executor.test.ts

@@ -529,7 +529,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/artifact-writing-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -560,7 +560,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/success-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -585,7 +585,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         { script: './test-fixtures/success-hook.ts', timeout: 10000 },
         { vps_ip: '10.0.0.5' },
         {},
@@ -614,7 +614,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         { username: 'test' },
@@ -641,7 +641,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'on_backup',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -663,7 +663,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -686,7 +686,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'on_backup',
-        '1.0',
+        '2.0',
         definition,
         { backup_dir: '/tmp/backup' },
         {},
@@ -708,7 +708,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         {},
         {},
@@ -743,10 +743,10 @@ describe('Hook Executor', () => {
       const { logger } = createCapturingLogger();
       const definition: HookDefinition = { script: './test-fixtures/success-hook.ts' };
 
-      const result = await invokeHook(__dirname, 'on_poop', '1.0', definition, {}, {}, {}, logger);
+      const result = await invokeHook(__dirname, 'on_poop', '2.0', definition, {}, {}, {}, logger);
 
       expect(result.success).toBe(false);
-      expect(result.error).toContain("Hook 'on_poop' is not part of celilo_contract 1.0");
+      expect(result.error).toContain("Hook 'on_poop' is not part of celilo_contract 2.0");
     });
 
     test('pre-flight: fails when a required capability is missing', async () => {
@@ -759,7 +759,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},
@@ -786,7 +786,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},
@@ -813,7 +813,7 @@ describe('Hook Executor', () => {
       const result = await invokeHook(
         __dirname,
         'container_created',
-        '1.0',
+        '2.0',
         definition,
         { vps_ip: '10.0.0.5' },
         {},

package/src/hooks/hook-state-dir.test.ts

@@ -62,7 +62,7 @@ describe('celilo#1000: a hook is TOLD where its state directory is', () => {
       const result = await invokeHook(
         root,
         'on_install',
-        '1.0',
+        '2.0',
         { script: 'hook.ts' },
         {},
         {},
@@ -97,7 +97,7 @@ describe('celilo#1000: a hook is TOLD where its state directory is', () => {
       const result = await invokeHook(
         root,
         'on_install',
-        '1.0',
+        '2.0',
         { script: 'hook.ts' },
         {},
         {},

package/src/hooks/mount-set.test.ts

@@ -177,6 +177,34 @@ describe('~/.ssh is never in the mount set (stage 3, D12)', () => {
   });
 });
 
+describe('a bound browser without fonts is a browser that cannot render', () => {
+  // celilo#1422. Binding BROWSER_ROOT makes the browser START; it does not make
+  // it RENDER. With no font configuration in the jail, Blink's remote font face
+  // path hits a fatal NOTREACHED on any page that loads a web font and the
+  // renderer dies mid navigation — surfacing as a Playwright selector timeout
+  // that names neither fonts nor the jail. Measured on the management host,
+  // same bwrap invocation, only these rows differing: 12 NOTREACHED without,
+  // 0 with.
+  //
+  // Tied to BROWSER_ROOT deliberately. Fonts are only interesting BECAUSE a
+  // browser is bound, so if the browser bind is ever dropped this test should
+  // be reconsidered with it rather than left asserting an unrelated directory.
+  test('every font directory the renderer needs is bound alongside the browser', () => {
+    const paths = pathsOf(BASE);
+    expect(paths).toContain(BROWSER_ROOT);
+    for (const dir of ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts']) {
+      expect(paths).toContain(dir);
+    }
+  });
+
+  test('fonts are read-only — a hook has no business writing to them', () => {
+    for (const dir of ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts']) {
+      const row = deriveMountSet(BASE).entries.find((e) => e.path === dir);
+      expect(row?.mode).toBe('ro');
+    }
+  });
+});
+
 describe('the fleet browser is reachable, and only read-only (task 4.10)', () => {
   test('BROWSER_ROOT is bound', () => {
     // Task 4.10 names `~/.cache/ms-playwright`. That path is stale:

package/src/hooks/mount-set.ts

@@ -112,6 +112,34 @@ export interface MountSetRequest {
 /** Directories whose contents the runtime needs in order to start at all. */
 const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
 
+/**
+ * What RENDERING needs, as distinct from what running needs.
+ *
+ * Omitting these does not stop the browser starting, which is why it survived
+ * the bind added for `BROWSER_ROOT` below. It kills the RENDERER, and only on a
+ * page that loads a web font. Blink's remote font face path hits a fatal
+ * `NOTREACHED` with no font configuration present, the renderer dies mid
+ * navigation, and Playwright reports `Target page, context or browser has been
+ * closed` while awaiting a selector — which reads as a slow page or a flaky
+ * selector and names neither fonts nor the jail.
+ *
+ * Measured 2026-09-25 on the management host, same bwrap invocation, only these
+ * three rows differing (celilo#1422):
+ *
+ *   without: 12x ERROR ... remote_font_face_source.cc:365] NOTREACHED hit.
+ *   with:     0
+ *
+ * celilo PROVISIONS these deliberately — `celilo-mgmt`'s browser block installs
+ * `fontconfig` and `fonts-dejavu-core` because "a screenshot with no glyphs is
+ * not worth retaining" (D7). So the fleet already pays for fonts and the jail
+ * was hiding them from the one process that needs them: the provisioning and
+ * the mount set disagreed, and the browser lost.
+ *
+ * Read-only, and absent rows are dropped like any other, so a host with no
+ * fonts installed is exactly as it was rather than newly fatal.
+ */
+const FONT_DIRS = ['/usr/share/fonts', '/usr/share/fontconfig', '/etc/fonts'] as const;
+
 /**
  * What resolving a hostname needs. Read-only, and absent ones are dropped.
  *
@@ -220,6 +248,11 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   for (const dir of RUNTIME_SUPPORT_DIRS) {
     entries.push(entry(dir, 'ro', 'shared libraries and trust store', 'runtime'));
   }
+  for (const dir of FONT_DIRS) {
+    entries.push(
+      entry(dir, 'ro', 'fonts — the renderer dies without them, see FONT_DIRS', 'runtime'),
+    );
+  }
   for (const file of RESOLVER_FILES) {
     entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES', 'runtime'));
   }

package/src/hooks/test-fixtures/store-backed.ts

@@ -1,4 +1,4 @@
-import type { HookStore, HookStoreBackedMap } from '@celilo/capabilities';
+import type { HookStore } from '@celilo/capabilities';
 
 /**
  * In-memory hook-owned-state stores for tests that build a HookContext
@@ -16,10 +16,12 @@ export function configStore(
   return attach(values);
 }
 
-export function secretStore(values: Record<string, string> = {}): HookStoreBackedMap {
+export function secretStore(
+  values: Record<string, string> = {},
+): Record<string, string> & HookStore {
   // Downcast: the caller passed Record<string, string>; attach only adds
   // methods and never writes, so the value type is unchanged.
-  return attach(values) as HookStoreBackedMap;
+  return attach(values) as Record<string, string> & HookStore;
 }
 
 function attach(values: Record<string, unknown>): Record<string, unknown> & HookStore {

package/src/manifest/contracts/index.ts

@@ -5,13 +5,15 @@
  * manifest's `celilo_contract` field selects which contract applies; the
  * registry is the single source of truth for what each version promises.
  *
- * To mint a new contract version: add a new file (e.g. `./v2.ts`), import its
- * contract object here, and register it in `CONTRACTS`. Old contracts stay
- * registered indefinitely so legacy modules continue to validate.
+ * To mint a new contract version: add a new file (e.g. `./v3.ts`), import its
+ * contract object here, and register it in `CONTRACTS`. A version whose
+ * modules still work stays registered; a version whose modules would now FAIL
+ * SILENTLY moves to `RETIRED_CONTRACT_VERSIONS` with the reason, so the
+ * validator refuses it by name rather than dropping state at deploy time.
  */
 
-import { V1_CONTRACT } from './v1';
 import type { ContractHookSignature, ContractHooks } from './v1';
+import { V2_CONTRACT } from './v2';
 
 export type { ContractHooks, ContractHookSignature };
 
@@ -26,7 +28,7 @@ export type { ContractHooks, ContractHookSignature };
  * `ContractHooks` stays exact.
  *
  * Returns `undefined` for a name the contract does not define; the caller
- * turns that into "Hook 'x' is not part of celilo_contract 1.0".
+ * turns that into "Hook 'x' is not part of celilo_contract 2.0".
  */
 export function contractHookSignature(
   hooks: ContractHooks,
@@ -53,16 +55,35 @@ export interface Contract {
  * `SUPPORTED_CONTRACT_VERSIONS` below so Zod's enum picks it up.
  */
 export const CONTRACTS: Record<string, Contract> = {
-  '1.0': V1_CONTRACT,
+  '2.0': V2_CONTRACT,
+};
+
+/**
+ * Versions a manifest may still NAME but that no longer validate, mapped to
+ * the reason. A retired version is kept here rather than simply deleted so
+ * the validator can say what broke and how to move, instead of reporting a
+ * known version as an unrecognised string.
+ */
+export const RETIRED_CONTRACT_VERSIONS: Record<string, string> = {
+  '1.0':
+    'contract 1.0 persisted a hook\'s returned record as the module\'s secrets and config. That channel is removed (openspec/changes/hook-owned-state D5) — a 1.0 hook would deploy successfully and store nothing. Declare celilo_contract "2.0" and persist state with context.config.set / context.secrets.set against names the manifest declares.',
 };
 
 /**
  * Const tuple of supported contract version strings, used to drive the Zod
  * enum that validates the manifest's `celilo_contract` field.
  */
-export const SUPPORTED_CONTRACT_VERSIONS = ['1.0'] as const;
+export const SUPPORTED_CONTRACT_VERSIONS = ['2.0'] as const;
 export type SupportedContractVersion = (typeof SUPPORTED_CONTRACT_VERSIONS)[number];
 
+/**
+ * Every version string a manifest is allowed to WRITE — supported plus
+ * retired. The schema enum accepts these so a retired version reaches
+ * `validateHookContract`, which explains the retirement; anything else is a
+ * plain unknown-version error from Zod.
+ */
+export const KNOWN_CONTRACT_VERSIONS = ['1.0', '2.0'] as const;
+
 /**
  * Look up a contract by version string.
  *

package/src/manifest/contracts/v2.ts

@@ -0,0 +1,32 @@
+/**
+ * Celilo Module Contract — v2.0
+ *
+ * Hook SIGNATURES are unchanged from v1.0 — `V2_HOOKS` is `V1_HOOKS`. What
+ * changed is what the framework does with a hook's return value: nothing.
+ *
+ * Under v1.0, a record returned from `validate_config`, `on_install` or
+ * `container_created` was swept back into the module's secrets (and, for
+ * validate_config, its config). That was the only write channel a hook had,
+ * so a hook that needed to persist something it discovered had to return it.
+ * The channel is gone (openspec/changes/hook-owned-state, D5): a hook now
+ * persists state explicitly through `context.config.set` / `context.secrets.set`,
+ * against names its manifest declares.
+ *
+ * This is a MAJOR bump rather than a v1.x clarification because a module
+ * written against the old channel keeps deploying and silently stores
+ * nothing — the deploy reports success and the state is dropped. Refusing
+ * `celilo_contract: "1.0"` outright (see `RETIRED_CONTRACT_VERSIONS`) turns
+ * that silent loss into a message naming the fix, which is the whole point of
+ * versioning the contract.
+ */
+
+import { V1_HOOKS } from './v1';
+import type { ContractHooks } from './v1';
+
+/** v2.0 hook signatures — identical to v1.0. The break is behavioural. */
+export const V2_HOOKS: ContractHooks = V1_HOOKS;
+
+export const V2_CONTRACT = {
+  version: '2.0' as const,
+  hooks: V2_HOOKS,
+};

package/src/manifest/icon-schema.test.ts

@@ -11,7 +11,7 @@ import { ModuleManifestSchema } from './schema';
 
 function manifestWith(icon?: string): Record<string, unknown> {
   return {
-    celilo_contract: '1.0',
+    celilo_contract: '2.0',
     id: 'icon-fixture',
     name: 'Icon Fixture',
     version: '1.0.0',

package/src/manifest/schema.ts

@@ -6,7 +6,7 @@ import {
   MONITOR_INTERVAL_FLOOR_MINUTES,
   cadenceSchema,
 } from '../services/cadence';
-import { SUPPORTED_CONTRACT_VERSIONS } from './contracts';
+import { KNOWN_CONTRACT_VERSIONS } from './contracts';
 
 /**
  * Variable declaration sources
@@ -610,7 +610,18 @@ export const ModuleManifestSchema = z
      * here so a future v2 contract can change requirements without breaking
      * v1 modules.
      */
-    celilo_contract: z.enum(SUPPORTED_CONTRACT_VERSIONS),
+    /**
+     * The enum accepts RETIRED versions as well as supported ones. Refusing a
+     * retired version is a POLICY about importing a manifest, and it lives in
+     * `validateManifest`, not here: this schema is also what re-parses the
+     * manifest celilo already STORED for an installed module
+     * (`module-pause.ts`, `module-remove.ts`, `provider-arrival.ts`), and each
+     * of those `continue`s past a parse failure. Refusing here would make
+     * every still-unmigrated installed module silently vanish from the
+     * dependent-removal check and the provider backfill — a narrowing with no
+     * error, which is the exact failure mode this change exists to remove.
+     */
+    celilo_contract: z.enum(KNOWN_CONTRACT_VERSIONS),
 
     id: z
       .string()
@@ -849,6 +860,20 @@ export const ModuleManifestSchema = z
         command: z.string().min(1).optional(),
         /** Path to a build script (relative to module directory). Mutually exclusive with command. */
         script: z.string().min(1).optional(),
+        /**
+         * Wall-clock budget for the build, in seconds (celilo#1252).
+         *
+         * The packager used to kill every build at a hardcoded 300s. A module
+         * whose build command declares its own retry budget — forgejo fetches
+         * two release archives from codeberg with `curl --retry` — could
+         * express far more wall clock than that cap allowed, and the retries
+         * written for a flaky upstream never ran. The cap is a property of the
+         * fetch the module performs, so the module names it.
+         *
+         * `packages/e2e/tests/module-build-budget-fits-timeout.test.ts` fails
+         * when a build command's worst-case curl budget exceeds this value.
+         */
+        timeout_seconds: z.number().int().positive().max(7200).default(300),
         artifacts: z
           .array(
             z

package/src/manifest/template-validator.test.ts

@@ -14,7 +14,7 @@ import {
  */
 function createTestManifest(overrides?: Partial<ModuleManifest>): ModuleManifest {
   return {
-    celilo_contract: '1.0',
+    celilo_contract: '2.0',
     id: 'test-module',
     name: 'Test Module',
     version: '1.0.0',