@celilo/cli 2.2.1 → 3.0.0

package/src/hooks/jail.test.ts

@@ -209,9 +209,13 @@ describe('the three policies', () => {
   });
 
   test("'required' turns an unavailable jail into a hard failure (task 4.5)", () => {
-    expect(() =>
-      planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
-    ).toThrow(/CELILO_HOOK_JAIL=required/);
+    expect(
+      () => planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
+      // Not /CELILO_HOOK_JAIL=required/. Since hook-jail-config-surface the
+      // policy can come from the stored `hooks.jail_policy` row or the
+      // default, so a message naming the variable names a source that may be
+      // unset.
+    ).toThrow(/hook jail policy is 'required'/);
   });
 
   test("'required' names the reason, so the operator can act on it", () => {
@@ -291,30 +295,42 @@ describe('jailPolicy reads the operator’s switch', () => {
 
 describe('resolveJailPolicy applies D2 precedence (hook-jail-config-surface)', () => {
   test('an env value set and non-empty wins over stored config', () => {
-    expect(resolveJailPolicy('required', 'off')).toEqual({ policy: 'required', source: 'env' });
+    expect(resolveJailPolicy('required', undefined, 'off')).toEqual({
+      policy: 'required',
+      source: 'env',
+    });
   });
 
   test('an EMPTY STRING env value counts as unset and falls through to config', () => {
     // jailPolicy() already treats '' as unset, so the resolver agrees rather
     // than inventing a second rule for what counts as set.
-    expect(resolveJailPolicy('', 'off')).toEqual({ policy: 'off', source: 'config' });
+    expect(resolveJailPolicy('', undefined, 'off')).toEqual({ policy: 'off', source: 'config' });
   });
 
   test('stored config wins when the env var is absent', () => {
-    expect(resolveJailPolicy(undefined, 'off')).toEqual({ policy: 'off', source: 'config' });
-    expect(resolveJailPolicy(undefined, 'required')).toEqual({
+    expect(resolveJailPolicy(undefined, undefined, 'off')).toEqual({
+      policy: 'off',
+      source: 'config',
+    });
+    expect(resolveJailPolicy(undefined, undefined, 'required')).toEqual({
       policy: 'required',
       source: 'config',
     });
   });
 
-  test('both absent resolves to off from the default (peba, ce-rez7)', () => {
-    expect(resolveJailPolicy(undefined, undefined)).toEqual({ policy: 'off', source: 'default' });
-    expect(resolveJailPolicy('', undefined)).toEqual({ policy: 'off', source: 'default' });
+  test('all absent resolves to off from the default (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy(undefined, undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
+    expect(resolveJailPolicy('', undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
   });
 
   test('an explicit env auto still wins (peba, ce-rez7)', () => {
-    expect(resolveJailPolicy('auto', 'off')).toEqual({ policy: 'auto', source: 'env' });
+    expect(resolveJailPolicy('auto', undefined, 'off')).toEqual({ policy: 'auto', source: 'env' });
   });
 
   test('a stored empty jail_policy THROWS, it does not resolve to auto (peba, ce-8832)', () => {
@@ -322,8 +338,8 @@ describe('resolveJailPolicy applies D2 precedence (hook-jail-config-surface)', (
     // can only arrive via a restore from file or a hand edit to the DB — the
     // untrusted paths D3 exists to catch. It is outside the enum and fails
     // closed like any other bad stored value.
-    expect(() => resolveJailPolicy(undefined, '')).toThrow(/is not a hook jail policy/);
-    expect(() => resolveJailPolicy(undefined, '')).toThrow(/hooks\.jail_policy=''/);
+    expect(() => resolveJailPolicy(undefined, undefined, '')).toThrow(/is not a hook jail policy/);
+    expect(() => resolveJailPolicy(undefined, undefined, '')).toThrow(/hooks\.jail_policy=''/);
   });
 
   test('a typo in the STORED row is refused, not silently treated as auto (D3)', () => {
@@ -331,15 +347,87 @@ describe('resolveJailPolicy applies D2 precedence (hook-jail-config-surface)', (
     // foreign state, and a typo that silently meant `auto` reads as an armed
     // jail when nothing is armed. The config path is no laxer than the env
     // path.
-    expect(() => resolveJailPolicy(undefined, 'alwayssafe')).toThrow(/is not a hook jail policy/);
-    expect(() => resolveJailPolicy(undefined, 'alwayssafe')).toThrow(
+    expect(() => resolveJailPolicy(undefined, undefined, 'alwayssafe')).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy(undefined, undefined, 'alwayssafe')).toThrow(
       /hooks\.jail_policy='alwayssafe'/,
     );
   });
 
   test('a typo in the env value is still refused (unchanged jailPolicy behaviour)', () => {
-    expect(() => resolveJailPolicy('requried', undefined)).toThrow(/is not a hook jail policy/);
-    expect(() => resolveJailPolicy('requried', 'off')).toThrow(/CELILO_HOOK_JAIL='requried'/);
+    expect(() => resolveJailPolicy('requried', undefined, undefined)).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy('requried', undefined, 'off')).toThrow(
+      /CELILO_HOOK_JAIL='requried'/,
+    );
+  });
+});
+
+describe('resolveJailPolicy applies the four-step precedence (per-module-jail-policy task 1.3)', () => {
+  // Each boundary gets its own assertion, not just the ends: the chain is
+  // fixed and rendered, and a test that only pins (env, default) cannot tell
+  // a reordering of module and config apart from a correct one.
+
+  test('env beats the module row', () => {
+    expect(resolveJailPolicy('required', 'off', 'auto')).toEqual({
+      policy: 'required',
+      source: 'env',
+    });
+    expect(resolveJailPolicy('off', 'auto', 'auto')).toEqual({ policy: 'off', source: 'env' });
+  });
+
+  test('the module row beats system config', () => {
+    expect(resolveJailPolicy(undefined, 'off', 'auto')).toEqual({
+      policy: 'off',
+      source: 'module',
+    });
+    expect(resolveJailPolicy(undefined, 'required', 'off')).toEqual({
+      policy: 'required',
+      source: 'module',
+    });
+  });
+
+  test('system config beats the default', () => {
+    expect(resolveJailPolicy(undefined, undefined, 'auto')).toEqual({
+      policy: 'auto',
+      source: 'config',
+    });
+    expect(resolveJailPolicy(undefined, undefined, 'required')).toEqual({
+      policy: 'required',
+      source: 'config',
+    });
+  });
+
+  test('the default is off (peba, ce-rez7)', () => {
+    expect(resolveJailPolicy(undefined, undefined, undefined)).toEqual({
+      policy: 'off',
+      source: 'default',
+    });
+  });
+
+  test('an absent module row falls through to system config — absent means follow the system', () => {
+    // The everyday case: a fleet with no per-module rows behaves exactly as
+    // it does today, which is the spec's own operator guarantee.
+    expect(resolveJailPolicy(undefined, undefined, 'auto')).toEqual({
+      policy: 'auto',
+      source: 'config',
+    });
+  });
+
+  test('a bad stored per-module value THROWS rather than coercing (task 1.3)', () => {
+    // The same rule as the system key (peba, ce-8832): a restore or a hand
+    // edit is a trust boundary, and a typo that silently meant `off` would
+    // jail a module the operator exempted — or the reverse. The error names
+    // its source so a reader can tell which stored row is junk.
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe', 'off')).toThrow(
+      /is not a hook jail policy/,
+    );
+    expect(() => resolveJailPolicy(undefined, 'alwayssafe', 'off')).toThrow(
+      /module's jail policy='alwayssafe'/,
+    );
+    expect(() => resolveJailPolicy(undefined, '', 'off')).toThrow(/is not a hook jail policy/);
   });
 });
 

package/src/hooks/jail.ts

@@ -100,7 +100,9 @@ export function autoJailDefers(availability: JailAvailability): boolean {
 }
 
 /**
- * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `auto`.
+ * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `off`
+ * (peba's ruling on ce-rez7; `resolveJailPolicy`'s doc comment below has the
+ * reversal trigger).
  *
  * `required` is D8's end state, reached as an explicit act once stage 2 has
  * been proven on a host: an unavailable jail becomes a hard failure rather
@@ -433,21 +435,37 @@ export function jailPolicy(): JailPolicy {
 }
 
 /** Where the effective jail policy came from. Rendered by `system doctor` (D4). */
-export type JailPolicySource = 'env' | 'config' | 'default';
+export type JailPolicySource = 'env' | 'module' | 'config' | 'default';
+
+/** How much jailing a policy does. Lower is weaker (per-module-jail-policy). */
+export const POLICY_STRENGTH: Record<JailPolicy, number> = { off: 0, auto: 1, required: 2 };
+
+/**
+ * Whether the module's own policy jails LESS than the system's would — the
+ * definition of an exemption (per-module-jail-policy task 3.1-3.3).
+ *
+ * Shared by `module jail`'s weakening interview, `module list`'s marker,
+ * `system doctor`'s count and `system audit`'s category, so the four
+ * surfaces cannot disagree about what an exemption is.
+ */
+export function isWeakerJailPolicy(modulePolicy: JailPolicy, systemPolicy: JailPolicy): boolean {
+  return POLICY_STRENGTH[modulePolicy] < POLICY_STRENGTH[systemPolicy];
+}
 
 /**
- * Apply D2's precedence to the two sources: env wins, then stored config,
- * then the default, which is `off` (peba's ruling on ce-rez7; see
- * openspec/changes/hook-jail-config-surface/design.md for the reversal
- * trigger).
+ * Apply the precedence to the four sources (per-module-jail-policy task 1.2):
+ * env wins, then the module's own recorded policy, then stored system
+ * config, then the default, which is `off` (peba's rulings on ce-rez7 and
+ * ce-8832; see openspec/changes/hook-jail-config-surface/design.md and
+ * openspec/changes/per-module-jail-policy/ for the fixed chain).
  *
  * Pure, so both consumers (executor.ts and system-doctor.ts) can fetch the
- * stored row themselves and stay testable without a database.
+ * stored rows themselves and stay testable without a database.
  *
  * The empty-string env value is treated as unset, matching `jailPolicy()`'s
  * own handling — one rule for "what counts as set", not a second one here.
  *
- * The config path is deliberately stricter than the env path: a stored
+ * The stored paths are deliberately stricter than the env path: a stored
  * empty string THROWS (peba's ruling on ce-8832). The set-time pattern
  * `^(auto|off|required)$` rejects `''`, so a stored one can only arrive via
  * a restore from file or a hand edit to the DB — exactly the untrusted
@@ -456,9 +474,15 @@ export type JailPolicySource = 'env' | 'config' | 'default';
  * closed is the whole point. An empty CELILO_HOOK_JAIL stays "not set",
  * because `jailPolicy()` relies on that and slice 1's safety rests on the
  * two resolvers agreeing.
+ *
+ * The module row follows the same throw rule as the system key (task 1.3).
+ * `undefined` is the everyday case — no row, follow the system — and a row
+ * keyed to a module that was removed is impossible by schema: the FK
+ * cascades the delete.
  */
 export function resolveJailPolicy(
   envValue: string | undefined,
+  moduleValue: string | undefined,
   configValue: string | undefined,
 ): { policy: JailPolicy; source: JailPolicySource } {
   if (envValue !== undefined && envValue !== '') {
@@ -469,6 +493,14 @@ export function resolveJailPolicy(
       `CELILO_HOOK_JAIL='${envValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
     );
   }
+  if (moduleValue !== undefined) {
+    if (moduleValue === 'auto' || moduleValue === 'off' || moduleValue === 'required') {
+      return { policy: moduleValue, source: 'module' };
+    }
+    throw new Error(
+      `the module's jail policy='${moduleValue}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+    );
+  }
   if (configValue !== undefined) {
     if (configValue === 'auto' || configValue === 'off' || configValue === 'required') {
       return { policy: configValue, source: 'config' };
@@ -620,9 +652,14 @@ function realpathOrSelf(path: string): string {
  * Why an `off` policy runs unjailed, shared with `celilo system doctor` (task
  * 4.6) so the sentence the operator reads there is the sentence the record
  * carries.
+ *
+ * It names no source. Since hook-jail-config-surface there are three (the
+ * environment variable, the stored `hooks.jail_policy` row, and the `off`
+ * default), and this sentence is rendered for all of them. The doctor prints
+ * the source on its own line above this one; the record carries it as state.
  */
 export const JAIL_OFF_REASON =
-  'CELILO_HOOK_JAIL=off: the operator switched the hook jail off on this host.';
+  "The hook jail policy is 'off', so hooks run unjailed on this host. Set hooks.jail_policy to 'auto' or 'required' to jail them.";
 
 export function planJailedSpawn(
   cmd: readonly string[],
@@ -647,7 +684,7 @@ export function planJailedSpawn(
       : 'This invocation has no module tree to jail, so there is no mount set to enforce.';
     if (policy === 'required') {
       throw new Error(
-        `CELILO_HOOK_JAIL=required and no hook jail is available. ${reason ?? ''}`.trim(),
+        `The hook jail policy is 'required' and no hook jail is available. ${reason ?? ''}`.trim(),
       );
     }
     return { cmd, mode: 'unjailed', backend: availability.backend, reason, skipped: [] };

package/src/hooks/run-named-hook.ts

@@ -1,3 +1,4 @@
+import type { HookDefinition } from '@celilo/capabilities';
 /**
  * Helper to load + invoke a single named hook on a module.
  *
@@ -41,6 +42,16 @@ export interface RunNamedHookOptions {
    * hook's own `timeout` or the executor default applies.
    */
   timeoutMs?: number;
+  /**
+   * Use this hook definition instead of the manifest's own entry for the
+   * name. Only `on_upstream_publish` needs it: its manifest value is an
+   * ARRAY of match-rule entries and the build-bus dispatcher has already
+   * chosen the matching one, so the definition it passes is the matched
+   * entry (module-orchestrator-primitives slice 7). Every other hook keeps
+   * reading the manifest, and `celilo module run-hook` — which has no
+   * matched entry to supply — still gets `notDefined` for the array form.
+   */
+  hookDefinition?: HookDefinition;
 }
 
 export interface RunNamedHookResult extends HookResult {
@@ -113,22 +124,14 @@ export async function runNamedHook(
   }
 
   const manifest = module.manifestData as ModuleManifest;
-  const hookDef = manifest.hooks?.[hookName as keyof typeof manifest.hooks];
-  if (!hookDef) {
-    return {
-      success: true,
-      outputs: {},
-      duration: Date.now() - startedAt,
-      notDefined: true,
-    };
-  }
-  // Defensive narrow: `on_upstream_publish` is also under
-  // `manifest.hooks` (build-bus, Phase 4) but is an ARRAY of
-  // match-rule hooks dispatched by the receiver daemon — NOT
-  // runnable via `celilo module run-hook`. The HookName type
-  // excludes it, but the indexed-access return type can't prove
-  // that, so narrow at the value level.
-  if (Array.isArray(hookDef)) {
+  // `on_upstream_publish` is under `manifest.hooks` as an ARRAY of
+  // match-rule entries; the dispatcher supplies the matched entry via
+  // `options.hookDefinition`. Without one (e.g. `celilo module run-hook`)
+  // there is no single definition to run, so the hook reports notDefined
+  // rather than guessing an entry.
+  const hookDef =
+    options.hookDefinition ?? manifest.hooks?.[hookName as keyof typeof manifest.hooks];
+  if (!hookDef || Array.isArray(hookDef)) {
     return {
       success: true,
       outputs: {},

package/src/hooks/test-fixtures/artifact-writing-hook.ts

@@ -20,6 +20,5 @@ export default defineHook({
     writeFileSync(join(dir, 'spa-failure.png'), 'not-really-a-png');
     writeFileSync(join(dir, 'spa-failure.html'), '<html></html>');
     writeFileSync(join(dir, 'spa-failure.requests.txt'), 'GET /api/getActiveMonth 200');
-    return { api_key: 'wrote-artifacts' };
   },
 });

package/src/hooks/test-fixtures/capability-calling-hook.ts

@@ -5,8 +5,13 @@
  * One test per SHAPE rather than per method: the broker is generic, so a
  * per-method suite would prove the same thing thirty-seven times and drift the
  * moment a capability gained a method.
+ *
+ * Reports through a JSON file in its state directory: hook return values are
+ * no longer carried anywhere (hook-owned-state D5).
  */
 
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { defineHook, isMissingProviderInputError } from '@celilo/capabilities';
 
 interface DemoCapability {
@@ -27,25 +32,25 @@ export default defineHook({
     // `demo` is a fixture capability, not a registry entry, so the typed
     // capability map does not know it. The broker is generic and does not care.
     const demo = (ctx.capabilities as unknown as Record<string, DemoCapability>).demo;
-    const outputs: Record<string, unknown> = {};
+    const report: Record<string, unknown> = {};
 
     // Non-function properties are copied verbatim, which is what keeps
     // `providerModuleId` readable — a hook names the provider in its errors.
-    outputs.providerModuleId = demo.providerModuleId;
-    outputs.version = demo.version;
+    report.providerModuleId = demo.providerModuleId;
+    report.version = demo.version;
 
     // An optional method the provider did not implement must be ABSENT, not a
     // proxy that throws, or `if (cap.registerTrustedSource)` answers wrongly.
-    outputs.optionalMethodAbsent = demo.sometimesAbsent === undefined;
+    report.optionalMethodAbsent = demo.sometimesAbsent === undefined;
 
-    outputs.returned = await demo.echo({ x: 1, nested: { y: [2, 3] } });
-    outputs.undefinedBecomesNull = await demo.returnsNothing({});
+    report.returned = await demo.echo({ x: 1, nested: { y: [2, 3] } });
+    report.undefinedBecomesNull = await demo.returnsNothing({});
 
     try {
       await demo.boom({});
-      outputs.plainThrow = 'did not throw';
+      report.plainThrow = 'did not throw';
     } catch (error) {
-      outputs.plainThrow = {
+      report.plainThrow = {
         isError: error instanceof Error,
         name: (error as Error).name,
         message: (error as Error).message,
@@ -55,10 +60,10 @@ export default defineHook({
 
     try {
       await demo.missingInput({});
-      outputs.missingProviderInput = 'did not throw';
+      report.missingProviderInput = 'did not throw';
     } catch (error) {
       const e = error as Record<string, unknown>;
-      outputs.missingProviderInput = {
+      report.missingProviderInput = {
         recognised: isMissingProviderInputError(error),
         providerModuleId: e.providerModuleId,
         ensureId: e.ensureId,
@@ -69,11 +74,13 @@ export default defineHook({
 
     try {
       await (demo as unknown as { nope(): Promise<unknown> }).nope();
-      outputs.unknownMethod = 'did not throw';
+      report.unknownMethod = 'did not throw';
     } catch (error) {
-      outputs.unknownMethod = (error as Error).message;
+      report.unknownMethod = (error as Error).message;
     }
 
-    return outputs;
+    // Hand the report to the caller through the state directory, the one
+    // channel a hook still has.
+    writeFileSync(join(ctx.stateDir as string, 'report.json'), JSON.stringify(report));
   },
 });

package/src/hooks/test-fixtures/jail-probe-hook.ts

@@ -6,6 +6,10 @@
  * bubblewrap removes the path and gives `ENOENT`; `sandbox-exec` denies it and
  * gives `EPERM`. Both satisfy the requirement, so this fixture records only
  * whether the access worked and hands the message back for the post-mortem.
+ *
+ * The report is written to a JSON file in the state directory: hook return
+ * values are no longer carried anywhere (hook-owned-state D5), and `state/`
+ * is the one writable path inside the jail.
  */
 
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
@@ -32,7 +36,7 @@ export default defineHook({
       staged_input: string;
     };
 
-    return {
+    const report = {
       // Outside the module tree entirely, and the whole acceptance criterion:
       // celilo's data directory is not bound, so the key is not merely denied
       // but absent.
@@ -68,5 +72,9 @@ export default defineHook({
         for (const name of names) readFileSync(join(sshDir, name));
       }),
     };
+
+    // Hand the report to the parent through the state directory — the one
+    // channel a jailed hook still has (D5 removed the return channel).
+    writeFileSync(`${ctx.stateDir}/report.json`, JSON.stringify(report));
   },
 });

package/src/hooks/test-fixtures/jail-toolchain-hook.ts

@@ -21,7 +21,7 @@
  */
 
 import { execFileSync, execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { BROWSER_ROOT, defineHook } from '@celilo/capabilities';
 
@@ -81,7 +81,7 @@ export default defineHook({
     // run that supplied one — a false ABSENT indistinguishable from a real one.
     const browser = (ctx.config as { browser_executable?: string }).browser_executable ?? '';
 
-    return {
+    const reach = {
       // The one every other shell-out depends on. `execSync` spawns
       // `/bin/sh -c`, so a jail without it cannot run ANY hook that uses
       // `node:child_process`, whatever binary that hook was reaching for.
@@ -223,5 +223,10 @@ export default defineHook({
         throw new Error('no bwrap on any known path');
       }),
     };
+
+    // Hand the report to the parent through the state directory — the one
+    // channel a jailed hook still has (hook-owned-state D5 removed the
+    // return channel).
+    writeFileSync(`${ctx.stateDir}/report.json`, JSON.stringify(reach));
   },
 });

package/src/hooks/test-fixtures/runaway-hook.ts

@@ -21,6 +21,5 @@ export default defineHook({
     ctx.logger.info('runaway hook starting');
     await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 2000)));
     writeFileSync(String(ctx.config.marker_path), 'the hook kept running\n');
-    return {};
   },
 });

package/src/hooks/test-fixtures/sigterm-ignoring-hook.ts

@@ -17,6 +17,5 @@ export default defineHook({
     ctx.logger.info('sigterm-ignoring hook starting');
     await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 20_000)));
     writeFileSync(String(ctx.config.marker_path), 'survived SIGTERM\n');
-    return {};
   },
 });

package/src/hooks/test-fixtures/silent-hook.ts

@@ -15,6 +15,5 @@ export default defineHook({
   handler: async (ctx) => {
     ctx.logger.info('Starting, then going quiet');
     await new Promise((r) => setTimeout(r, Number(ctx.config.silent_ms ?? 0)));
-    return {};
   },
 });

package/src/hooks/test-fixtures/store-writing-hook.ts

@@ -3,25 +3,32 @@
  * the process boundary — set/get round trip on both stores, delete, a
  * committed transaction, a discarded transaction, and the undeclared-name
  * throw the whole design exists to produce.
+ *
+ * Reports through a JSON file in its state directory: hook return values
+ * are no longer carried anywhere (hook-owned-state D5), and the state
+ * directory is the sanctioned place a hook hands structured data to its
+ * caller.
  */
 
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { defineHook } from '@celilo/capabilities';
 
 export default defineHook({
   hook: 'on_install',
   requires: [],
   handler: async (ctx) => {
-    const outputs: Record<string, unknown> = {};
+    const report: Record<string, unknown> = {};
 
     // Round trip on each store.
     await ctx.secrets.set('bot_token', 'token-value');
-    outputs.secretRoundTrip = await ctx.secrets.get('bot_token');
+    report.secretRoundTrip = await ctx.secrets.get('bot_token');
 
     await ctx.config.set('public_ip', '203.0.113.7');
-    outputs.configRoundTrip = await ctx.config.get('public_ip');
+    report.configRoundTrip = await ctx.config.get('public_ip');
 
     // The map surface still answers from the values the context carried.
-    outputs.mapRead = ctx.config.mapOnlyValue;
+    report.mapRead = ctx.config.mapOnlyValue;
 
     // Delete removes; deleting a declared-but-never-written name is a no-op.
     // (An UNDECLARED name on delete throws — that is 3.4, tested below.
@@ -29,15 +36,15 @@ export default defineHook({
     await ctx.secrets.delete('bot_token');
     await ctx.secrets.set('api_key', 'to-delete');
     await ctx.secrets.delete('api_key');
-    outputs.deletedIsGone = await ctx.secrets.get('api_key');
+    report.deletedIsGone = await ctx.secrets.get('api_key');
 
     // Committed transaction: both writes land.
     await ctx.secrets.transaction((s) => {
       s.set('bot_token', 'committed-a');
       s.set('api_key', 'committed-b');
     });
-    outputs.transactionA = await ctx.secrets.get('bot_token');
-    outputs.transactionB = await ctx.secrets.get('api_key');
+    report.transactionA = await ctx.secrets.get('bot_token');
+    report.transactionB = await ctx.secrets.get('api_key');
 
     // Discarded transaction: nothing lands, including the overwrite of the
     // committed value above.
@@ -47,17 +54,19 @@ export default defineHook({
         throw new Error('hook failed midway');
       });
     } catch (error) {
-      outputs.discarded = (error as Error).message;
+      report.discarded = (error as Error).message;
     }
-    outputs.afterDiscard = await ctx.secrets.get('bot_token');
+    report.afterDiscard = await ctx.secrets.get('bot_token');
 
     // An undeclared name throws, naming the module and the declared set.
     try {
       await ctx.secrets.set('not_declared', 'x');
     } catch (error) {
-      outputs.undeclaredSecret = (error as Error).message;
+      report.undeclaredSecret = (error as Error).message;
     }
 
-    return outputs;
+    // Hand the report to the caller through the state directory, the one
+    // channel a hook still has.
+    writeFileSync(join(ctx.stateDir as string, 'report.json'), JSON.stringify(report));
   },
 });

package/src/hooks/test-fixtures/success-hook.ts

@@ -2,9 +2,10 @@
  * Test fixture: successful hook script. Migrated to defineHook in
  * HOOK_API_V2 Phase 8 — the executor now requires the brand.
  *
- * Uses `hook: 'container_created'` because that hook's contract output
- * is `SecretCapturingHookOutput` (Record<string, unknown> | void), so
- * returning an `api_key` field is allowed.
+ * Declares `hook: 'container_created'` and returns void: hook return
+ * values are no longer persisted or consumed (hook-owned-state D5), so a
+ * hook reports through the logger and, where a test needs structured data
+ * back, through a file written to its state directory.
  */
 
 import { defineHook } from '@celilo/capabilities';
@@ -15,6 +16,5 @@ export default defineHook({
   handler: async (ctx) => {
     ctx.logger.info('Starting test hook');
     ctx.logger.success('Test hook completed');
-    return { api_key: `test-key-for-${(ctx.vps_ip as string | undefined) ?? 'unknown'}` };
   },
 });