@indigoai-us/hq-cli 5.5.1 → 5.5.2-sentry-rc.0

package/src/sentry-before-send.ts

@@ -0,0 +1,221 @@
+// src/sentry-before-send.ts — canonical fleet scrubber
+// Line 1 is per-repo — see "Per-repo `import type` line" table in Step 3.
+// hq-console uses @sentry/nextjs. Consumer steps override to their own SDK.
+import type { ErrorEvent, EventHint } from "@sentry/node";
+
+const SENSITIVE_FIELD_NAMES = new Set([
+  "password", "secret", "apikey", "api_key", "token",
+  // Cognito token-response fields captured as error context.
+  "idtoken", "accesstoken", "refreshtoken",
+]);
+
+// Stored lowercased; membership tested against `name.toLowerCase()`.
+// MUST cover BOTH Auth.js v5 (current in hq-console, pinned to
+// next-auth@5.0.0-beta.25 which resolves @auth/core@0.37.2) AND legacy
+// NextAuth v4 name spaces — covering both is cheap and survives accidental
+// downgrades or mixed-version repos. Grounded against @auth/core@0.37.2's
+// src/lib/utils/cookie.ts (re-ground via `grep -nE
+// '(sessionToken|callbackUrl|csrfToken|pkceCodeVerifier|state|nonce|webauthnChallenge): \{'
+// node_modules/.pnpm/@auth+core@0.37.2/node_modules/@auth/core/src/lib/utils/cookie.ts`
+// — seven matches, one per cookie family): two distinct prefixing patterns
+// coexist there, and the entries below mirror BOTH exactly:
+//   • session-token / callback-url / pkce.code_verifier / state / nonce /
+//     challenge each pair the bare form (HTTP dev, cookiePrefix="") with
+//     the __Secure- form (HTTPS prod, cookiePrefix="__Secure-").
+//   • csrf-token is special: the source explicitly uses __Host- (NOT
+//     __Secure-) under HTTPS for stricter cookie scoping (the csrfToken
+//     entry in @auth/core's cookie.ts is the only one whose name template
+//     uses `__Host-` instead of `${cookiePrefix}`; the comment above it
+//     reads "Default to __Host- for CSRF token for additional protection
+//     if using useSecureCookies"). The set therefore pairs the bare form
+//     with __Host-, and does NOT include __Secure-authjs.csrf-token
+//     because @auth/core never emits that name. The legacy v4 entry mirrors
+//     the same pattern (bare next-auth.csrf-token + __Host-next-auth.csrf-token,
+//     no __Secure- variant).
+// Missing any of the four OAuth-state families (pkce.code_verifier, state,
+// nonce, challenge) ships a cookie-leak in the same class as the v4-only
+// defect Round-4 called out. This set is the single authoritative spec;
+// all of Steps 3/8/9a/12/13 reproduce it identically.
+//
+// MAINTAINER NOTE: Do NOT extend this set by mechanically pairing every
+// cookie with bare + __Secure- + __Host-. The pairing follows the source:
+// session-style cookies use __Secure-; csrf-style cookies use __Host-.
+// New entries added in the future must be grounded against the actual
+// emitter (Auth.js source for v5/v4, vendor docs for Clerk, etc.) rather
+// than copied from the existing pattern.
+const SENSITIVE_COOKIE_NAMES = new Set([
+  // ==== Auth.js v5 (next-auth@5 / @auth/core) ====
+  // Session JWT — bare + __Secure-
+  "authjs.session-token",
+  "__secure-authjs.session-token",
+  // CSRF double-submit token — bare + __Host- ONLY (@auth/core's cookie.ts
+  // csrfToken entry uses __Host-, never __Secure-)
+  "authjs.csrf-token",
+  "__host-authjs.csrf-token",
+  // Post-auth redirect URL — bare + __Secure-
+  "authjs.callback-url",
+  "__secure-authjs.callback-url",
+  // OAuth PKCE verifier — leaking this enables interception of an in-flight
+  // OAuth code exchange.
+  "authjs.pkce.code_verifier",
+  "__secure-authjs.pkce.code_verifier",
+  // OAuth CSRF/replay protection
+  "authjs.state",
+  "__secure-authjs.state",
+  // OpenID Connect nonce — replay protection
+  "authjs.nonce",
+  "__secure-authjs.nonce",
+  // OAuth WebAuthn challenge
+  "authjs.challenge",
+  "__secure-authjs.challenge",
+  // ==== NextAuth v4 legacy names (kept so accidental downgrades /
+  //       mixed-version monorepos don't silently leak). Same prefix
+  //       discipline as v5: csrf-token uses __Host-, others use __Secure-. ====
+  "next-auth.session-token",
+  "__secure-next-auth.session-token",
+  "next-auth.csrf-token",
+  "__host-next-auth.csrf-token",
+  "next-auth.callback-url",
+  "__secure-next-auth.callback-url",
+  "next-auth.pkce.code_verifier",
+  "__secure-next-auth.pkce.code_verifier",
+  "next-auth.state",
+  "__secure-next-auth.state",
+  // ==== Clerk (documented for future; no-op today) ====
+  "__clerk_db_jwt", "__session",
+]);
+
+const REDACTED = "[Filtered]";
+
+const SENSITIVE_HEADER_NAMES = new Set([
+  "authorization", "proxy-authorization",
+  "cookie", "set-cookie",
+  "x-api-key", "x-auth-token", "x-access-token", "x-session-token",
+]);
+
+function scrubHeaders(h?: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (!h) return h;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(h)) {
+    out[k] = SENSITIVE_HEADER_NAMES.has(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+}
+
+type CookieField = Record<string, unknown> | string | undefined;
+
+function scrubCookies(c: CookieField): CookieField {
+  if (!c) return c;
+  if (typeof c === "string") return REDACTED; // raw Cookie header — wholesale redact
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(c)) {
+    out[k] = SENSITIVE_COOKIE_NAMES.has(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+}
+
+const SENSITIVE_STRING_PATTERNS: RegExp[] = [
+  // kv pairs; `(?:id|access|refresh)[_-]?token` catches Cognito-style free-text
+  // `accessToken=...`, `refreshToken: ...`, `id_token=...` which bare `\btoken` misses.
+  /\b(password|secret|api[_-]?key|(?:id|access|refresh)[_-]?token|token)\s*[:=]\s*[^\s&"'<>]+/gi,
+  /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+];
+
+function scrubString(s: string): string {
+  let out = s;
+  for (const re of SENSITIVE_STRING_PATTERNS) {
+    out = out.replace(re, (m) => {
+      const sep = m.search(/[:=\s]/);
+      return sep > 0 ? `${m.slice(0, sep + 1)}${REDACTED}` : REDACTED;
+    });
+  }
+  return out;
+}
+
+function scrubQueryString(qs: string): string {
+  try {
+    const params = new URLSearchParams(qs.startsWith("?") ? qs.slice(1) : qs);
+    const out: string[] = [];
+    for (const [k, v] of params) {
+      out.push(`${k}=${SENSITIVE_FIELD_NAMES.has(k.toLowerCase()) ? REDACTED : v}`);
+    }
+    const joined = out.join("&");
+    return qs.startsWith("?") ? `?${joined}` : joined;
+  } catch {
+    return scrubString(qs);
+  }
+}
+
+function scrubFields<T>(value: T, memo: Map<object, unknown> = new Map()): T {
+  if (value === null || typeof value !== "object") return value;
+  const obj = value as unknown as object;
+  // On cycle revisit, return the SAME scrubbed copy built on first visit —
+  // NOT the original. Returning the original would leak fields reachable
+  // only through the cycle (e.g., a.self.token).
+  if (memo.has(obj)) return memo.get(obj) as T;
+
+  if (Array.isArray(value)) {
+    const arr: unknown[] = [];
+    memo.set(obj, arr);
+    for (const v of value) arr.push(scrubFields(v, memo));
+    return arr as unknown as T;
+  }
+
+  const out: Record<string, unknown> = {};
+  memo.set(obj, out);
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (SENSITIVE_FIELD_NAMES.has(k.toLowerCase())) {
+      out[k] = REDACTED;
+    } else if (v !== null && typeof v === "object") {
+      out[k] = scrubFields(v, memo);
+    } else if (typeof v === "string") {
+      // SCALAR-STRING DEFENSE-IN-DEPTH. A stringified log line stashed via
+      // setExtra / setContext / setUser can embed `password=...` or a Bearer
+      // token even when the outer key (`note`, `bio`, `log_line`, …) isn't
+      // in SENSITIVE_FIELD_NAMES. Route scalar strings through scrubString so
+      // these don't bypass the scrubber on their way into Sentry.
+      out[k] = scrubString(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out as unknown as T;
+}
+
+export function beforeSend(event: ErrorEvent, _hint: EventHint): ErrorEvent | null {
+  if (event.request) {
+    const req = event.request as { headers?: unknown; cookies?: unknown; data?: unknown; query_string?: unknown };
+    event.request = {
+      ...event.request,
+      headers: scrubHeaders(req.headers as Record<string, unknown> | undefined) as typeof event.request.headers,
+      cookies: scrubCookies(req.cookies as CookieField) as typeof event.request.cookies,
+      data: scrubFields(req.data),
+      query_string:
+        typeof req.query_string === "string"
+          ? scrubQueryString(req.query_string)
+          : (req.query_string as typeof event.request.query_string),
+    };
+  }
+  if (typeof event.message === "string") event.message = scrubString(event.message);
+  if (event.exception?.values) {
+    event.exception = {
+      ...event.exception,
+      values: event.exception.values.map((v) => ({
+        ...v,
+        value: typeof v.value === "string" ? scrubString(v.value) : v.value,
+      })),
+    };
+  }
+  if (event.user) event.user = scrubFields(event.user as Record<string, unknown>) as typeof event.user;
+  if (event.breadcrumbs) {
+    event.breadcrumbs = event.breadcrumbs.map((b) => ({
+      ...b,
+      message: typeof b.message === "string" ? scrubString(b.message) : b.message,
+      data: b.data ? scrubFields(b.data) : b.data,
+    }));
+  }
+  if (event.extra) event.extra = scrubFields(event.extra);
+  if (event.contexts) event.contexts = scrubFields(event.contexts);
+  return event;
+}

package/src/sentry.test.ts

@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as Sentry from "@sentry/node";
+import { initSentry } from "./sentry.js";
+
+vi.mock("./sentry-dsn.generated.js", () => ({ BUNDLED_DSN: "" }));
+
+describe("initSentry — empty BUNDLED_DSN no-op", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("fakeTransport.send is never called after captureException + flush(2000) when no DSN configured", async () => {
+    vi.stubEnv("SENTRY_DSN", "");
+
+    const fakeTransport = { send: vi.fn().mockResolvedValue(undefined) };
+
+    initSentry();
+
+    Sentry.captureException(new Error("no-dsn-should-not-send"));
+    await Sentry.flush(2000);
+
+    expect(fakeTransport.send).not.toHaveBeenCalled();
+  });
+});

package/src/sentry.ts

@@ -0,0 +1,19 @@
+import * as Sentry from "@sentry/node";
+import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
+import { beforeSend } from "./sentry-before-send.js";
+
+export function initSentry(): void {
+  const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
+  if (!dsn) return;
+  Sentry.init({
+    dsn,
+    release: `hq-cli@${process.env.npm_package_version ?? "0.0.0"}`,
+    environment: process.env.HQ_CLI_ENV ?? "production",
+    initialScope: {
+      tags: { repo: "hq-cli" },
+    },
+    beforeSend,
+  });
+}
+
+export { Sentry };

package/src/strategies/link.ts

@@ -5,10 +5,10 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ModuleDefinition, SyncResult } from '../types.js';
+import type { LegacyModuleDefinition, SyncResult } from '../types.js';
 
 export async function linkSync(
-  module: ModuleDefinition,
+  module: LegacyModuleDefinition,
   moduleDir: string,
   hqRoot: string
 ): Promise<SyncResult> {

package/src/strategies/merge.ts

@@ -6,7 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import type { ModuleDefinition, SyncResult, SyncState } from '../types.js';
+import type { LegacyModuleDefinition, SyncResult, SyncState } from '../types.js';
 import { readState, writeState } from '../utils/manifest.js';
 
 function hashFile(filePath: string): string {
@@ -69,7 +69,7 @@ function copyRecursive(
 }
 
 export async function mergeSync(
-  module: ModuleDefinition,
+  module: LegacyModuleDefinition,
   moduleDir: string,
   hqRoot: string
 ): Promise<SyncResult> {

package/src/types.ts

@@ -1,8 +1,15 @@
 /**
  * HQ Module Manifest Types (US-001)
+ *
+ * `modules.yaml` hosts two kinds of entries, discriminated by `strategy`:
+ *   - link | merge | copy  → git-repo-based module sync (existing flow)
+ *   - package              → hq-pack content pack installed via `hq install`
+ *                            (new in hq-core v12.0.0; see
+ *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
 
-export type SyncStrategy = 'link' | 'merge' | 'copy';
+export type LegacyStrategy = 'link' | 'merge' | 'copy';
+export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
 
 export interface PathMapping {
@@ -10,15 +17,28 @@ export interface PathMapping {
   dest: string;  // Path in HQ tree (relative to HQ root)
 }
 
-export interface ModuleDefinition {
+export interface LegacyModuleDefinition {
   name: string;
   repo: string;              // Git URL (https or git@)
   branch?: string;           // Default: main
-  strategy: SyncStrategy;    // link | merge | copy
+  strategy: LegacyStrategy;
   paths: PathMapping[];      // What to sync and where
-  access?: AccessLevel;      // For future RBAC
+  access?: AccessLevel;
 }
 
+export interface PackModuleDefinition {
+  name: string;              // e.g. 'hq-pack-gstack'
+  strategy: 'package';
+  source: string;            // '@scope/name@ver' | git URL#sha | local path
+  version?: string;          // semver from the pack's package.yaml
+  installed_at?: string;     // e.g. 'packages/hq-pack-gstack'
+  installed_at_iso?: string; // ISO timestamp
+  resolved_sha?: string;     // git transport only
+  access?: AccessLevel;
+}
+
+export type ModuleDefinition = LegacyModuleDefinition | PackModuleDefinition;
+
 export interface ModulesManifest {
   version: '1';
   modules: ModuleDefinition[];
@@ -45,3 +65,33 @@ export interface SyncResult {
   message?: string;
   filesChanged?: number;
 }
+
+// ---------------------------------------------------------------------------
+// hq-pack content-pack manifest (packages/{name}/package.yaml).
+//
+// Distinct from packages/hq-cli/src/schemas/hq-package.schema.json, which
+// covers the entitlement-gated registry flow (`hq packages install <slug>`).
+// ---------------------------------------------------------------------------
+
+export type PackContributeKey =
+  | 'workers'
+  | 'knowledge'
+  | 'skills'
+  | 'commands'
+  | 'hooks'
+  | 'policies'
+  | 'scripts';
+
+export interface PackManifest {
+  name: string;                 // ^hq-pack-[a-z0-9][a-z0-9-]*$
+  version: string;              // semver
+  publisher: string;            // @scope
+  access: 'public' | 'private';
+  requires: { hqCore: string }; // semver range
+  contributes: Partial<Record<PackContributeKey, string[]>>;
+  description?: string;
+  license?: string;
+  repository?: string;
+  keywords?: string[];
+  conditional?: string;         // bash predicate; skip install if exits non-zero
+}

package/src/utils/cognito-session.ts

@@ -65,13 +65,13 @@ export async function ensureCognitoToken(options: {
   if (cached) {
     try {
       if (interactive) {
-        console.log(chalk.dim("  Refreshing expiring HQ session..."));
+        console.error(chalk.dim("  Refreshing expiring HQ session..."));
       }
       const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
       return refreshed.accessToken;
     } catch (err) {
       if (interactive) {
-        console.log(
+        console.error(
           chalk.dim(
             `  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`,
           ),
@@ -86,7 +86,7 @@ export async function ensureCognitoToken(options: {
     );
   }
 
-  console.log(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
+  console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
   const tokens = await browserLogin(DEFAULT_COGNITO);
   return tokens.accessToken;
 }

package/src/utils/manifest.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Regression tests for manifest path resolution.
+ *
+ * Bug caught during hq-core-split S3 testing (2026-04-21): prior to this
+ * fix, `getManifestPath()` returned a flat path (`{hqRoot}/modules.yaml`),
+ * but real HQ installs use the nested layout (`{hqRoot}/modules/modules.yaml`).
+ * Running `hq install` against a real HQ would silently create a shadow
+ * manifest at the root, orphaning the canonical nested one.
+ *
+ * These tests lock in:
+ *   1. Nested layout is preferred when it exists.
+ *   2. Flat layout is honored when (and only when) it already exists.
+ *   3. Fresh HQs default to writing the nested form — never shadow-writing
+ *      a root-level `modules.yaml`.
+ *   4. Read/write round-trips correctly against the nested layout.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+
+import {
+  addModule,
+  getManifestPath,
+  readManifest,
+  writeManifest,
+} from './manifest.js';
+import type { ModulesManifest } from '../types.js';
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-manifest-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+const sampleManifest: ModulesManifest = {
+  version: '1',
+  modules: [
+    {
+      name: 'knowledge-public-hq-core',
+      repo: 'https://github.com/indigoai-us/knowledge-public-hq-core.git',
+      strategy: 'link',
+      paths: [
+        {
+          src: '.',
+          dest: 'knowledge/public/hq-core',
+        },
+      ],
+    },
+  ],
+};
+
+describe('getManifestPath', () => {
+  it('prefers nested modules/modules.yaml when it exists', () => {
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    fs.mkdirSync(path.dirname(nested), { recursive: true });
+    fs.writeFileSync(nested, yaml.dump(sampleManifest));
+
+    expect(getManifestPath(tmpRoot)).toBe(nested);
+  });
+
+  it('honors legacy flat modules.yaml when only the flat form exists', () => {
+    // Legacy fixtures / very old HQ instances may pre-date the nested layout.
+    const flat = path.join(tmpRoot, 'modules.yaml');
+    fs.writeFileSync(flat, yaml.dump(sampleManifest));
+
+    expect(getManifestPath(tmpRoot)).toBe(flat);
+  });
+
+  it('defaults to nested path on a fresh HQ (neither file exists)', () => {
+    // Regression: previously returned the flat path, which meant writeManifest
+    // created a shadow root-level manifest on real HQs.
+    expect(getManifestPath(tmpRoot)).toBe(
+      path.join(tmpRoot, 'modules', 'modules.yaml'),
+    );
+  });
+});
+
+describe('readManifest / writeManifest round-trip', () => {
+  it('round-trips against the nested layout', () => {
+    writeManifest(tmpRoot, sampleManifest);
+
+    const nested = path.join(tmpRoot, 'modules', 'modules.yaml');
+    expect(fs.existsSync(nested)).toBe(true);
+
+    const roundTripped = readManifest(tmpRoot);
+    expect(roundTripped).toEqual(sampleManifest);
+  });
+
+  it('writes into the nested modules/ dir on fresh HQs (creates dir)', () => {
+    // The nested dir does not exist yet — writeManifest must mkdir-p.
+    expect(fs.existsSync(path.join(tmpRoot, 'modules'))).toBe(false);
+
+    writeManifest(tmpRoot, sampleManifest);
+
+    expect(fs.existsSync(path.join(tmpRoot, 'modules'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpRoot, 'modules', 'modules.yaml'))).toBe(
+      true,
+    );
+  });
+
+  it('does NOT shadow-write a root-level modules.yaml on fresh HQs', () => {
+    // This is the original bug: pre-fix, writeManifest on a fresh HQ created
+    // `{hqRoot}/modules.yaml`, which shadowed the canonical nested manifest.
+    writeManifest(tmpRoot, sampleManifest);
+
+    expect(fs.existsSync(path.join(tmpRoot, 'modules.yaml'))).toBe(false);
+  });
+
+  it('rewrites into the flat layout when flat already exists (legacy compat)', () => {
+    const flat = path.join(tmpRoot, 'modules.yaml');
+    fs.writeFileSync(flat, yaml.dump({ version: '1', modules: [] }));
+
+    writeManifest(tmpRoot, sampleManifest);
+
+    // Flat stays flat; no silent migration to nested, no shadow write.
+    expect(fs.existsSync(flat)).toBe(true);
+    expect(
+      fs.existsSync(path.join(tmpRoot, 'modules', 'modules.yaml')),
+    ).toBe(false);
+
+    const reread = readManifest(tmpRoot);
+    expect(reread).toEqual(sampleManifest);
+  });
+});
+
+describe('addModule', () => {
+  it('appends to the existing nested manifest without creating a flat shadow', () => {
+    writeManifest(tmpRoot, sampleManifest);
+
+    addModule(tmpRoot, {
+      name: 'knowledge-public-testing',
+      repo: 'https://github.com/indigoai-us/knowledge-public-testing.git',
+      strategy: 'link',
+      paths: [{ src: '.', dest: 'knowledge/public/testing' }],
+    });
+
+    const after = readManifest(tmpRoot);
+    expect(after?.modules).toHaveLength(2);
+    expect(fs.existsSync(path.join(tmpRoot, 'modules.yaml'))).toBe(false);
+  });
+});

package/src/utils/manifest.ts

@@ -18,8 +18,25 @@ export function findHqRoot(): string {
   return process.cwd();
 }
 
+/**
+ * Resolve the manifest path for a given HQ root.
+ *
+ * The canonical layout is nested: `{hqRoot}/modules/modules.yaml` (catalog)
+ * alongside `{hqRoot}/modules/<module-name>/` (clone targets).
+ *
+ * Legacy fixtures and very old HQ instances may have the flat layout
+ * (`{hqRoot}/modules.yaml`); we honor that if — and only if — the flat file
+ * already exists. On fresh HQs we default to the nested form so we never
+ * silently create a second shadow manifest at the root.
+ *
+ * Exported for tests.
+ */
 export function getManifestPath(hqRoot: string): string {
-  return path.join(hqRoot, MANIFEST_FILE);
+  const nested = path.join(hqRoot, 'modules', MANIFEST_FILE);
+  const flat = path.join(hqRoot, MANIFEST_FILE);
+  if (fs.existsSync(nested)) return nested;
+  if (fs.existsSync(flat)) return flat;
+  return nested; // default for fresh HQs — see getModulesDir()
 }
 
 export function getLockPath(hqRoot: string): string {
@@ -45,6 +62,10 @@ export function readManifest(hqRoot: string): ModulesManifest | null {
 
 export function writeManifest(hqRoot: string, manifest: ModulesManifest): void {
   const manifestPath = getManifestPath(hqRoot);
+  // Ensure the parent directory exists — on a fresh HQ the nested
+  // `modules/` dir may not yet be present, and fs.writeFileSync does not
+  // auto-mkdir. Safe no-op when the dir already exists.
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   const content = yaml.dump(manifest, { lineWidth: -1 });
   fs.writeFileSync(manifestPath, content);
 }