@celilo/cli 2.1.0 → 2.2.0

package/src/hooks/mount-set.ts

@@ -39,6 +39,8 @@ export interface MountEntry {
   readonly mode: MountMode;
   /** Why this row exists. Surfaced by the unjailed lint and by `system doctor`. */
   readonly reason: string;
+  /** What this row's absence from the host means. See `MountAbsence`. */
+  readonly absence: MountAbsence;
 }
 
 export interface MountSet {
@@ -154,8 +156,27 @@ const RESOLVER_FILES = ['/etc/resolv.conf', '/etc/nsswitch.conf', '/etc/hosts']
  */
 const NEVER_MOUNT = ['/usr/bin/bwrap', '/usr/local/bin/bwrap', '/bin/bwrap'] as const;
 
-function entry(path: string, mode: MountMode, reason: string): MountEntry {
-  return { path, mode, reason };
+/**
+ * What a row's ABSENCE from the host means. Required, never defaulted: a default
+ * lets the next mount be added without deciding which kind it is, and that is
+ * exactly how the undifferentiated `skipped` list came to exist.
+ *
+ * bubblewrap fails the whole jail on a bind whose source is missing, so an
+ * absent row must be dropped. The question this answers is whether dropping it
+ * is fine, fatal, or nobody's business.
+ */
+export type MountAbsence =
+  /** Fatal. The hook cannot do what it was asked without this. */
+  | 'required'
+  /** Fatal only for a module that declared it needs the facility. */
+  | 'declared-only'
+  /** Not reported. A genuinely needed one fails the runtime, which is louder. */
+  | 'runtime'
+  /** Expected at some lifecycle points. Debug at most. */
+  | 'conditional';
+
+function entry(path: string, mode: MountMode, reason: string, absence: MountAbsence): MountEntry {
+  return { path, mode, reason, absence };
 }
 
 /**
@@ -182,21 +203,25 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   // silently an empty tmpfs directory writes into it, returns success, and
   // produces a backup containing NOTHING. It is found at restore. So the gate
   // on this asserts the artifact is non-empty, never that the hook exited zero.
-  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run'));
+  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run', 'runtime'));
 
   // 2. The runtime. Without it nothing runs, so it is not really a policy row.
-  entries.push(entry(request.runtimePath, 'ro', 'the interpreter'));
-  entries.push(entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns'));
+  entries.push(entry(request.runtimePath, 'ro', 'the interpreter', 'required'));
+  entries.push(
+    entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns', 'required'),
+  );
   // See MountSetRequest.runtimeModulePaths. Without these the shim starts and
   // immediately dies on `Cannot find module`.
   for (const dir of request.runtimeModulePaths ?? []) {
-    entries.push(entry(resolve(dir), 'ro', "celilo's own dependencies, which the shim imports"));
+    entries.push(
+      entry(resolve(dir), 'ro', "celilo's own dependencies, which the shim imports", 'required'),
+    );
   }
   for (const dir of RUNTIME_SUPPORT_DIRS) {
-    entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
+    entries.push(entry(dir, 'ro', 'shared libraries and trust store', 'runtime'));
   }
   for (const file of RESOLVER_FILES) {
-    entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES'));
+    entries.push(entry(file, 'ro', 'name resolution — see RESOLVER_FILES', 'runtime'));
   }
   // The fleet browser, read-only (task 4.10).
   //
@@ -225,7 +250,9 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   // the browser rather than here. That interim landed 2026-08-31 (celilo#1215):
   // the launch path in `test-fixtures/jail-toolchain-hook.ts` carries the flag,
   // and `jail-browser-launch-flags.test.ts` pins it there.
-  entries.push(entry(BROWSER_ROOT, 'ro', 'the fleet browser, when one is provisioned'));
+  entries.push(
+    entry(BROWSER_ROOT, 'ro', 'the fleet browser, when one is provisioned', 'declared-only'),
+  );
 
   // 3. The module's own tree, read-only, then its writable directories carved
   //    on top. bubblewrap resolves that in the right order, which is why the
@@ -234,19 +261,36 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   //    D9 says "the module's own tree is bound read-only". These are the
   //    carved exceptions to that sentence, and there are three of them rather
   //    than the one D9's prose implies.
-  entries.push(entry(modulePath, 'ro', "the module's own tree"));
+  entries.push(entry(modulePath, 'ro', "the module's own tree", 'required'));
   entries.push(
-    entry(resolve(request.stateDir), 'rw', 'ctx.stateDir, the sanctioned writable directory'),
+    entry(
+      resolve(request.stateDir),
+      'rw',
+      'ctx.stateDir, the sanctioned writable directory',
+      'required',
+    ),
   );
   entries.push(
-    entry(join(modulePath, 'generated'), 'rw', "celilo's generated output the hook may amend"),
+    entry(
+      join(modulePath, 'generated'),
+      'rw',
+      "celilo's generated output the hook may amend",
+      'conditional',
+    ),
   );
   if (request.screenshotDir) {
-    entries.push(entry(resolve(request.screenshotDir), 'rw', 'ctx.screenshotDir, this run only'));
+    entries.push(
+      entry(
+        resolve(request.screenshotDir),
+        'rw',
+        'ctx.screenshotDir, this run only',
+        'conditional',
+      ),
+    );
   }
 
   // 4. The broker channel. Bound AFTER the tmpfs, per the note above.
-  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket'));
+  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket', 'required'));
 
   // 5. Contract-declared path inputs, at the access the contract declares.
   //    Never inferred from the name — see ContractField.path.
@@ -256,6 +300,10 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
         resolve(input.value),
         input.access === 'write' ? 'rw' : 'ro',
         `contract input '${input.name}' (${input.access})`,
+        // Fatal, always. A hook whose declared WRITE path is dropped writes into
+        // the run's private tmpfs and reports success over a directory that is
+        // discarded when it exits. celilo#1248-adjacent; see jail.ts's note.
+        'required',
       ),
     );
   }

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

@@ -26,6 +26,7 @@ import {
 import { remoteAccessPolicy } from '../services/remote-access';
 import { loadCapabilityFunctions } from './capability-loader';
 import { invokeHook } from './executor';
+import { createHookStores } from './hook-store';
 import { loadHookConfigMap } from './load-hook-config';
 import type { HookLogger, HookName, HookResult } from './types';
 
@@ -192,6 +193,7 @@ export async function runNamedHook(
       requiredCapabilities,
       systems: getModuleSystems(moduleId, db),
       remoteAccess: remoteAccessPolicy(moduleId, db),
+      hookStores: () => createHookStores(db, moduleId),
       timeoutMs: options.timeoutMs,
     },
   );

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

@@ -26,7 +26,7 @@ export default defineHook({
   hook: 'container_created',
   requires: [],
   handler: async (ctx) => {
-    const config = ctx.config as {
+    const config = ctx.config as unknown as {
       planted_secret: string;
       sibling_file: string;
       staged_input: string;

package/src/hooks/test-fixtures/on-restore-staging-hook.ts

@@ -0,0 +1,26 @@
+/**
+ * Test fixture: an on_restore hook in the celilo-mgmt staging shape, minus
+ * everything the real one owns but the staging itself. Copies the artifact's
+ * celilo.db into restore_dir/system/ so the Phase 4 wrapper's
+ * applyStagedSystemFiles has something to swap.
+ */
+
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'on_restore',
+  requires: [],
+  optional: [],
+  handler: async (ctx) => {
+    const restoreDir = (ctx as unknown as { restore_dir: string }).restore_dir;
+    const systemDir = join(restoreDir, 'system');
+    mkdirSync(systemDir, { recursive: true });
+    const artifactDb = join(restoreDir, 'celilo.db');
+    if (existsSync(artifactDb)) {
+      cpSync(artifactDb, join(systemDir, 'celilo.db'));
+    }
+    return { restored_items: 1 };
+  },
+});

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

@@ -0,0 +1,47 @@
+import type { HookStore, HookStoreBackedMap } from '@celilo/capabilities';
+
+/**
+ * In-memory hook-owned-state stores for tests that build a HookContext
+ * without a broker. The four methods mutate the record directly; the
+ * manifest validation a real store applies lives broker-side
+ * (hook-store.ts) and has its own tests.
+ *
+ * Methods are defined non-enumerably, so the result spreads, serializes and
+ * `toEqual`s as the plain record the test wrote — the same shape a real
+ * broker-side context carries when executeHookScript frames it.
+ */
+export function configStore(
+  values: Record<string, unknown> = {},
+): Record<string, unknown> & HookStore {
+  return attach(values);
+}
+
+export function secretStore(values: Record<string, string> = {}): HookStoreBackedMap {
+  // 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;
+}
+
+function attach(values: Record<string, unknown>): Record<string, unknown> & HookStore {
+  const store: HookStore = {
+    get: async (name) => values[name] as string | undefined,
+    set: async (name, value) => {
+      values[name] = value;
+    },
+    delete: async (name) => {
+      delete values[name];
+    },
+    transaction: async (fn) => {
+      await fn(store);
+    },
+  };
+  for (const [name, method] of Object.entries(store)) {
+    Object.defineProperty(values, name, {
+      value: method,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return Object.assign(values, store);
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Test fixture: a hook that exercises the hook-owned-state accessor across
+ * 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.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'on_install',
+  requires: [],
+  handler: async (ctx) => {
+    const outputs: Record<string, unknown> = {};
+
+    // Round trip on each store.
+    await ctx.secrets.set('bot_token', 'token-value');
+    outputs.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');
+
+    // The map surface still answers from the values the context carried.
+    outputs.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.
+    // Declared-and-absent is the no-op case 3.7 pins.)
+    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');
+
+    // 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');
+
+    // Discarded transaction: nothing lands, including the overwrite of the
+    // committed value above.
+    try {
+      await ctx.secrets.transaction(async (s) => {
+        s.set('bot_token', 'discarded');
+        throw new Error('hook failed midway');
+      });
+    } catch (error) {
+      outputs.discarded = (error as Error).message;
+    }
+    outputs.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;
+    }
+
+    return outputs;
+  },
+});

package/src/hooks/unjailed-lint.test.ts

@@ -26,6 +26,7 @@ import { executeHookScript, hookChildEnv } from './executor';
 import type { MountSetWire } from './hook-protocol';
 import { createCapturingLogger } from './logger';
 import { deriveMountSet } from './mount-set';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 import { classifyAccess, mountSetEnvValue, parseLintMountSet } from './unjailed-lint';
 
@@ -54,10 +55,25 @@ function scratchModule(script: string): string {
 
 const describeSet = (overrides: Partial<MountSetWire>): MountSetWire => ({
   entries: [
-    { path: '/tmp', mode: 'tmpfs', reason: 'private scratch, per run' },
-    { path: '/srv/celilo/mod', mode: 'ro', reason: "the module's own tree" },
-    { path: '/srv/celilo/mod/state', mode: 'rw', reason: 'the sanctioned writable directory' },
-    { path: '/srv/staged', mode: 'rw', reason: "contract input 'backup_dir' (write)" },
+    { path: '/tmp', mode: 'tmpfs', reason: 'private scratch, per run', absence: 'runtime' },
+    {
+      path: '/srv/celilo/mod',
+      mode: 'ro',
+      reason: "the module's own tree",
+      absence: 'required',
+    },
+    {
+      path: '/srv/celilo/mod/state',
+      mode: 'rw',
+      reason: 'the sanctioned writable directory',
+      absence: 'required',
+    },
+    {
+      path: '/srv/staged',
+      mode: 'rw',
+      reason: "contract input 'backup_dir' (write)",
+      absence: 'required',
+    },
   ],
   chdir: '/srv/celilo/mod',
   ...overrides,
@@ -159,8 +175,8 @@ describe('the lint inside a real hook run', () => {
     mkdirSync(join(root, 'state'), { recursive: true });
     const { logger, messages } = createCapturingLogger();
     const context: HookContext = {
-      config: {},
-      secrets: {},
+      config: configStore(),
+      secrets: secretStore(),
       systems: [],
       logger,
       debug: false,

package/src/manifest/schema.ts

@@ -17,6 +17,7 @@ export const VariableSourceSchema = z.enum([
   'system',
   'terraform',
   'infrastructure',
+  'hook',
 ]);
 
 /**

package/src/module/packaging/build.ts

@@ -1,8 +1,9 @@
 import { execFileSync, execSync } from 'node:child_process';
-import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join, relative } from 'node:path';
+import { gunzipSync } from 'node:zlib';
 import { create as tarCreate } from 'tar';
 import { parse as parseYaml } from 'yaml';
 import { log } from '../../cli/prompts';
@@ -120,6 +121,33 @@ export async function computeChecksums(sourceDir: string): Promise<ChecksumsData
   };
 }
 
+/**
+ * Ceiling on the final tar+gzip write of the .netapp. Every step before it
+ * (staging, the module's own build command) already carries a timeout, but the
+ * tar stream did not — and 2026-09-04 it stalled mid-write (all samples in
+ * kevent64, artifact truncated at 59 percent) and sat there for two hours with
+ * no error and no exit. A bounded wait turns that into a nameable failure.
+ */
+const PACKAGE_STREAM_TIMEOUT_MS = 300_000;
+
+/**
+ * Validate that a produced .netapp is a complete gzip stream.
+ *
+ * A .netapp is a gzipped tar (tarCreate above runs with gzip: true), so a
+ * full gunzip pass is the whole check: a stream truncated mid-write fails
+ * with 'unexpected end of file' instead of surviving to the consumer, where
+ * the same zlib error reads as a truncated DOWNLOAD from an unrelated cause.
+ * Returns null when valid, otherwise the reason.
+ */
+export function verifyNetappIntegrity(packagePath: string): string | null {
+  try {
+    gunzipSync(readFileSync(packagePath));
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
 /**
  * Build a module package (.netapp file)
  *
@@ -321,7 +349,7 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
 
     // Create tarball
     const finalOutputPath = outputPath || join(process.cwd(), `${moduleId}.netapp`);
-    await tarCreate(
+    const tarPromise = tarCreate(
       {
         file: finalOutputPath,
         cwd: buildDir,
@@ -329,6 +357,46 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
       },
       ['checksums.json', 'signature.sig', ...Object.keys(checksumsData.files)],
     );
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () =>
+          reject(
+            new Error(
+              `packaging tar stream exceeded ${PACKAGE_STREAM_TIMEOUT_MS / 1000}s and was abandoned mid-write`,
+            ),
+          ),
+        PACKAGE_STREAM_TIMEOUT_MS,
+      );
+    });
+    timer?.unref?.();
+    try {
+      await Promise.race([tarPromise, timeout]);
+    } catch (tarError) {
+      // The losing side may still hold the output file open: swallow its
+      // eventual rejection and remove the partial artifact so nothing
+      // downstream mistakes a truncated write for a package.
+      tarPromise.catch(() => {});
+      rmSync(finalOutputPath, { force: true });
+      return {
+        success: false,
+        error: `Failed to build module: ${
+          tarError instanceof Error ? tarError.message : 'Unknown error'
+        }`,
+      };
+    }
+
+    // Refuse to declare success on an artifact we cannot read back. The tar
+    // step resolved, so this only trips if the stream left the file truncated
+    // anyway — the exact corruption build-infra shipped on 2026-09-04.
+    const integrityError = verifyNetappIntegrity(finalOutputPath);
+    if (integrityError) {
+      rmSync(finalOutputPath, { force: true });
+      return {
+        success: false,
+        error: `Produced package failed gzip integrity check (${finalOutputPath}): ${integrityError}`,
+      };
+    }
 
     return {
       success: true,

package/src/module/web-root.ts

@@ -14,7 +14,7 @@
  */
 
 import { join } from 'node:path';
-import { MODULE_WEB_ROOT } from '@celilo/capabilities';
+import { MODULE_STATE_WEB_ROOT, MODULE_WEB_ROOT } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { modules } from '../db/schema';
@@ -33,3 +33,19 @@ export function resolveModuleWebRoot(moduleId: string, db: DbClient): string | u
   if (!module) return undefined;
   return join(module.sourcePath, MODULE_WEB_ROOT);
 }
+
+/**
+ * Absolute path to `<module root>/state/site` — the state web overlay
+ * (celilo#1265) — or undefined when no such module is installed.
+ *
+ * Beside `resolveModuleWebRoot` for the same reason that function lives here:
+ * ONE application of the convention, by the one party that can resolve it for
+ * a module that is not running. Does NOT check that the directory exists — a
+ * module with no generated site content has no overlay, and deciding what an
+ * absent directory means belongs to the caller (see `requireWebRoot`).
+ */
+export function resolveModuleStateWebRoot(moduleId: string, db: DbClient): string | undefined {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return undefined;
+  return join(module.sourcePath, MODULE_STATE_WEB_ROOT);
+}