@celilo/cli 2.3.0 → 3.0.0

package/src/cli/json-output.test.ts

@@ -27,6 +27,7 @@
  * have failed anything. See celilo#703.
  */
 
+import { Database } from 'bun:sqlite';
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
 import { spawnSync } from 'node:child_process';
 import { readFileSync, readdirSync } from 'node:fs';
@@ -49,6 +50,7 @@ const JSON_COMMANDS = [
   'module list --json',
   'module health --json',
   'system audit --json',
+  'system update --dry-run --json',
   'alerts list --json',
   'commands --json',
 ] as const;
@@ -90,6 +92,85 @@ describe('celilo#698 — JSON commands emit parseable JSON', () => {
   }
 });
 
+/**
+ * celilo#1362 — a --json command must stay parseable while its health checks
+ * run. The celilo#698 gates above all fire against an EMPTY fleet, where no
+ * health check ever executes and the pollution path never wakes up: the
+ * gauge silently animated frames onto stdout (plus plain `[module:hook]`
+ * logger lines) for every check, and `system audit --json` redirected to a
+ * file carried ~1 MB of `Testing app` frames before the first `{`.
+ *
+ * This gate seeds a module with a logging, sleeping health_check hook
+ * (`test-fixtures/modules/gauge-pollution-test`) so the checks genuinely
+ * run, then parses each fleet-wide --json command's stdout verbatim.
+ */
+describe('celilo#1362 — --json output stays parseable while health checks run', () => {
+  let ctx: IntegrationTestContext;
+  const FIXTURE_PATH = join(import.meta.dir, '../../test-fixtures/modules/gauge-pollution-test');
+  const MODULE_ID = 'gauge-pollution-test';
+  const SPAWN_ENV = () => ({
+    ...process.env,
+    CELILO_DB_PATH: ctx.dbPath,
+    CELILO_DATA_DIR: ctx.dataDir,
+    CELILO_SUPPRESS_DEPRECATION: '1',
+  });
+
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+
+    const imported = spawnSync(
+      'bun',
+      ['run', 'src/cli/index.ts', 'module', 'import', FIXTURE_PATH],
+      { encoding: 'utf8', env: SPAWN_ENV(), stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 },
+    );
+    expect(
+      imported.status,
+      `module import exited ${imported.status}\nstdout: ${imported.stdout}\nstderr: ${imported.stderr}`,
+    ).toBe(0);
+
+    // runAllHealthChecks only checks INSTALLED/VERIFIED modules. Seeded
+    // the same way capability-abi-mismatch.test.ts seeds providers: the
+    // lifecycle under test is output purity, not the deploy flow.
+    const db = new Database(ctx.dbPath);
+    try {
+      db.run(`UPDATE modules SET state = 'VERIFIED' WHERE id = '${MODULE_ID}'`);
+    } finally {
+      db.close();
+    }
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  for (const command of [
+    'system audit --json',
+    'system update --dry-run --json',
+    'module health --json',
+  ]) {
+    test(`celilo ${command} emits parseable JSON with a health-checked module deployed`, () => {
+      const result = spawnSync('bun', ['run', 'src/cli/index.ts', ...command.split(' ')], {
+        encoding: 'utf8',
+        env: SPAWN_ENV(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 120_000,
+      });
+
+      expect(
+        result.status,
+        `celilo ${command} exited ${result.status}\nstderr: ${result.stderr}`,
+      ).toBe(0);
+
+      // Verbatim JSON.parse — the gauge frames and plain logger lines both
+      // land here pre-fix, and either one alone breaks the parse.
+      expect(() => JSON.parse(result.stdout)).not.toThrow();
+
+      // And the fixture's own log lines must not ride along on stdout.
+      expect(result.stdout).not.toContain('gauge-pollution step');
+    });
+  }
+});
+
 /**
  * Walk from the index of a `{` to the index just past its matching `}`,
  * skipping over string literals so a brace inside a string doesn't unbalance

package/src/cli/types.ts

@@ -35,6 +35,15 @@ export interface CommandError {
   success: false;
   error: string;
   details?: unknown;
+  /**
+   * Marks a refusal that is not a failure: the action was skipped BEFORE any
+   * state changed and will be retried when its precondition holds (the
+   * registry poll defers a consumer upgrade whose capability requirements the
+   * deployed providers cannot serve — celilo#1361). Callers that read only
+   * `success` still see a non-deploy; the poll uses this to report deferrals
+   * separately from failures instead of counting them as red.
+   */
+  deferred?: boolean;
 }
 
 export type CommandResult = CommandSuccess | CommandError;

package/src/hooks/broker.test.ts

@@ -12,7 +12,7 @@
 
 import { describe, expect, test } from 'bun:test';
 import { execSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { MissingProviderInputError } from '@celilo/capabilities';
@@ -60,10 +60,13 @@ async function runCapabilityHook(): Promise<Record<string, unknown>> {
       stateDir: dir,
       capabilities: demoCapabilities(),
     };
-    return await executeHookScript(join(FIXTURES, 'capability-calling-hook.ts'), context, {
+    await executeHookScript(join(FIXTURES, 'capability-calling-hook.ts'), context, {
       timeoutMs: 30_000,
       idleTimeoutMs: 30_000,
     });
+    // The fixture hands its report through the state directory: hook return
+    // values are no longer carried anywhere (hook-owned-state D5).
+    return JSON.parse(readFileSync(join(dir, 'report.json'), 'utf-8')) as Record<string, unknown>;
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
@@ -137,11 +140,14 @@ async function runStoreHook(
       capabilities: {},
       ...contextData,
     } as unknown as HookContext;
-    return await executeHookScript(join(FIXTURES, 'store-writing-hook.ts'), context, {
+    await executeHookScript(join(FIXTURES, 'store-writing-hook.ts'), context, {
       timeoutMs: 30_000,
       idleTimeoutMs: 30_000,
       hookStores: () => Promise.resolve(memoryStores()),
     });
+    // The fixture hands its report through the state directory: hook return
+    // values are no longer carried anywhere (hook-owned-state D5).
+    return JSON.parse(readFileSync(join(dir, 'report.json'), 'utf-8')) as Record<string, unknown>;
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }

package/src/hooks/executor.test.ts

@@ -131,7 +131,8 @@ describe('Hook Executor', () => {
         vps_ip: '10.0.0.1',
       });
 
-      expect(result).toEqual({ api_key: 'test-key-for-10.0.0.1' });
+      // Void hook: no outputs. The envelope carries an empty record.
+      expect(result).toEqual({});
       expect(messages).toContainEqual({ level: 'info', message: 'Starting test hook' });
       expect(messages).toContainEqual({ level: 'success', message: 'Test hook completed' });
     });
@@ -622,7 +623,9 @@ describe('Hook Executor', () => {
       );
 
       expect(result.success).toBe(true);
-      expect(result.outputs).toEqual({ api_key: 'test-key-for-10.0.0.5' });
+      // Hook return values are no longer consumed (hook-owned-state D5): a
+      // void hook's outputs are empty, and nothing persists them.
+      expect(result.outputs).toEqual({});
       expect(result.duration).toBeGreaterThanOrEqual(0);
       expect(messages.some((m) => m.message.includes('completed successfully'))).toBe(true);
     });

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

@@ -31,7 +31,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { executeHookScript } from './executor';
@@ -132,7 +132,7 @@ async function measureReach(): Promise<{ reach: Reach; cleanup: () => void }> {
   const savedPolicy = process.env.CELILO_HOOK_JAIL;
   process.env.CELILO_HOOK_JAIL = 'required';
   try {
-    const reach = (await executeHookScript(PROBE_HOOK, context, {
+    await executeHookScript(PROBE_HOOK, context, {
       timeoutMs: 60_000,
       idleTimeoutMs: 60_000,
       jail: {
@@ -145,7 +145,12 @@ async function measureReach(): Promise<{ reach: Reach; cleanup: () => void }> {
           ? [{ name: 'browser_executable', value: probeBrowserDir(), access: 'read' as const }]
           : [],
       },
-    })) as unknown as Reach;
+    });
+    // The fixture hands its report through the state directory: hook return
+    // values are no longer carried anywhere (hook-owned-state D5).
+    const reach = JSON.parse(
+      readFileSync(join(stateDir, 'report.json'), 'utf-8'),
+    ) as unknown as Reach;
 
     return { reach, cleanup: restorePolicy };
   } catch (error) {

package/src/hooks/hook-jail-unreachability.test.ts

@@ -69,6 +69,9 @@ interface Rig {
   cleanup: () => void;
 }
 
+/** Where the probe fixture hands its report to the parent (hook-owned-state D5). */
+const REPORT_PATH = 'report.json';
+
 /**
  * Lay out a module store the way celilo does, run the probe hook against it,
  * and hand back both the hook's report and the paths so the parent can check
@@ -134,14 +137,19 @@ async function runProbe(): Promise<Rig> {
   const savedPolicy = process.env.CELILO_HOOK_JAIL;
   process.env.CELILO_HOOK_JAIL = 'required';
   try {
-    const outputs = (await executeHookScript(PROBE_HOOK, context, {
+    await executeHookScript(PROBE_HOOK, context, {
       timeoutMs: 60_000,
       idleTimeoutMs: 60_000,
       jail: {
         modulePath,
         pathInputs: [{ name: 'staged_input', value: stagedInput, access: 'write' }],
       },
-    })) as unknown as Rig['outputs'];
+    });
+    // The fixture hands its report through the state directory: hook return
+    // values are no longer carried anywhere (hook-owned-state D5).
+    const outputs = JSON.parse(
+      readFileSync(join(stateDir, REPORT_PATH), 'utf-8'),
+    ) as unknown as Rig['outputs'];
     return {
       outputs,
       stagedInput,

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

@@ -155,14 +155,16 @@ afterAll(() => {
 
 async function runTrespass(jail = false): Promise<{ report: TrespassReport; lines: string[] }> {
   const { logger, messages } = createCapturingLogger();
+  const screenshotDir = mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-'));
+  const stateDir = mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-'));
   const context: HookContext = {
     config: configStore({ sibling_module_id: 'hello-foo', other_system_ip: '' }),
     secrets: secretStore(),
     systems: [],
     logger,
     debug: false,
-    screenshotDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
-    stateDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    screenshotDir,
+    stateDir,
     capabilities: {},
   };
 
@@ -173,7 +175,7 @@ async function runTrespass(jail = false): Promise<{ report: TrespassReport; line
   const savedPolicy = process.env.CELILO_HOOK_JAIL;
   if (jail) process.env.CELILO_HOOK_JAIL = 'required';
   try {
-    const outputs = await executeHookScript(TRESPASS_SCRIPT, context, {
+    await executeHookScript(TRESPASS_SCRIPT, context, {
       timeoutMs: 60_000,
       idleTimeoutMs: 60_000,
       // The module's own tree, two levels above the hook script. Absent means
@@ -181,12 +183,19 @@ async function runTrespass(jail = false): Promise<{ report: TrespassReport; line
       ...(jail ? { jail: { modulePath: dirname(dirname(TRESPASS_SCRIPT)), pathInputs: [] } } : {}),
     });
     return {
-      report: outputs as unknown as TrespassReport,
+      // The fixture hands its report through the state directory the jail
+      // binds read-write: the same channel works jailed and unjailed (D5
+      // removed the return channel).
+      report: JSON.parse(
+        readFileSync(join(stateDir, 'report.json'), 'utf-8'),
+      ) as unknown as TrespassReport,
       lines: messages.map((m) => m.message),
     };
   } finally {
     if (savedPolicy === undefined) delete process.env.CELILO_HOOK_JAIL;
     else process.env.CELILO_HOOK_JAIL = savedPolicy;
+    rmSync(screenshotDir, { recursive: true, force: true });
+    rmSync(stateDir, { recursive: true, force: true });
   }
 }
 

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'}` };
   },
 });