@celilo/cli 1.11.0 → 1.13.0

package/src/hooks/jail.ts

@@ -0,0 +1,491 @@
+/**
+ * The hook jail's caller (openspec/changes/hook-process-boundary, D8 and D9).
+ *
+ * `mount-set.ts` computes WHAT a hook may see. This file decides whether a jail
+ * is available at all, turns that computation into a command line, and records
+ * which of the two happened. It is the half that touches the machine, kept out
+ * of the derivation so the derivation stays hermetic.
+ *
+ * Three things live here and they answer three different questions:
+ *
+ *   - `detectJailBackend()` — CAN this host jail? Measured by running
+ *     bubblewrap, never by looking for the binary. D8's table records four
+ *     distinct denials that all leave `bwrap` sitting on disk.
+ *   - `planJailedSpawn()` — pure. Given a backend, a policy and a mount set,
+ *     what command does celilo spawn? (Rule 10.4.)
+ *   - `recordJailMode()` — WHICH happened, written down. D8 is explicit that
+ *     the mode is state and not a log line: a per-invocation warning on a fleet
+ *     that deploys often is noise, noise gets filtered, and filtered is
+ *     indistinguishable from absent. The row that matters is a host that used
+ *     to jail and has stopped, and you cannot see a transition in a log nobody
+ *     reads.
+ */
+
+import { execFileSync } from 'node:child_process';
+import type { Dirent } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getDataDir } from '../config/paths';
+import { type MountSet, type MountSetRequest, toBwrapArgs } from './mount-set';
+
+/** Which jail celilo can build here. `none` means the hook runs unjailed. */
+export type JailBackend = 'bubblewrap' | 'none';
+
+/**
+ * What the operator asked for. `CELILO_HOOK_JAIL`, and the default is `auto`.
+ *
+ * `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
+ * than a recorded fact. `off` is the escape hatch for the reverse case — a
+ * hook that has not yet been walked against the jail (task 4.13) and needs to
+ * run today.
+ */
+export type JailPolicy = 'auto' | 'off' | 'required';
+
+/** Whether the hook that just ran was jailed. The recorded state (D8). */
+export type JailMode = 'jailed' | 'unjailed';
+
+export interface JailAvailability {
+  readonly backend: JailBackend;
+  /**
+   * Why there is no backend, in one sentence an operator can act on.
+   * Absent when there is one. `celilo system doctor` surfaces it (task 4.6).
+   */
+  readonly reason?: string;
+}
+
+export interface JailPlan {
+  /** The command celilo spawns, jail wrapper included. */
+  readonly cmd: readonly string[];
+  readonly mode: JailMode;
+  readonly backend: JailBackend;
+  readonly reason?: string;
+  /**
+   * Mount rows the derivation asked for that do not exist on this host.
+   *
+   * bubblewrap fails the whole jail on a bind whose SOURCE is missing, and
+   * several rows are legitimately absent: `/lib64` does not exist on arm64,
+   * `<module>/generated` only appears once celilo has generated something, and
+   * `~/.ssh` need not exist at all. Dropping them is the caller's job rather
+   * than the derivation's, which is why they are reported rather than silently
+   * filtered — a contract input landing here is a real defect and this is
+   * where it becomes visible.
+   */
+  readonly skipped: readonly string[];
+}
+
+/**
+ * Namespace flags, shared by the probe and the real spawn so they cannot
+ * drift.
+ *
+ * A probe that clears a weaker bar than the spawn is the failure CLAUDE.md
+ * names: a correct assertion about the wrong subject. If any flag here is
+ * denied, the probe fails and celilo records `unjailed` instead of discovering
+ * it one hook at a time.
+ *
+ * **`--unshare-net` is deliberately absent.** D9 says the network is not
+ * namespaced; D12 scopes reachability by withholding the credential instead.
+ *
+ * `--unshare-pid` needs a fresh `/proc` or the jail shows the host's process
+ * table, and `/proc/1/root` is a well-worn way to read out of one. It also
+ * makes the kill in D7 total: `bwrap` is pid 1 inside the namespace, and the
+ * kernel reaps every process in a pid namespace whose init dies.
+ *
+ * `--new-session` is NOT here. It defends against TIOCSTI injection into a
+ * controlling terminal, and the child is spawned with `stdout: 'pipe'` and no
+ * tty, so there is nothing to inject into.
+ */
+const JAIL_NAMESPACE_ARGS = [
+  '--unshare-user',
+  '--unshare-ipc',
+  '--unshare-pid',
+  '--unshare-uts',
+  // The one unshare that legitimately may be unavailable on an older kernel.
+  '--unshare-cgroup-try',
+  '--die-with-parent',
+  '--proc',
+  '/proc',
+  '--dev',
+  '/dev',
+] as const;
+
+/**
+ * The jail builder.
+ *
+ * Resolved from `PATH` rather than pinned to `/usr/bin/bwrap`. The AppArmor
+ * profile D8 ships attaches BY PATH, so a `bwrap` found somewhere else carries
+ * no profile — but that case fails the probe below rather than passing
+ * silently, and celilo then records `unjailed` with the parser's own message.
+ * A visible wrong answer is worth more than a pinned path that is wrong on a
+ * distribution nobody tested.
+ */
+const BWRAP = 'bwrap';
+
+/** How long to wait for the probe before calling the backend unavailable. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+const JAIL_MODE_FILE = 'hook-jail-mode.json';
+
+/** Cleared by nothing: a host does not gain a jail mid-process. */
+let probed: JailAvailability | undefined;
+
+/**
+ * Can this host build a jail? Measured, cached for the process.
+ *
+ * The probe RUNS bubblewrap, with the same namespace flags the real spawn
+ * uses, against a whole-filesystem bind. Presence is not the question: D8
+ * measured four distinct denials — a missing `CAP_SYS_ADMIN`, a seccomp
+ * filter, an AppArmor policy, and Docker's masked `/proc` — and every one of
+ * them leaves the binary exactly where it was.
+ *
+ * `bun` is the command because it is the one binary guaranteed to be here: we
+ * are running in it. A probe that execs `/bin/true` fails for a missing
+ * `/bin/true` and reads exactly like a denied namespace.
+ */
+export function detectJailBackend(): JailAvailability {
+  if (!probed) probed = probeJailBackend();
+  return probed;
+}
+
+function probeJailBackend(): JailAvailability {
+  if (process.platform === 'darwin') {
+    // `sandbox-exec` is measured working (D8) but the backend that generates
+    // its profile is task 4.8 and is not built. Claiming macOS is jailed
+    // because the tool exists would be the fail-open jail D8 calls worse than
+    // no jail at all.
+    return {
+      backend: 'none',
+      reason:
+        'macOS has no hook jail yet: the sandbox-exec backend is designed but not built (hook-process-boundary task 4.8). Hooks run unjailed on this host.',
+    };
+  }
+  if (process.platform !== 'linux') {
+    return {
+      backend: 'none',
+      reason: `No hook jail backend exists for platform '${process.platform}'. Hooks run unjailed on this host.`,
+    };
+  }
+
+  try {
+    execFileSync(
+      BWRAP,
+      [...JAIL_NAMESPACE_ARGS, '--ro-bind', '/', '/', '--', process.execPath, '--version'],
+      { stdio: 'ignore', timeout: PROBE_TIMEOUT_MS },
+    );
+    return { backend: 'bubblewrap' };
+  } catch (error) {
+    return { backend: 'none', reason: unavailableReason(error) };
+  }
+}
+
+/**
+ * Turn the probe's failure into something an operator can act on.
+ *
+ * Deliberately reads the FAILURE and not a message: D8 records one string
+ * (`setting up uid map: Permission denied`) arriving from two unrelated
+ * causes, which is why the guidance names both rather than guessing.
+ */
+function unavailableReason(error: unknown): string {
+  const spawnFailure = (error as { code?: string } | null)?.code;
+  if (spawnFailure === 'ENOENT') {
+    return 'bubblewrap is not installed, so hooks run unjailed. Install it (`apt install bubblewrap`) and re-run.';
+  }
+  return [
+    'bubblewrap is installed but could not build a namespace, so hooks run unjailed.',
+    'On Ubuntu 24.04 this is kernel.apparmor_restrict_unprivileged_userns=1 refusing a user namespace to an unprofiled binary;',
+    'celilo ships /etc/apparmor.d/celilo-hook-jail to grant it, so check that the profile loaded (`apparmor_parser -Q --skip-cache /etc/apparmor.d/celilo-hook-jail`).',
+    'Inside a container it is more likely a dropped capability or a masked /proc.',
+  ].join(' ');
+}
+
+/**
+ * What the operator asked for, from `CELILO_HOOK_JAIL`.
+ *
+ * Fails fast on a value it does not know (Rule 4.2). A typo'd
+ * `CELILO_HOOK_JAIL=requried` that silently meant `auto` would read as the
+ * jail being enforced when it is not, which is the one mistake this variable
+ * exists to prevent.
+ */
+export function jailPolicy(): JailPolicy {
+  const raw = process.env.CELILO_HOOK_JAIL;
+  if (raw === undefined || raw === '') return 'auto';
+  if (raw === 'auto' || raw === 'off' || raw === 'required') return raw;
+  throw new Error(
+    `CELILO_HOOK_JAIL='${raw}' is not a hook jail policy. Use 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off'.`,
+  );
+}
+
+/**
+ * Resolve every path in a mount-set request through the filesystem (task 4.2k).
+ *
+ * `deriveMountSet` is pure and says so: it resolves lexically, which cannot
+ * follow a symlink. Two reasons the caller has to.
+ *
+ * `modulePath` is `mod.sourcePath` out of the database, and a database
+ * restored from another box carries that box's absolute paths (ISS-0052,
+ * `restore-from-file.ts`).
+ *
+ * And on macOS the whole jail turns on it: `/tmp` is a symlink to
+ * `/private/tmp`, a `sandbox-exec` rule naming the unresolved path is silently
+ * not applied, the access succeeds, and nothing reports an error (D8,
+ * measured). That backend is task 4.8, but the resolution belongs here now so
+ * it is not a thing 4.8 has to remember.
+ *
+ * A path that does not exist keeps its lexical form. It cannot be resolved and
+ * it will not survive `planJailedSpawn`'s existence filter either.
+ */
+export function realpathRequest(request: MountSetRequest): MountSetRequest {
+  return {
+    ...request,
+    modulePath: realpathOrSelf(request.modulePath),
+    stateDir: realpathOrSelf(request.stateDir),
+    screenshotDir: request.screenshotDir ? realpathOrSelf(request.screenshotDir) : undefined,
+    socketDir: realpathOrSelf(request.socketDir),
+    runtimePath: realpathOrSelf(request.runtimePath),
+    runnerPath: realpathOrSelf(request.runnerPath),
+    runtimeModulePaths: request.runtimeModulePaths?.map(realpathOrSelf),
+    pathInputs: request.pathInputs.map((input) => ({
+      ...input,
+      value: realpathOrSelf(input.value),
+    })),
+    sshDir: request.sshDir ? realpathOrSelf(request.sshDir) : undefined,
+  };
+}
+
+/**
+ * The `node_modules` directories the runner shim resolves its own imports
+ * through, nearest first.
+ *
+ * The shim is not self-contained: it imports `isCompiledHook` from
+ * `@celilo/capabilities` and Zod through `hook-protocol.ts`. Node resolution
+ * walks up from the importing file looking for `node_modules` at each
+ * ancestor, so this walks the same ladder and keeps whichever rungs exist.
+ *
+ * **It collects only directories literally named `node_modules`, and that is
+ * the safety property.** Under an npm install the shim sits at
+ * `/var/celilo/node_modules/@celilo/cli/src/hooks/`, so the ancestor holding
+ * its dependencies is `/var/celilo` — and binding THAT would put `master.key`
+ * and `celilo.db` inside the jail, which is the one outcome the whole change
+ * exists to prevent. Appending `node_modules` before testing for existence is
+ * what makes the difference, so do not "simplify" this into binding the
+ * ancestor itself.
+ */
+export function runtimeModulePathsFor(
+  runnerPath: string,
+  exists: (path: string) => boolean = existsSync,
+): string[] {
+  const found: string[] = [];
+  let dir = dirname(runnerPath);
+  for (;;) {
+    const candidate = join(dir, 'node_modules');
+    if (exists(candidate)) {
+      found.push(candidate);
+      found.push(...linkedPackageDirs(candidate));
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return [...new Set(found)];
+    dir = parent;
+  }
+}
+
+/**
+ * Package directories inside `dir` that are reachable ONLY through a symlink.
+ *
+ * A workspace install — bun's, pnpm's — puts a link in `node_modules` pointing
+ * sideways at `packages/<x>`. Binding `node_modules` binds the link and not
+ * what it points at, and the shim then dies on
+ * `ENOENT reading ".../node_modules/@celilo/capabilities"`. That is the second
+ * of the two failures this walk exists to prevent, and like the first it was
+ * found by running the jail rather than by reading it.
+ *
+ * An npm install has real directories here, so this finds nothing and costs
+ * one `readdir`. That is why it is written as the general case rather than as
+ * a development special case: the two shapes are the same rule, and a
+ * dev-only branch here would be a jail nobody tests until production.
+ */
+function linkedPackageDirs(dir: string): string[] {
+  const linked: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return linked;
+  }
+
+  for (const entry of entries) {
+    // `.bin` holds links to executables, not to packages. Following them binds
+    // single files and buys nothing.
+    if (entry.name === '.bin') continue;
+    const path = join(dir, entry.name);
+    // A scope is a real directory whose MEMBERS are the links.
+    if (entry.isDirectory() && entry.name.startsWith('@')) {
+      linked.push(...linkedPackageDirs(path));
+      continue;
+    }
+    if (!entry.isSymbolicLink()) continue;
+    try {
+      const target = realpathSync(path);
+      if (statSync(target).isDirectory()) linked.push(target);
+    } catch {
+      // A dangling link resolves to nothing and binds nothing.
+    }
+  }
+  return linked;
+}
+
+function realpathOrSelf(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Decide the command celilo spawns.
+ *
+ * Planning function (Rule 10.4) — pure, so every branch below is testable
+ * without a jail, which matters because the host running the tests usually has
+ * no jail at all.
+ *
+ * @param cmd - The unjailed command: the runtime and the runner shim.
+ * @param set - The derived mount set, or `undefined` when the caller has no
+ *   module tree to jail (the executor's own fixtures, and the bus handler path).
+ */
+export function planJailedSpawn(
+  cmd: readonly string[],
+  set: MountSet | undefined,
+  availability: JailAvailability,
+  policy: JailPolicy,
+  exists: (path: string) => boolean = existsSync,
+): JailPlan {
+  if (policy === 'off') {
+    return {
+      cmd,
+      mode: 'unjailed',
+      backend: availability.backend,
+      reason: 'CELILO_HOOK_JAIL=off: the operator switched the hook jail off on this host.',
+      skipped: [],
+    };
+  }
+
+  if (availability.backend === 'none' || !set) {
+    const reason = set
+      ? availability.reason
+      : '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(),
+      );
+    }
+    return { cmd, mode: 'unjailed', backend: availability.backend, reason, skipped: [] };
+  }
+
+  // A tmpfs needs no source — bubblewrap creates it — so it is never dropped.
+  const present = set.entries.filter((e) => e.mode === 'tmpfs' || exists(e.path));
+  const skipped = set.entries.filter((e) => !present.includes(e)).map((e) => e.path);
+
+  return {
+    cmd: [
+      BWRAP,
+      ...JAIL_NAMESPACE_ARGS,
+      ...toBwrapArgs({ ...set, entries: present }),
+      '--',
+      ...cmd,
+    ],
+    mode: 'jailed',
+    backend: availability.backend,
+    skipped,
+  };
+}
+
+export interface JailModeRecord {
+  readonly mode: JailMode;
+  readonly backend: JailBackend;
+  readonly reason?: string;
+  /**
+   * The host this was measured on.
+   *
+   * D8's third state — "unjailed, was jailed yesterday" — is the only one that
+   * raises an alert, and it is defined per host. Without this the same file
+   * copied between boxes, or a database restored onto a new one, reads as a
+   * transition that never happened.
+   */
+  readonly host: string;
+  readonly recordedAt: string;
+}
+
+/**
+ * Where the mode is written. `CELILO_HOOK_JAIL_MODE_PATH` overrides it, the
+ * same way `subscriber-store.ts` takes an override for the same reason.
+ */
+export function jailModeStorePath(): string {
+  return process.env.CELILO_HOOK_JAIL_MODE_PATH ?? join(getDataDir(), JAIL_MODE_FILE);
+}
+
+/** The last recorded mode, or `undefined` if nothing has recorded one yet. */
+export function readJailMode(): JailModeRecord | undefined {
+  const path = jailModeStorePath();
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as JailModeRecord;
+  } catch {
+    // A corrupt file is the same as no file for every consumer: the next run
+    // overwrites it. Throwing here would fail a hook over a state write.
+    return undefined;
+  }
+}
+
+/**
+ * Write down which mode this run used, and return what it replaced.
+ *
+ * The previous record is returned rather than acted on. A jailed-to-unjailed
+ * transition on the same host is what raises the self-monitor alert, and that
+ * monitor is task 4.4 — this is the state it will read.
+ *
+ * Best effort by design: a read-only data directory must not fail a hook.
+ */
+export function recordJailMode(plan: JailPlan): { previous?: JailModeRecord } {
+  const previous = readJailMode();
+  const record: JailModeRecord = {
+    mode: plan.mode,
+    backend: plan.backend,
+    ...(plan.reason ? { reason: plan.reason } : {}),
+    host: hostname(),
+    recordedAt: new Date().toISOString(),
+  };
+
+  if (
+    previous &&
+    previous.host === record.host &&
+    previous.mode === record.mode &&
+    previous.backend === record.backend
+  ) {
+    // Unchanged. Rewriting it every hook would churn the file and lose the
+    // one timestamp worth having: when the mode last CHANGED.
+    return { previous };
+  }
+
+  const path = jailModeStorePath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`);
+    renameSync(tmp, path);
+  } catch {
+    // Deliberately swallowed, and the only place in this file that is. The
+    // mode is diagnostic state; a hook must not fail because celilo could not
+    // write it down.
+  }
+  return { previous };
+}

package/src/hooks/mount-set.ts

@@ -84,6 +84,25 @@ export interface MountSetRequest {
   readonly runtimePath: string;
   /** The runner shim, which lives in celilo's tree rather than the module's. */
   readonly runnerPath: string;
+  /**
+   * The `node_modules` directories the shim resolves its OWN imports through,
+   * nearest first. Empty means the shim is self-contained, which it is not.
+   *
+   * This row exists because the jail was run rather than read. `bwrap` built
+   * the namespace correctly, applied every mount below, and the shim then died
+   * on `Cannot find module '@celilo/capabilities'` — it imports `isCompiledHook`
+   * from there and Zod through `hook-protocol.ts`, and both resolve ABOVE
+   * `dirname(runnerPath)`. Under npm that is `/var/celilo/node_modules`; in the
+   * repo it is the workspace root's. Neither is inside the shim's directory,
+   * so without this the jail cannot start a hook at all, anywhere.
+   *
+   * The caller walks the filesystem for these (`runtimeModulePathsFor`), which
+   * is why they arrive as an argument rather than being computed here. Only
+   * directories literally NAMED `node_modules` are ever collected, and that is
+   * what keeps `/var/celilo` — `master.key`, `celilo.db` — out of the jail
+   * while `/var/celilo/node_modules` goes into it.
+   */
+  readonly runtimeModulePaths?: readonly string[];
   /** Contract-declared path inputs, already resolved to values. */
   readonly pathInputs: readonly DeclaredPathInput[];
   /**
@@ -154,6 +173,11 @@ export function deriveMountSet(request: MountSetRequest): MountSet {
   // 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'));
+  // 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"));
+  }
   for (const dir of RUNTIME_SUPPORT_DIRS) {
     entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
   }

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

@@ -0,0 +1,59 @@
+/**
+ * Test fixture: reports what a hook can and cannot reach from inside the jail.
+ *
+ * Every probe reports an OUTCOME rather than throwing, because the assertion
+ * that matters is unreachability and not any particular errno (task 4.9).
+ * 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.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { defineHook } from '@celilo/capabilities';
+
+function probe(fn: () => void): { succeeded: boolean; detail: string } {
+  try {
+    fn();
+    return { succeeded: true, detail: 'ok' };
+  } catch (error) {
+    return { succeeded: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    const config = ctx.config as {
+      planted_secret: string;
+      sibling_file: string;
+      staged_input: string;
+    };
+
+    return {
+      // 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.
+      planted_secret: probe(() => {
+        readFileSync(config.planted_secret, 'utf-8');
+      }),
+      // A sibling module's tree. `<store>` itself is never bound, so one `..`
+      // reaches nothing.
+      sibling_write: probe(() => {
+        writeFileSync(config.sibling_file, 'trespassed');
+      }),
+      // The carve-out: `state/` sits INSIDE the read-only module tree and is
+      // bound read-write on top of it.
+      state_write: probe(() => {
+        writeFileSync(`${ctx.stateDir}/jail-probe`, 'state is writable');
+      }),
+      // A declared path input under os.tmpdir(), which D9 also makes a fresh
+      // tmpfs. If the tmpfs did not lead, this write lands in a private
+      // filesystem that vanishes when the hook exits — and the hook SUCCEEDS.
+      // The parent asserts the bytes survived, which is the only way to tell.
+      staged_write: probe(() => {
+        writeFileSync(`${config.staged_input}/produced`, 'staged input survived the tmpfs');
+      }),
+    };
+  },
+});

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

@@ -0,0 +1,48 @@
+/**
+ * The `icon` field's refinement (openspec/changes/module-icons, D3).
+ *
+ * This is the trust boundary: `manifest.yml` is hand-edited and the value ends
+ * up drawn in a coloured row, so the check that it is monochrome-capable lives
+ * here rather than in any consumer.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { ModuleManifestSchema } from './schema';
+
+function manifestWith(icon?: string): Record<string, unknown> {
+  return {
+    celilo_contract: '1.0',
+    id: 'icon-fixture',
+    name: 'Icon Fixture',
+    version: '1.0.0',
+    ...(icon === undefined ? {} : { icon }),
+  };
+}
+
+describe('manifest icon', () => {
+  test('accepts a BMP non-emoji scalar', () => {
+    const parsed = ModuleManifestSchema.parse(manifestWith('⛨'));
+    expect(parsed.icon).toBe('⛨');
+  });
+
+  test('accepts absence', () => {
+    const parsed = ModuleManifestSchema.parse(manifestWith());
+    expect(parsed.icon).toBeUndefined();
+  });
+
+  test('rejects U+1F512, naming the monochrome reason rather than the range', () => {
+    const result = ModuleManifestSchema.safeParse(manifestWith('🔒'));
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('expected the padlock to be rejected');
+    const message = result.error.issues[0]?.message ?? '';
+    expect(message).toContain('monochrome');
+    expect(message).toContain('U+1F512');
+  });
+
+  test('rejects a two-character string', () => {
+    const result = ModuleManifestSchema.safeParse(manifestWith('⛨⛨'));
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('expected two characters to be rejected');
+    expect(result.error.issues[0]?.message ?? '').toContain('exactly one character');
+  });
+});