@celilo/cli 2.2.1 → 3.0.0

package/src/policy/capability-shape.ts

@@ -11,7 +11,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import type { CapabilityTableDeclaration, CapabilityTables } from '@celilo/capabilities';
 import ts from 'typescript';
@@ -95,6 +95,216 @@ function printedInterface(file: string, typeName: string): string {
   throw new Error(`${typeName} not found in ${file}`);
 }
 
+// --- REQUEST / RESULT TYPES -------------------------------------------------
+//
+// The interface hash above references its request and result types by NAME
+// only, so an edit to `PublishStaticSiteRequest` never moved a hash. That is
+// the exact hole celilo#1361 fell through: `sourceDir` was removed from three
+// request types, no contract version moved, and every new consumer build died
+// against the deployed providers. Everything below resolves those types and
+// hashes their members, so a request-contract change trips the gate like any
+// interface change — and the recorded member text lets the regenerate script
+// tell a breaking member diff (bump the MAJOR) from an additive one (minor).
+
+interface DeclaredType {
+  file: string;
+  decl: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+  source: ts.SourceFile;
+}
+
+/** All interface and type-alias declarations in one capabilities src file. */
+function declaredTypes(file: string): Map<string, DeclaredType> {
+  const out = new Map<string, DeclaredType>();
+  if (!existsSync(file)) return out;
+  const source = parse(file);
+  for (const statement of source.statements) {
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+      out.set(statement.name.text, { file, decl: statement, source });
+    }
+  }
+  return out;
+}
+
+/** Named relative imports of one file: local name → the file it came from. */
+function importsOf(file: string): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!existsSync(file)) return out;
+  const source = parse(file);
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const specifier = (statement.moduleSpecifier as ts.StringLiteral).text;
+    if (!specifier.startsWith('./')) continue;
+    const target = join(CAPABILITIES_SRC, `${specifier.replace('./', '')}.ts`);
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      out.set(element.name.text, target);
+    }
+  }
+  return out;
+}
+
+/** Type-reference identifiers reachable from one declaration. */
+function referencedTypeNames(decl: ts.Declaration): Set<string> {
+  const out = new Set<string>();
+  const walk = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) {
+      if (ts.isIdentifier(node.typeName)) out.add(node.typeName.text);
+    } else if (ts.isExpressionWithTypeArguments(node)) {
+      if (ts.isIdentifier(node.expression)) out.add(node.expression.text);
+    }
+    ts.forEachChild(node, (child) => walk(child));
+  };
+  walk(decl);
+  return out;
+}
+
+const shapePrinter = ts.createPrinter({ removeComments: true });
+
+/** One member of a request type, in the form the baseline records and diffs. */
+export interface RequestMemberShape {
+  name: string;
+  optional: boolean;
+  /** Printed member type, comments stripped. */
+  type: string;
+}
+
+/** One request or result type a capability's interface can reach. */
+export interface RequestTypeShape {
+  name: string;
+  /** 'alias' types hash as one synthetic `_self` member. */
+  kind: 'interface' | 'alias';
+  members: RequestMemberShape[];
+}
+
+function membersOfDecl(decl: DeclaredType): RequestMemberShape[] {
+  if (ts.isTypeAliasDeclaration(decl.decl)) {
+    return [
+      {
+        name: '_self',
+        optional: false,
+        type: shapePrinter.printNode(ts.EmitHint.Unspecified, decl.decl.type, decl.source),
+      },
+    ];
+  }
+  const members: RequestMemberShape[] = [];
+  for (const member of decl.decl.members) {
+    if (!member.name) continue;
+    const typeNode =
+      ts.isPropertySignature(member) || ts.isMethodSignature(member) ? member.type : undefined;
+    members.push({
+      name: member.name.getText(decl.source),
+      optional: Boolean(member.questionToken),
+      type: typeNode
+        ? shapePrinter.printNode(ts.EmitHint.Unspecified, typeNode, decl.source)
+        : shapePrinter.printNode(ts.EmitHint.Unspecified, member, decl.source),
+    });
+  }
+  return members.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const declsCache = new Map<string, Map<string, DeclaredType>>();
+
+function declsOf(file: string): Map<string, DeclaredType> {
+  let cached = declsCache.get(file);
+  if (!cached) {
+    cached = declaredTypes(file);
+    declsCache.set(file, cached);
+  }
+  return cached;
+}
+
+function allSrcFiles(): string[] {
+  return readdirSync(CAPABILITIES_SRC)
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+    .map((name) => join(CAPABILITIES_SRC, name));
+}
+
+/**
+ * Resolve a referenced type name from the file that references it: the file's
+ * own declarations first, then its named imports, then a unique export
+ * anywhere in packages/capabilities/src. An unresolved name is not contract
+ * surface this repo owns (primitives, DOM types) and is ignored; an ambiguous
+ * one would hash the wrong declaration, so it refuses rather than guessing.
+ */
+function resolveName(name: string, fromFile: string): DeclaredType | undefined {
+  const local = declsOf(fromFile).get(name);
+  if (local) return local;
+  const imported = importsOf(fromFile).get(name);
+  if (imported) {
+    const found = declsOf(imported).get(name);
+    if (found) return found;
+  }
+  const hits: DeclaredType[] = [];
+  for (const file of allSrcFiles()) {
+    const found = declsOf(file).get(name);
+    const exported = found?.decl.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (found && exported) hits.push(found);
+  }
+  if (hits.length === 1) return hits[0];
+  if (hits.length > 1) {
+    throw new Error(
+      `capability-shape: type name '${name}' is declared in ${hits.length} files (${hits.map((h) => h.file).join(', ')}), so its request shape cannot be resolved unambiguously. Rename one of them.`,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Every request/result type reachable from a capability's interface. Names
+ * that resolve to nothing in packages/capabilities/src (primitives, DOM
+ * types) are ignored — they are not contract surface this repo owns.
+ */
+export function requestTypes(capability: string): RequestTypeShape[] {
+  const subject = capabilitySubjects().get(capability);
+  if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
+
+  const start = parse(subject.file);
+  let iface: ts.InterfaceDeclaration | undefined;
+  for (const statement of start.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === subject.typeName) {
+      iface = statement;
+    }
+  }
+  if (!iface) throw new Error(`${subject.typeName} not found in ${subject.file}`);
+
+  const visited = new Set<string>();
+  const shapes: RequestTypeShape[] = [];
+  const queue: Array<{ name: string; fromFile: string }> = [
+    { name: subject.typeName, fromFile: subject.file },
+  ];
+  while (queue.length > 0) {
+    const { name, fromFile } = queue.pop() as { name: string; fromFile: string };
+    if (visited.has(name)) continue;
+    visited.add(name);
+    const decl = resolveName(name, fromFile);
+    if (!decl) continue;
+    const members = membersOfDecl(decl);
+    shapes.push({
+      name,
+      kind: ts.isTypeAliasDeclaration(decl.decl) ? 'alias' : 'interface',
+      members,
+    });
+    const refs = referencedTypeNames(decl.decl);
+    for (const ref of refs) {
+      if (visited.has(ref)) continue;
+      const resolved = resolveName(ref, decl.file);
+      if (resolved) queue.push({ name: ref, fromFile: resolved.file });
+      else visited.add(ref);
+    }
+  }
+  return shapes.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The canonical request-shape text: the baseline's `requests` field, the diff
+ * input for the regenerate guard, and part of the shape hash. Sorted so member
+ * or type reordering is not a shape change.
+ */
+export function requestsKey(capability: string): string {
+  return canonical(requestTypes(capability));
+}
+
 /** Every `* satisfies CapabilityTables` const exported from a capability's module. */
 export async function tablesOf(file: string): Promise<CapabilityTables> {
   const loaded = (await import(file)) as Record<string, unknown>;
@@ -125,5 +335,76 @@ export async function shapeHash(capability: string): Promise<string> {
   if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
   const iface = printedInterface(subject.file, subject.typeName);
   const tables = canonical(await tablesOf(subject.file));
-  return createHash('sha256').update(`${iface}\n--tables--\n${tables}`).digest('hex');
+  // Requests fold into the SAME hash as the interface: a request-contract
+  // change must move the version exactly like an interface change, and the
+  // regenerate script records `requests` beside the hash so it can tell the
+  // breaking member diff from an additive one (see classifyRequestChange).
+  const requests = requestsKey(capability);
+  return createHash('sha256')
+    .update(`${iface}\n--tables--\n${tables}\n--requests--\n${requests}`)
+    .digest('hex');
+}
+
+/** How a capability's request-shape text changed from one recording to the next. */
+export type RequestChangeClassification =
+  | { kind: 'unchanged' }
+  | { kind: 'additive'; note: string }
+  | { kind: 'breaking'; reasons: string[] };
+
+/**
+ * Classify a request-shape change between a baseline recording and the
+ * current code. ONLY these are breaking (the bump rule in
+ * capability-contract.ts):
+ *   - a member was removed (old providers reject the request; old consumers
+ *     stop compiling)
+ *   - a member went optional → required (consumers that omitted it break)
+ *   - a member's type changed (cannot tell widened from narrowed here, so
+ *     treated as breaking; pass --non-breaking to the regenerate script
+ *     when review agrees the widening is safe)
+ * Everything else — adding an optional member, relaxing required → optional —
+ * is additive and takes a minor per the bump rules.
+ */
+export function classifyRequestChange(
+  before: RequestTypeShape[],
+  after: RequestTypeShape[],
+): RequestChangeClassification {
+  const beforeByName = new Map(before.map((t) => [t.name, t]));
+  const afterByName = new Map(after.map((t) => [t.name, t]));
+  const reasons: string[] = [];
+  const additions: string[] = [];
+  for (const [name, oldType] of beforeByName) {
+    const newType = afterByName.get(name);
+    if (!newType) {
+      // A type leaving the reachable set is an interface change, which the
+      // interface hash and its own bump cover. Not a request-level break.
+      continue;
+    }
+    const oldMembers = new Map(oldType.members.map((m) => [m.name, m]));
+    const newMembers = new Map(newType.members.map((m) => [m.name, m]));
+    for (const [memberName, oldMember] of oldMembers) {
+      const newMember = newMembers.get(memberName);
+      if (!newMember) {
+        reasons.push(`${name}.${memberName} was removed`);
+      } else {
+        if (!oldMember.optional && newMember.optional) {
+          additions.push(`${name}.${memberName} became optional`);
+        } else if (oldMember.optional && !newMember.optional) {
+          reasons.push(`${name}.${memberName} went optional → required`);
+        } else if (oldMember.type !== newMember.type) {
+          reasons.push(
+            `${name}.${memberName} changed type (${oldMember.type} → ${newMember.type})`,
+          );
+        }
+      }
+    }
+    for (const newMember of newMembers.values()) {
+      if (!oldMembers.has(newMember.name)) {
+        if (newMember.optional) additions.push(`${name}.${newMember.name} added (optional)`);
+        else reasons.push(`${name}.${newMember.name} added as REQUIRED`);
+      }
+    }
+  }
+  if (reasons.length > 0) return { kind: 'breaking', reasons };
+  if (additions.length > 0) return { kind: 'additive', note: additions.join('; ') };
+  return { kind: 'unchanged' };
 }

package/src/policy/module-script-scan.ts

@@ -82,28 +82,36 @@ export const SWALLOWED_REFUSAL_RULE = 'swallowed framework refusal';
  */
 const CLI_SPAWN_RE =
   /\b(?:execSync|execFileSync|execFile|exec|spawnSync|spawn)\s*\(\s*(?:['"`]\s*celilo(?=\s|['"`])|`[^`]*\bcelilo(?=\s|`))/;
+
+/**
+ * The spawn rule runs against the WHOLE FILE, not one line at a time. The
+ * per-line pass above could not see a call whose argv wrapped onto the next
+ * line — `execFileSync(\n  'celilo', …` — and that blind spot was live:
+ * celilo-registry setup.ts carried a four-line spawn and iptables
+ * firewall-functions.ts three more, all scanning clean while the gate was
+ * green (found by ce-y0we's reach check on 2026-09-09). The regex itself
+ * needs no change — `\s*` already crosses newlines, and `[^\`]*` never
+ * matches a backtick so a template cannot swallow the rest of the file — it
+ * just has to be applied to text wider than a line. Line numbers come from
+ * the match index, so reports still name the line an author fixes.
+ */
+const CLI_SPAWN_BLOCK_RE = new RegExp(CLI_SPAWN_RE.source, 'g');
+
+/** Same wording the rule carried when it ran per line; moved with the pass. */
+const CLI_SPAWN_HINT =
+  'A jailed hook has no celilo binary and no shell, so this dies with ' +
+  '"Executable not found in $PATH" (celilo#1225). Replace the spawn with an ' +
+  'injected capability — context.secrets/context.config for self-config and ' +
+  'self-secrets (openspec/changes/hook-owned-state) — or move the operation ' +
+  'into the framework the way celilo-mgmt on_install did (5e0e624d).';
+
 const FRAMEWORK_CALL_RE = new RegExp(`${CLI_SPAWN_RE.source}|\\brunCelilo\\s*\\(`);
 
 const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
-  {
-    rule: JAILED_CLI_SPAWN_RULE,
-    // Same regex as CLI_SPAWN_RE below — one definition of "reaches the
-    // framework", used by both rules that key on it. Matches the CLI as
-    // argv[0] of a spawn-family call ('celilo' / "celilo"), or inside a shell
-    // string passed to one, where celilo is followed by a word (a subcommand)
-    // or the closing quote — so `docker exec celilo-mgr …`, a `celilo.db` file
-    // name, and prose that merely names the CLI do not fire. What it
-    // deliberately cannot see: a binary path resolved into a variable, or a
-    // spawn reached through an indirection. Same honesty class as the
-    // namespace rule — a lint, not a boundary.
-    re: CLI_SPAWN_RE,
-    hint:
-      'A jailed hook has no celilo binary and no shell, so this dies with ' +
-      '"Executable not found in $PATH" (celilo#1225). Replace the spawn with an ' +
-      'injected capability — context.secrets/context.config for self-config and ' +
-      'self-secrets (openspec/changes/hook-owned-state) — or move the operation ' +
-      'into the framework the way celilo-mgmt on_install did (5e0e624d).',
-  },
+  // NOTE: the jailed-CLI-spawn rule is NOT in this array — it runs in its own
+  // whole-file pass in scanModuleScriptSource (CLI_SPAWN_BLOCK_RE), because a
+  // per-line match missed every spawn whose argv wrapped. Everything else
+  // stays per-line.
   {
     rule: 'raw ssh invocation (StrictHostKeyChecking)',
     re: /StrictHostKeyChecking/,
@@ -200,6 +208,20 @@ export function scanModuleScriptSource(file: string, source: string): ScanViolat
   const violations: ScanViolation[] = [];
   const lines = source.split('\n');
 
+  // The jailed-CLI-spawn pass: whole-file, so a spawn whose argv wraps onto
+  // the next line is still seen (see CLI_SPAWN_BLOCK_RE for the blind spot
+  // that motivated this). Reported on the line the CALL starts, because that
+  // is the site an author fixes.
+  CLI_SPAWN_BLOCK_RE.lastIndex = 0;
+  for (let m = CLI_SPAWN_BLOCK_RE.exec(source); m !== null; m = CLI_SPAWN_BLOCK_RE.exec(source)) {
+    violations.push({
+      file,
+      line: source.slice(0, m.index).split('\n').length,
+      rule: JAILED_CLI_SPAWN_RULE,
+      hint: CLI_SPAWN_HINT,
+    });
+  }
+
   lines.forEach((text, i) => {
     for (const { rule, re, hint } of PATTERN_RULES) {
       if (re.test(text)) violations.push({ file, line: i + 1, rule, hint });
@@ -337,51 +359,19 @@ export interface PolicyDebtEntry {
  * the test goes red, and the entry must be deleted in the same change.
  */
 export const JAILED_CLI_SPAWN_DEBT: readonly PolicyDebtEntry[] = [
-  {
-    module: 'celilo-mgmt',
-    file: 'scripts/on_backup.ts',
-    matches: 1,
-    reason:
-      'hook-owned-state 5.5 / survey class G: machine list becomes a machine-pool read capability',
-  },
   {
     module: 'dnsmasq-dhcp',
     file: 'scripts/dhcp-server-functions.ts',
     matches: 1,
     reason:
-      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
-  },
-  {
-    module: 'forgejo',
-    file: 'scripts/on-consumer-removed.ts',
-    matches: 1,
-    reason: 'hook-owned-state 5.5 (runner_registrations, Group B3)',
+      'capability provider, no hook entry imports it — ce-mqay (jail does not constrain it; conversion is dedup, not breakage)',
   },
   {
-    module: 'forgejo',
-    file: 'scripts/setup.ts',
-    matches: 1,
-    reason: 'hook-owned-state 5.5 (secret set)',
-  },
-  {
-    module: 'forgejo',
-    file: 'scripts/source-forge-functions.ts',
-    matches: 1,
-    reason:
-      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
-  },
-  {
-    module: 'generic-cpanel-hosting-provider',
-    file: 'scripts/on-consumer-removed.ts',
-    matches: 1,
-    reason: 'hook-owned-state 5.5 (publications, Group B4)',
-  },
-  {
-    module: 'generic-cpanel-hosting-provider',
-    file: 'scripts/publish-functions.ts',
-    matches: 1,
+    module: 'iptables',
+    file: 'scripts/firewall-functions.ts',
+    matches: 3,
     reason:
-      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+      'ce-mqay: capability provider, no hook entry imports it. Two config-set writes and one events emit. INVISIBLE to the scan until ce-y0we taught it continuation lines (2026-09-09) — these three were live spawns the green gate could not see',
   },
 ];
 
@@ -393,19 +383,13 @@ export const JAILED_CLI_SPAWN_DEBT: readonly PolicyDebtEntry[] = [
  * same guarded rot: when a site converts, the count drops, the debt test goes
  * red, and the entry must be deleted in the same change.
  *
- * Converted on 2026-09-07 by ce-pvii: knot-unbound-internal/scripts/on-install.ts
- * dropped its last swallow (the runCelilo wrapper), so the rule fires on
- * exactly these two sites and nothing else in the tree.
+ * EMPTY as of ce-y0we (2026-09-09): knot-unbound-internal's on-install dropped
+ * its last swallow on 2026-09-07 (ce-pvii), wireguard's health-check converted
+ * the same evening (01575380), and celilo-mgmt's on_backup machine-pool read
+ * retired the last entry. A NEW swallowed refusal must never land here — it
+ * gets fixed, not tracked.
  */
-export const SWALLOWED_REFUSAL_DEBT: readonly PolicyDebtEntry[] = [
-  {
-    module: 'celilo-mgmt',
-    file: 'scripts/on_backup.ts',
-    matches: 1,
-    reason:
-      'hook-owned-state 5.5 / survey class G: machine list becomes a typed-absent machine-pool read',
-  },
-];
+export const SWALLOWED_REFUSAL_DEBT: readonly PolicyDebtEntry[] = [];
 
 /**
  * The files inside `@celilo/capabilities` that implement the remote-exec

package/src/policy/no-hand-built-ssh.test.ts

@@ -85,7 +85,11 @@ describe('recurrence gate: the jailed-CLI-spawn debt list is honest', () => {
   });
 
   test('the debt list is non-trivial (the guard actually reached the entries)', () => {
-    expect(JAILED_CLI_SPAWN_DEBT.length).toBeGreaterThan(5);
+    // Was >5 while the list still carried the hook-owned-state 5.5 batch. The
+    // conversions retire entries faster than new debt arrives (ce-y0we), so
+    // the floor is now "at least one tracked site" — enough to prove the test
+    // reached the list without pinning the retirement schedule.
+    expect(JAILED_CLI_SPAWN_DEBT.length).toBeGreaterThan(0);
   });
 });
 

package/src/policy/no-swallowed-refusal.test.ts

@@ -212,9 +212,9 @@ describe('recurrence gate: a hook does not swallow a refused framework call', ()
     }
   });
 
-  test('today’s tree: the remaining known sites are flagged, and nothing else is', () => {
+  test('today’s tree: no swallowed refusals anywhere, and the scan still reaches every module', () => {
     // Raw scan, deliberately NOT scanModuleDirectory: the debt list below
-    // exempts these same files so the merged gate stays green while
+    // exempts the same files so the merged gate stays green while
     // hook-owned-state converts them, and this assertion has to outlive that
     // exemption to prove the rule still reaches them.
     const violations = moduleDirs().flatMap((d) =>
@@ -225,13 +225,11 @@ describe('recurrence gate: a hook does not swallow a refused framework call', ()
       ),
     );
     const sites = violations.map((v) => v.file.replace(`${repoRoot()}/`, '')).sort();
-    // Pinned to the exact sites from e2e-suite-recovery task 4.2, as measured
-    // on 2026-09-07 at on_backup.ts:52 (a third, on-install.ts:69, converted
-    // by ce-pvii the same day, and wireguard's health-check.ts converted by
-    // 01575380 the same evening). A converted site drops out and the debt
-    // entry must go; a NEW site appearing here is the next instance this scan
-    // exists to stop.
-    expect(sites).toEqual(['modules/celilo-mgmt/scripts/on_backup.ts']);
+    // Empty since ce-y0we (2026-09-09): on_backup.ts:52 was the last site —
+    // its machine-pool read is staged input now — and the two before it
+    // converted on 2026-09-07 (ce-pvii and 01575380). A NEW site appearing
+    // here is the next instance this scan exists to stop.
+    expect(sites, `Module script policy violations:\n${formatViolations(violations)}`).toEqual([]);
   });
 });
 
@@ -255,10 +253,12 @@ describe('recurrence gate: the swallow debt list is honest', () => {
     }
   });
 
-  test('the debt list is non-trivial (the guard actually reached the entries)', () => {
-    // The list held three entries until ce-pvii converted the on-install.ts
-    // entry and 01575380 converted wireguard's health-check (both
-    // 2026-09-07); one remains, so the guard still proves engagement.
-    expect(SWALLOWED_REFUSAL_DEBT.length).toBeGreaterThan(0);
+  test('the debt list is retired (empty), and this test pins that fact', () => {
+    // The list held three entries when the gate landed; ce-pvii and 01575380
+    // converted two on 2026-09-07 and ce-y0we retired the last (on_backup's
+    // machine-pool read) on 2026-09-09. Kept as an explicit pin so a future
+    // entry has to be justified against this sentence: a swallowed refusal is
+    // a defect to fix, never debt to track.
+    expect(SWALLOWED_REFUSAL_DEBT).toEqual([]);
   });
 });

package/src/registry/client.test.ts

@@ -48,14 +48,14 @@ describe('RegistryClient constructor', () => {
 
   afterEach(() => {
     if (origEnv === undefined) {
-      process.env.CELILO_REGISTRY_URL = undefined;
+      delete process.env.CELILO_REGISTRY_URL;
     } else {
       process.env.CELILO_REGISTRY_URL = origEnv;
     }
   });
 
   test('uses DEFAULT_REGISTRY when no arg and no env var', () => {
-    process.env.CELILO_REGISTRY_URL = undefined;
+    delete process.env.CELILO_REGISTRY_URL;
     const client = new RegistryClient();
     expect(client.baseUrl).toBe(DEFAULT_REGISTRY);
   });
@@ -228,6 +228,71 @@ describe('RegistryClient.publish — Cargo binary protocol', () => {
   });
 });
 
+// ── RegistryClient.publish — failure bodies (ce-sxb3, celilo#1370) ───────────
+
+describe('RegistryClient.publish — failure bodies (ce-sxb3)', () => {
+  let tmpFile: string;
+  let server: ReturnType<typeof Bun.serve> | undefined;
+
+  beforeEach(async () => {
+    tmpFile = `/tmp/test-publish-ce-sxb3-${Date.now()}.netapp`;
+    await Bun.write(tmpFile, 'fake netapp content');
+  });
+
+  afterEach(async () => {
+    server?.stop(true);
+    if (await Bun.file(tmpFile).exists()) await Bun.write(tmpFile, '');
+  });
+
+  function startStubServer(body: string | null, status: number, contentType?: string): string {
+    server = Bun.serve({
+      port: 0,
+      fetch: () =>
+        new Response(body, {
+          status,
+          ...(contentType ? { headers: { 'Content-Type': contentType } } : {}),
+        }),
+    });
+    return `http://localhost:${server.port}`;
+  }
+
+  test('JSON error body reports the refusal detail and the HTTP status', async () => {
+    const client = new RegistryClient(
+      startStubServer(
+        JSON.stringify({ errors: [{ detail: 'version already exists' }] }),
+        409,
+        'application/json',
+      ),
+    );
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('version already exists (HTTP 409)');
+  });
+
+  test('JSON null body names the HTTP status instead of crashing on err.errors', async () => {
+    const client = new RegistryClient(startStubServer('null', 500, 'application/json'));
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 500');
+  });
+
+  test('non-JSON body names the HTTP status', async () => {
+    const client = new RegistryClient(
+      startStubServer('<html>bad gateway</html>', 502, 'text/html'),
+    );
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 502');
+  });
+
+  test('empty body names the HTTP status', async () => {
+    const client = new RegistryClient(startStubServer(null, 403));
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 403');
+  });
+});
+
 // ── module-owner admin endpoints (ce-1ch) ─────────────────────────────────────
 
 describe('RegistryClient owner methods', () => {

package/src/registry/client.ts

@@ -305,10 +305,7 @@ export class RegistryClient {
     });
 
     if (!resp.ok) {
-      const err = (await resp.json().catch(() => ({ errors: [{ detail: resp.statusText }] }))) as {
-        errors: Array<{ detail: string }>;
-      };
-      throw new Error(err.errors?.[0]?.detail ?? `HTTP ${resp.status}`);
+      throw new Error(await this.errorDetail(resp));
     }
 
     return resp.json() as Promise<{ ok: boolean; name: string; vers: string }>;
@@ -364,10 +361,13 @@ export class RegistryClient {
 
   /** Extract `errors[0].detail` from a Cargo-protocol error body, or fall back to the status. */
   private async errorDetail(resp: Response): Promise<string> {
-    const body = (await resp.json().catch(() => ({}))) as {
+    // The body can be a JSON error object, JSON null, prose, or nothing. Only
+    // the first carries a detail; everything else falls back to the status.
+    const body = (await resp.json().catch(() => null)) as {
       errors?: Array<{ detail: string }>;
-    };
-    return body.errors?.[0]?.detail ?? `HTTP ${resp.status}`;
+    } | null;
+    const detail = body?.errors?.[0]?.detail;
+    return detail ? `${detail} (HTTP ${resp.status})` : `HTTP ${resp.status}`;
   }
 
   private async get(url: string): Promise<Response> {