@celilo/cli 2.1.0 → 2.2.0

package/src/hooks/broker.test.ts

@@ -18,7 +18,9 @@ import { join } from 'node:path';
 import { MissingProviderInputError } from '@celilo/capabilities';
 import { capabilityShape } from './broker';
 import { executeHookScript } from './executor';
+import type { HookStoreBackend, HookStores } from './hook-store';
 import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 
 const FIXTURES = join(__dirname, 'test-fixtures');
@@ -49,8 +51,8 @@ async function runCapabilityHook(): Promise<Record<string, unknown>> {
   const dir = mkdtempSync(join(tmpdir(), 'celilo-broker-'));
   try {
     const context: HookContext = {
-      config: {},
-      secrets: {},
+      config: configStore(),
+      secrets: secretStore(),
       systems: [],
       logger: createCapturingLogger().logger,
       debug: false,
@@ -67,6 +69,84 @@ async function runCapabilityHook(): Promise<Record<string, unknown>> {
   }
 }
 
+/**
+ * In-memory stand-ins for the broker-side stores. The storage mechanics have
+ * their own suite (`hook-store.test.ts`, real DB); what this layer must prove
+ * is the ROUND TRIP — a write in the hook's process landing in the broker's
+ * store and the read coming back.
+ */
+function memoryStores(): HookStores {
+  const makeBackend = (
+    kind: 'secret' | 'hook-owned config',
+    declared: string[],
+  ): HookStoreBackend => {
+    const rows = new Map<string, string>();
+    const assertDeclared = (name: string) => {
+      if (!declared.includes(name)) {
+        throw new Error(
+          `Module 'test-module' has no declared ${kind} '${name}'. Declared ${kind} names: ${declared.join(', ')}.`,
+        );
+      }
+    };
+    return {
+      get: (name) => {
+        assertDeclared(name);
+        return Promise.resolve(rows.get(name));
+      },
+      set: (name, value) => {
+        assertDeclared(name);
+        rows.set(name, value);
+        return Promise.resolve();
+      },
+      delete: (name) => {
+        assertDeclared(name);
+        rows.delete(name);
+        return Promise.resolve();
+      },
+      applyTransaction: (ops) => {
+        for (const entry of ops) {
+          assertDeclared(entry.name);
+          if (entry.op === 'set') rows.set(entry.name, entry.value ?? '');
+          else rows.delete(entry.name);
+        }
+        return Promise.resolve();
+      },
+    };
+  };
+  return {
+    secrets: makeBackend('secret', ['bot_token', 'api_key']),
+    config: makeBackend('hook-owned config', ['public_ip']),
+    declaredSecretNames: ['bot_token', 'api_key'],
+    declaredConfigNames: ['public_ip'],
+  };
+}
+
+async function runStoreHook(
+  contextData: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-broker-store-'));
+  try {
+    const context = {
+      config: { mapOnlyValue: 'from-the-context-frame' },
+      secrets: {},
+      systems: [],
+      logger: createCapturingLogger().logger,
+      debug: false,
+      screenshotDir: dir,
+      stateDir: dir,
+      capabilities: {},
+      ...contextData,
+    } as unknown as HookContext;
+    return await executeHookScript(join(FIXTURES, 'store-writing-hook.ts'), context, {
+      timeoutMs: 30_000,
+      idleTimeoutMs: 30_000,
+      hookStores: () => Promise.resolve(memoryStores()),
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 describe('capabilityShape', () => {
   test('splits functions from data', () => {
     const shape = capabilityShape(demoCapabilities());
@@ -149,3 +229,27 @@ describe('capability calls across the boundary', () => {
     expect(orphans).toEqual([]);
   }, 30_000);
 });
+
+describe('hook-owned-state store calls across the boundary', () => {
+  test('every store operation survives the round trip', async () => {
+    const outputs = await runStoreHook({});
+
+    expect(outputs.secretRoundTrip).toBe('token-value');
+    expect(outputs.configRoundTrip).toBe('203.0.113.7');
+    // The old map surface still answers beside the new methods.
+    expect(outputs.mapRead).toBe('from-the-context-frame');
+    expect(outputs.deletedIsGone).toBeUndefined();
+
+    // D4: plain sets land immediately; a transaction discards on throw.
+    expect(outputs.transactionA).toBe('committed-a');
+    expect(outputs.transactionB).toBe('committed-b');
+    expect(outputs.discarded).toBe('hook failed midway');
+    expect(outputs.afterDiscard).toBe('committed-a');
+
+    // D2: the undeclared name is an ERROR naming the module and the set. The
+    // message text itself is pinned by hook-store.test.ts; here it only has
+    // to have survived the wire intact.
+    expect(outputs.undeclaredSecret).toContain('not_declared');
+    expect(outputs.undeclaredSecret).toContain('bot_token');
+  }, 30_000);
+});

package/src/hooks/broker.ts

@@ -23,7 +23,10 @@ import { type Server, type Socket, createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
+  type BufferedStoreOp,
   type CapabilityShape,
+  type ChildFrame,
+  HOOK_PROTOCOL_VERSION,
   type HookError,
   createLineReader,
   encodeFrame,
@@ -31,8 +34,22 @@ import {
   serializeError,
   versionMismatch,
 } from './hook-protocol';
+import type { HookStores } from './hook-store';
 import type { HookLogger } from './types';
 
+/** The answering half's view of one store frame. */
+type StoreCallFrame = Extract<ChildFrame, { type: 'store' }>;
+
+/**
+ * A lazy provider of the module's two hook state stores.
+ *
+ * Lazy because building the stores reads the module row and its manifest, and
+ * because the secrets store touches the master key only when an operation
+ * actually needs it. A hook that never calls `context.secrets` should pay
+ * none of that.
+ */
+export type HookStoresProvider = () => Promise<HookStores>;
+
 /**
  * How long to wait after the child exits for its last frame to arrive. Short,
  * because by this point the writer is already gone and the bytes are either in
@@ -56,6 +73,13 @@ export interface BrokerOptions {
   logger: HookLogger;
   /** Called on every frame, so the idle timer measures the whole channel. */
   onActivity: () => void;
+  /**
+   * The module's hook-owned-state stores (hook-owned-state task 3.5). Absent
+   * means this run has none wired, and a `store` frame from the hook is
+   * REFUSED with an error naming the gap — a write that vanishes silently is
+   * the exact defect the accessor exists to remove.
+   */
+  stores?: HookStoresProvider;
 }
 
 export interface Broker {
@@ -163,6 +187,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   let connection: Socket | undefined;
   // Already resolved: no connection means nothing left to deliver.
   let connectionClosed: Promise<void> = Promise.resolve();
+  // The module's stores, resolved from the provider on first use.
+  let storesCache: HookStores | undefined;
 
   const server: Server = createServer((socket) => {
     if (connection) {
@@ -200,7 +226,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
           }
           send({
             type: 'context',
-            protocolVersion: 1,
+            protocolVersion: HOOK_PROTOCOL_VERSION,
             scriptPath: options.scriptPath,
             context: options.context,
           });
@@ -216,6 +242,10 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
           void dispatch(frame.id, frame.capability, frame.method, frame.args, send);
           return;
 
+        case 'store':
+          void dispatchStore(frame, send);
+          return;
+
         case 'result':
           outcome = { ok: true, outputs: frame.outputs };
           return;
@@ -285,6 +315,66 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     server.listen(socketPath, resolve);
   });
 
+  /**
+   * Answer one hook-owned-state store call.
+   *
+   * The stores resolve on first use and stay cached for the run. Everything
+   * that can fail — an undeclared name, a missing module row, a store that was
+   * never wired — answers as a `throw` frame rather than crashing the broker,
+   * so the hook's own `try`/`catch` sees it the way an in-process throw would
+   * behave.
+   */
+  async function dispatchStore(
+    frame: StoreCallFrame,
+    send: (frame: Parameters<typeof encodeFrame>[0]) => void,
+  ): Promise<void> {
+    if (stopped) {
+      send({
+        type: 'throw',
+        id: frame.id,
+        error: {
+          name: 'Error',
+          message: `Hook run has ended; refusing context.${frame.store}.${frame.method}.`,
+        },
+      });
+      return;
+    }
+
+    try {
+      if (!options.stores) {
+        throw new Error(
+          `No hook state stores were wired for this run, so context.${frame.store} is unavailable. This is a celilo bug: every hook invocation must receive both stores (hook-owned-state task 3.5).`,
+        );
+      }
+      storesCache ??= await options.stores();
+      const backend = storesCache[frame.store];
+
+      let value: unknown;
+      switch (frame.method) {
+        case 'get':
+          value = await backend.get(frame.args[0] as string);
+          break;
+        case 'set':
+          await backend.set(frame.args[0] as string, frame.args[1] as string);
+          value = null;
+          break;
+        case 'delete':
+          await backend.delete(frame.args[0] as string);
+          value = null;
+          break;
+        case 'transaction':
+          await backend.applyTransaction(frame.args[0] as BufferedStoreOp[]);
+          value = null;
+          break;
+      }
+      options.onActivity();
+      send({ type: 'return', id: frame.id, value });
+    } catch (error) {
+      options.onActivity();
+      send({ type: 'throw', id: frame.id, error: serializeError(error) });
+    }
+  }
+
   return {
     socketPath,
     drained: () =>

package/src/hooks/capability-loader-firewall.test.ts

@@ -302,6 +302,39 @@ describe('Firewall Chain Building', () => {
       expect(config.isolateTransitNetwork).toBe(true);
     });
 
+    test('single provider: the recorded interface_baseline is forwarded as a parsed list', async () => {
+      // The recorded baseline is what turns an undeclared interface from a
+      // refusal into an isolation. The single-provider iptables firewall (the
+      // production shape: the ISP router is not a celilo module) is built by
+      // buildCapabilityInterface, and THIS is the construction site that
+      // dropped the field — the baseline was written to module config and
+      // never read back, so the module converged in onboarding mode forever
+      // (ce-qzxm).
+      installReporter('iptables', '{"has_external":true}', '["dmz","app","secure"]');
+      upsertModuleConfig(db, 'iptables', 'firewall_ip', '192.168.0.254');
+      upsertModuleConfig(db, 'iptables', 'nat_ip', '192.168.0.253');
+      upsertModuleConfig(db, 'iptables', 'interface_baseline', 'eth0, eth1, eth2, eth3');
+
+      const config = await loadedConfig();
+      // A parsed array of NAMES, as the module's D5 split consumes it — not
+      // the raw comma string, and not with the write-side padding intact.
+      expect(config.interfaceBaseline).toEqual(['eth0', 'eth1', 'eth2', 'eth3']);
+    });
+
+    test('single provider: an empty interface_baseline arrives undefined, meaning onboarding', async () => {
+      // Empty and absent are the same thing, and both mean "never converged
+      // cleanly": treating an empty string as a baseline of nothing would make
+      // every interface new. The loader normalizes this so the module sees
+      // one shape for one meaning.
+      installReporter('iptables', '{"has_external":true}', '["dmz"]');
+      upsertModuleConfig(db, 'iptables', 'firewall_ip', '192.168.0.254');
+      upsertModuleConfig(db, 'iptables', 'nat_ip', '192.168.0.253');
+      upsertModuleConfig(db, 'iptables', 'interface_baseline', '');
+
+      const config = await loadedConfig();
+      expect(config.interfaceBaseline).toBeUndefined();
+    });
+
     test('chained provider: the downstream layer gets them too', async () => {
       // greenwave owns the WAN, so iptables is built through buildFirewallChain
       // rather than the single-provider path. That is a SECOND construction
@@ -324,10 +357,14 @@ describe('Firewall Chain Building', () => {
       upsertModuleConfig(db, 'iptables', 'nat_ip', '192.168.0.253');
       upsertModuleConfig(db, 'iptables', 'default_route_zone', 'internal');
       upsertModuleConfig(db, 'iptables', 'isolate_transit_network', true);
+      upsertModuleConfig(db, 'iptables', 'interface_baseline', 'eth0,eth1');
 
       const config = await loadedConfig();
       expect(config.defaultRouteZone).toBe('internal');
       expect(config.isolateTransitNetwork).toBe(true);
+      // The downstream construction site already forwarded this; pinned so the
+      // two sites cannot drift apart again.
+      expect(config.interfaceBaseline).toEqual(['eth0', 'eth1']);
     });
 
     test('unset settings arrive undefined, not as a wrong default', async () => {

package/src/hooks/capability-loader.ts

@@ -39,7 +39,7 @@ import {
   systemConfig,
   webRoutes,
 } from '../db/schema';
-import { resolveModuleWebRoot } from '../module/web-root';
+import { resolveModuleStateWebRoot, resolveModuleWebRoot } from '../module/web-root';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { buildControlPlaneApi } from '../services/api-principal-enrolment';
@@ -408,6 +408,10 @@ export async function loadCapabilityFunctions(
           // without this they could not find the caller's web root now that
           // `sourceDir` has left the request (D10 amendment).
           consumerWebRoot: resolveModuleWebRoot(consumingModuleId, db),
+          // WHERE THE CALLER'S GENERATED SITE FILES ARE (celilo#1265), by the
+          // 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),
         });
         // 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
@@ -594,6 +598,7 @@ export async function loadCapabilityFunctions(
         // Resolved here, not in the capability: on a converge there is no
         // consumer process to ask (D10 amendment).
         webRoot: resolveModuleWebRoot(consumingModuleId, db),
+        stateWebRoot: resolveModuleStateWebRoot(consumingModuleId, db),
         logger,
         config: providerConfig,
         secrets: providerSecrets,
@@ -789,6 +794,15 @@ function buildCapabilityInterface(
           trustedSubnets: zones?.trustedSubnets ?? [],
           controlPlaneSubnet: zones?.controlPlaneSubnet,
           frontedSubnets: zones?.frontedSubnets ?? [],
+          // The recorded baseline (D12), from this firewall's own module config.
+          // Absent means the box has never converged cleanly, so an interface
+          // celilo cannot attribute refuses rather than being disabled. The
+          // downstream-chain site below forwards this too; the single-provider
+          // firewall (an iptables box with the WAN held by a non-celilo ISP
+          // router) is built HERE, and this is the site that dropped it — the
+          // baseline was recorded but never read back, so every converge stayed
+          // in onboarding mode and refused instead of isolating (ce-qzxm).
+          interfaceBaseline: parseInterfaceBaseline(config.interface_baseline),
           // Operator settings, forwarded verbatim. `parseStoredConfigValue`
           // preserves each manifest-declared type, so the boolean arrives as a
           // boolean and needs no coercion here.

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

@@ -30,6 +30,7 @@ import {
   isCompiledCapabilityFactory,
   isCompiledHook,
 } from '@celilo/capabilities';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 
 function makeLogger(): HookLogger {
   return {
@@ -42,8 +43,8 @@ function makeLogger(): HookLogger {
 
 function makeContext(overrides: Partial<HookContext> = {}): HookContext {
   return {
-    config: {},
-    secrets: {},
+    config: configStore(),
+    secrets: secretStore(),
     systems: [],
     logger: makeLogger(),
     consumerModuleId: 'test-consumer',
@@ -152,7 +153,7 @@ describe('defineHook', () => {
       },
     });
 
-    await hook(makeContext({ config: { foo: 'bar' } }));
+    await hook(makeContext({ config: configStore({ foo: 'bar' }) }));
 
     expect(seenConfig).toEqual({ foo: 'bar' });
   });

package/src/hooks/executor.test.ts

@@ -15,7 +15,8 @@ import {
 } from './executor';
 import { readJailMode } from './jail';
 import { createCapturingLogger } from './logger';
-import type { HookDefinition } from './types';
+import { configStore, secretStore } from './test-fixtures/store-backed';
+import type { HookContext, HookDefinition } from './types';
 
 const FIXTURES_DIR = join(__dirname, 'test-fixtures');
 
@@ -115,8 +116,8 @@ describe('Hook Executor', () => {
       const scriptPath = join(FIXTURES_DIR, 'success-hook.ts');
 
       const result = await executeHookScript(scriptPath, {
-        config: { username: 'testuser' },
-        secrets: { password: 'secret' },
+        config: configStore({ username: 'testuser' }),
+        secrets: secretStore({ password: 'secret' }),
         systems: [],
         logger,
         debug: false,
@@ -136,8 +137,8 @@ describe('Hook Executor', () => {
 
       await expect(
         executeHookScript('/nonexistent/hook.ts', {
-          config: {},
-          secrets: {},
+          config: configStore(),
+          secrets: secretStore(),
           systems: [],
           logger,
           debug: false,
@@ -154,8 +155,8 @@ describe('Hook Executor', () => {
 
       await expect(
         executeHookScript(scriptPath, {
-          config: {},
-          secrets: {},
+          config: configStore(),
+          secrets: secretStore(),
           systems: [],
           logger,
           debug: false,
@@ -176,8 +177,8 @@ describe('Hook Executor', () => {
 
       await expect(
         executeHookScript(scriptPath, {
-          config: {},
-          secrets: {},
+          config: configStore(),
+          secrets: secretStore(),
           systems: [],
           logger,
           debug: false,
@@ -193,8 +194,8 @@ describe('Hook Executor', () => {
       const scriptPath = join(FIXTURES_DIR, 'void-hook.ts');
 
       const result = await executeHookScript(scriptPath, {
-        config: {},
-        secrets: {},
+        config: configStore(),
+        secrets: secretStore(),
         systems: [],
         logger,
         debug: false,
@@ -212,8 +213,8 @@ describe('Hook Executor', () => {
 
       await expect(
         executeHookScript(scriptPath, {
-          config: {},
-          secrets: {},
+          config: configStore(),
+          secrets: secretStore(),
           systems: [],
           logger,
           debug: false,
@@ -231,9 +232,9 @@ describe('Hook Executor', () => {
     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: {},
+      const context: HookContext = {
+        config: configStore({ silent_ms: 8000 }),
+        secrets: secretStore(),
         systems: [],
         logger,
         debug: false,
@@ -310,8 +311,8 @@ describe('Hook Executor', () => {
       try {
         const { logger } = createCapturingLogger();
         await executeHookScript(join(FIXTURES_DIR, 'void-hook.ts'), {
-          config: {},
-          secrets: {},
+          config: configStore(),
+          secrets: secretStore(),
           systems: [],
           logger,
           debug: false,

package/src/hooks/executor.ts

@@ -60,6 +60,7 @@ import {
 import { isPrivilegedCapability } from '../manifest/validate';
 import { pruneModuleArtifacts } from './artifact-retention';
 import { startBroker } from './broker';
+import type { HookStoresProvider } from './broker';
 import {
   HOOK_MOUNT_SET_ENV,
   HOOK_PROTOCOL_VERSION,
@@ -169,6 +170,35 @@ const FORWARDED_ENV = [
   'no_proxy',
 ] as const;
 
+/**
+ * The PATH a hook child gets: the CLI's own directory ahead of the inherited
+ * one, so the child can exec the SAME `celilo` the parent runs.
+ *
+ * A bun global install lands the `celilo` bin beside the bun binary itself
+ * (install.sh sets `BUN_INSTALL/bin`, default `~/.bun/bin`), so
+ * `dirname(process.execPath)` is that directory. The inherited PATH carries no
+ * such guarantee: the e2e management image runs the CLI only through an
+ * absolute-path wrapper at /usr/local/bin because its ENV has no /root/.bun/bin,
+ * and every hook that spawned `celilo` by name — caddy-internal's
+ * `on_consumer_removed` route withdrawal — died with "Executable not found in
+ * $PATH", leaving the stale routes it was withdrawing in place (celilo#1300).
+ * A real fleet hits the same class whenever the CLI is launched by a systemd
+ * unit or an absolute path with a minimal PATH.
+ *
+ * Already-present wins: an operator who has the directory on PATH sees an
+ * unchanged value. An absent inherited PATH still yields the CLI directory,
+ * so a hook can always reach `celilo` even from a stripped parent.
+ *
+ * Exported for the allow-list tests (hook-trespass.test.ts), which pin this
+ * contract the same way they pin the rest of the child environment.
+ */
+export function childPath(inherited: string | undefined): string {
+  const cliDir = dirname(process.execPath);
+  if (inherited === undefined) return cliDir;
+  if (inherited.split(':').includes(cliDir)) return inherited;
+  return `${cliDir}:${inherited}`;
+}
+
 /** The shim celilo spawns. Resolved from here so an npm install finds it too. */
 const HOOK_RUNNER_PATH = join(import.meta.dir, 'hook-runner.ts');
 /**
@@ -291,6 +321,13 @@ export interface ExecuteHookOptions {
    * fleet-credential operation is REFUSED, naming the gap (Rule 6.4).
    */
   remoteAccess?: RemoteAccessPolicy;
+  /**
+   * The module's hook-owned-state stores (hook-owned-state task 3.5), built
+   * lazily so a hook that never touches `context.secrets` / `context.config`
+   * pays nothing. Absent means the broker refuses store writes with an error
+   * naming the gap — never a silent drop.
+   */
+  hookStores?: HookStoresProvider;
 }
 
 /**
@@ -333,6 +370,7 @@ export async function executeHookScript(
     scriptPath,
     logger,
     onActivity: markActive,
+    stores: options.hookStores,
   });
   let remoteBroker: Awaited<ReturnType<typeof startRemoteBroker>> | undefined;
 
@@ -516,6 +554,10 @@ export function hookChildEnv(
   const env: Record<string, string> = {};
 
   for (const name of FORWARDED_ENV) {
+    if (name === 'PATH') {
+      env.PATH = childPath(process.env.PATH);
+      continue;
+    }
     const value = process.env[name];
     if (value !== undefined) env[name] = value;
   }
@@ -564,19 +606,36 @@ function jailRequest(
 
 /**
  * Say what the jail did, once per run, at a level that matches how surprising
- * it is.
+ * it is. A dropped row is now either FATAL or SILENT, never a warning.
+ *
+ * This used to warn about every absent row, because it could not tell a routine
+ * absence from a damaging one: "both look identical here, so the line names the
+ * paths and lets a reader tell them apart." That reasoning was sound and the
+ * result was not. The line fired 96 times with a byte-identical payload in a
+ * single `cele2e run --all`, so the case it existed to catch was buried in
+ * ninety-six copies of the case that does not matter. A signal that repeats
+ * unchanged is one every reader learns to skip.
+ *
+ * Each row now states what its own absence means (`MountAbsence`), so there is
+ * no classification left for a human to do from a path string:
  *
- * `skipped` is a warning rather than debug output on purpose. A dropped
- * `/lib64` on arm64 is routine; a dropped contract input means the hook is
- * about to write into the run's private tmpfs and report success over a
- * directory that is discarded when it exits (task 4.2j). Both look identical
- * here, so the line names the paths and lets a reader tell them apart.
+ *   required       throw. The hook cannot do what it was asked.
+ *   declared-only  silent until a module can declare the facility (ce-qani).
+ *   runtime        silent. A genuinely needed one fails the runtime, louder.
+ *   conditional    silent. Expected at this point in the lifecycle.
  */
 function reportJail(plan: JailPlan, logger: HookLogger): void {
   if (plan.mode === 'jailed') {
-    if (plan.skipped.length > 0) {
-      logger.warn(
-        `Hook jail: ${plan.skipped.length} mount(s) absent on this host and dropped: ${plan.skipped.join(', ')}`,
+    const fatal = plan.skipped.filter((m) => m.absence === 'required');
+    if (fatal.length > 0) {
+      // Throw rather than warn. A dropped contract input means the hook writes
+      // into the run's PRIVATE TMPFS and reports success over a directory that
+      // is discarded when it exits (task 4.2j), and a dropped interpreter or
+      // module tree means it could never have run at all. Both were previously
+      // survivable-looking warnings.
+      const detail = fatal.map((m) => `${m.path} (${m.reason})`).join(', ');
+      throw new Error(
+        `Hook jail cannot be built: ${fatal.length} required mount(s) absent on this host: ${detail}`,
       );
     }
     return;
@@ -642,6 +701,13 @@ export interface InvokeHookOptions {
    * refused (Rule 6.4).
    */
   remoteAccess?: RemoteAccessPolicy;
+  /**
+   * The module's hook-owned-state stores (hook-owned-state task 3.5), as a
+   * lazy provider: `() => createHookStores(db, moduleId)`. Built on first use
+   * inside the run, so a hook that never persists state never reads the
+   * manifest or touches the master key.
+   */
+  hookStores?: HookStoresProvider;
 }
 
 /**
@@ -885,7 +951,11 @@ export async function invokeHook(
 
   // Build context
   const loadedCapabilities = options.capabilities ?? {};
-  const context: HookContext = {
+  // The store accessor methods attach on the CHILD side (hook-runner.ts,
+  // buildStoreView) where the socket is, so the object serialized here
+  // carries the map half only. Same cast rationale as the runner's own
+  // context build. (hook-owned-state task 3.5)
+  const context = {
     ...inputs,
     config,
     secrets,
@@ -895,7 +965,7 @@ export async function invokeHook(
     screenshotDir,
     stateDir,
     capabilities: loadedCapabilities,
-  };
+  } as unknown as HookContext;
 
   // Pre-flight: every required capability must be loaded (HOOK_API_V2 D3).
   // Fail before invoking the handler so the script never sees a missing
@@ -945,6 +1015,7 @@ export async function invokeHook(
       idleTimeoutMs,
       jail: { modulePath, pathInputs: declaredPathInputs(signature, inputs) },
       remoteAccess: options.remoteAccess,
+      hookStores: options.hookStores,
     });
 
     // Validate outputs against the contract signature