@indigoai-us/hq-cloud 6.11.15 → 6.11.16

package/src/agent-codex-instructions.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  composeCodexAgentsMd,
+  orderCapabilityFiles,
+  gatherCodexAgentSections,
+  materializeCodexAgents,
+  codexHomeDir,
+  CODEX_AGENTS_MARKER,
+  AGENT_CONTRACT_FILE,
+  AGENTS_PROFILE_REL,
+  AGENT_CAPABILITIES_REL,
+  type CodexSection,
+} from "./agent-codex-instructions.js";
+
+describe("composeCodexAgentsMd (pure)", () => {
+  it("returns empty string for no sections", () => {
+    expect(composeCodexAgentsMd([])).toBe("");
+  });
+
+  it("returns empty string when every section is whitespace-only", () => {
+    const sections: CodexSection[] = [
+      { name: "a", content: "   \n\t " },
+      { name: "b", content: "" },
+    ];
+    expect(composeCodexAgentsMd(sections)).toBe("");
+  });
+
+  it("emits the generated marker header then the joined body", () => {
+    const out = composeCodexAgentsMd([
+      { name: "profile", content: "I am the agent." },
+      { name: "contract", content: "Build your own tools." },
+    ]);
+    expect(out.startsWith(CODEX_AGENTS_MARKER)).toBe(true);
+    expect(out).toContain("I am the agent.");
+    expect(out).toContain("Build your own tools.");
+    // body sections separated by a blank line, trailing newline
+    expect(out).toContain("I am the agent.\n\nBuild your own tools.");
+    expect(out.endsWith("\n")).toBe(true);
+  });
+
+  it("trims sections and drops the empty ones", () => {
+    const out = composeCodexAgentsMd([
+      { name: "a", content: "\n\n  kept  \n\n" },
+      { name: "b", content: "   " },
+      { name: "c", content: "also" },
+    ]);
+    expect(out).toContain("kept\n\nalso");
+    expect(out).not.toMatch(/ {2}kept/);
+  });
+
+  it("is deterministic / carries no timestamp (idempotent bytes)", () => {
+    const sections = [{ name: "x", content: "stable" }];
+    expect(composeCodexAgentsMd(sections)).toBe(composeCodexAgentsMd(sections));
+  });
+});
+
+describe("orderCapabilityFiles (pure)", () => {
+  it("orders the contract first, then the rest alphabetically", () => {
+    expect(
+      orderCapabilityFiles(["slack.md", "zeta.md", AGENT_CONTRACT_FILE, "alpha.md"]),
+    ).toEqual([AGENT_CONTRACT_FILE, "alpha.md", "slack.md", "zeta.md"]);
+  });
+
+  it("drops non-markdown entries", () => {
+    expect(
+      orderCapabilityFiles([AGENT_CONTRACT_FILE, "_seed-allowlist.yaml", "notes.txt", "x.md"]),
+    ).toEqual([AGENT_CONTRACT_FILE, "x.md"]);
+  });
+
+  it("handles a missing contract gracefully", () => {
+    expect(orderCapabilityFiles(["b.md", "a.md"])).toEqual(["a.md", "b.md"]);
+  });
+});
+
+describe("gatherCodexAgentSections + materializeCodexAgents (IO)", () => {
+  let hqRoot: string;
+  let codexHome: string;
+  const capDir = () => path.join(hqRoot, AGENT_CAPABILITIES_REL);
+
+  beforeEach(() => {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-codex-test-"));
+    hqRoot = path.join(base, "hq");
+    codexHome = path.join(base, ".codex");
+    fs.mkdirSync(capDir(), { recursive: true });
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(path.dirname(hqRoot), { recursive: true, force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  });
+
+  const seedProfile = (s: string) =>
+    fs.writeFileSync(path.join(hqRoot, AGENTS_PROFILE_REL), s);
+  const seedCap = (name: string, s: string) =>
+    fs.writeFileSync(path.join(capDir(), name), s);
+
+  it("gathers profile + contract + others in the right order", () => {
+    fs.mkdirSync(path.join(hqRoot, "personal"), { recursive: true });
+    seedProfile("PROFILE briefing");
+    seedCap("slack.md", "SLACK doc");
+    seedCap(AGENT_CONTRACT_FILE, "CONTRACT body");
+
+    const sections = gatherCodexAgentSections(hqRoot);
+    expect(sections.map((s) => s.name)).toEqual([
+      AGENTS_PROFILE_REL,
+      `${AGENT_CAPABILITIES_REL}/${AGENT_CONTRACT_FILE}`,
+      `${AGENT_CAPABILITIES_REL}/slack.md`,
+    ]);
+  });
+
+  it("writes ~/.codex/AGENTS.md with contract ahead of other capabilities", () => {
+    seedCap(AGENT_CONTRACT_FILE, "CONTRACT body");
+    seedCap("slack.md", "SLACK doc");
+
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    expect(res.written).toBe(true);
+    expect(res.sectionCount).toBe(2);
+
+    const written = fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8");
+    expect(written.startsWith(CODEX_AGENTS_MARKER)).toBe(true);
+    expect(written.indexOf("CONTRACT body")).toBeLessThan(
+      written.indexOf("SLACK doc"),
+    );
+  });
+
+  it("SKIPS (no write, no delete) when the overlay is empty — never destructive", () => {
+    // Pre-existing materialized file from a prior good sync.
+    fs.mkdirSync(codexHome, { recursive: true });
+    const existing = `${CODEX_AGENTS_MARKER} prior -->\n\nPRIOR CONTENT\n`;
+    fs.writeFileSync(path.join(codexHome, "AGENTS.md"), existing);
+
+    // Overlay is empty (transient unsynced tree).
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    expect(res.written).toBe(false);
+    expect(res.skippedReason).toBe("empty-overlay");
+    // The previously-materialized file is left intact.
+    expect(fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8")).toBe(
+      existing,
+    );
+  });
+
+  it("creates the codex home dir if missing", () => {
+    seedCap(AGENT_CONTRACT_FILE, "CONTRACT body");
+    expect(fs.existsSync(codexHome)).toBe(false);
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    expect(res.written).toBe(true);
+    expect(fs.existsSync(path.join(codexHome, "AGENTS.md"))).toBe(true);
+  });
+
+  it("is idempotent — two runs produce byte-identical output", () => {
+    seedCap(AGENT_CONTRACT_FILE, "CONTRACT body");
+    seedCap("slack.md", "SLACK doc");
+    materializeCodexAgents({ hqRoot, codexHome });
+    const first = fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8");
+    materializeCodexAgents({ hqRoot, codexHome });
+    const second = fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8");
+    expect(second).toBe(first);
+  });
+
+  it("never throws on an unreadable hq-root (returns error result)", () => {
+    const res = materializeCodexAgents({
+      hqRoot: path.join(hqRoot, "does-not-exist"),
+      codexHome,
+    });
+    expect(res.written).toBe(false);
+    // No capability dir → empty overlay → skip (not a hard error).
+    expect(res.skippedReason).toBe("empty-overlay");
+  });
+});
+
+describe("materializeCodexAgents — hardening (security + failure modes)", () => {
+  let base: string;
+  let hqRoot: string;
+  let codexHome: string;
+  const capDir = () => path.join(hqRoot, AGENT_CAPABILITIES_REL);
+
+  beforeEach(() => {
+    base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-codex-harden-"));
+    hqRoot = path.join(base, "hq");
+    codexHome = path.join(base, ".codex");
+    fs.mkdirSync(capDir(), { recursive: true });
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    try {
+      fs.rmSync(base, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  });
+
+  it("does NOT follow a symlinked capability file (no out-of-tree exfiltration)", () => {
+    // A secret outside the overlay; a symlink inside capDir pointing at it.
+    const secret = path.join(base, "secret.txt");
+    fs.writeFileSync(secret, "TOP-SECRET-CREDENTIAL");
+    fs.writeFileSync(path.join(capDir(), AGENT_CONTRACT_FILE), "CONTRACT body");
+    fs.symlinkSync(secret, path.join(capDir(), "escape.md"));
+
+    const sections = gatherCodexAgentSections(hqRoot);
+    // The symlink is skipped; only the real contract file is gathered.
+    expect(sections.map((s) => s.name)).toEqual([
+      `${AGENT_CAPABILITIES_REL}/${AGENT_CONTRACT_FILE}`,
+    ]);
+
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    const written = fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8");
+    expect(written).not.toContain("TOP-SECRET-CREDENTIAL");
+    expect(res.sectionCount).toBe(1);
+  });
+
+  it("skips a symlinked capability DIR (no descent through a symlinked capDir)", () => {
+    // Replace capDir with a symlink to an external dir containing a real .md.
+    const external = path.join(base, "external-caps");
+    fs.mkdirSync(external, { recursive: true });
+    fs.writeFileSync(path.join(external, AGENT_CONTRACT_FILE), "EXTERNAL body");
+    fs.rmSync(capDir(), { recursive: true, force: true });
+    fs.symlinkSync(external, capDir());
+
+    const sections = gatherCodexAgentSections(hqRoot);
+    expect(sections).toEqual([]);
+  });
+
+  it("refuses to clobber a SYMLINK target (preserves it; distinct skip reason)", () => {
+    fs.writeFileSync(path.join(capDir(), AGENT_CONTRACT_FILE), "CONTRACT body");
+    fs.mkdirSync(codexHome, { recursive: true });
+    const realTarget = path.join(base, "managed-agents.md");
+    fs.writeFileSync(realTarget, "MANAGED BY DOTFILES");
+    fs.symlinkSync(realTarget, path.join(codexHome, "AGENTS.md"));
+
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    expect(res.written).toBe(false);
+    expect(res.skippedReason).toBe("target-not-regular-file");
+    // The symlink is intact and still points at the managed file.
+    expect(fs.lstatSync(path.join(codexHome, "AGENTS.md")).isSymbolicLink()).toBe(
+      true,
+    );
+    expect(fs.readFileSync(realTarget, "utf8")).toBe("MANAGED BY DOTFILES");
+  });
+
+  it("refuses when the target is a DIRECTORY (no EISDIR crash, distinct reason)", () => {
+    fs.writeFileSync(path.join(capDir(), AGENT_CONTRACT_FILE), "CONTRACT body");
+    fs.mkdirSync(path.join(codexHome, "AGENTS.md"), { recursive: true });
+
+    const res = materializeCodexAgents({ hqRoot, codexHome });
+    expect(res.written).toBe(false);
+    expect(res.skippedReason).toBe("target-not-regular-file");
+    expect(fs.statSync(path.join(codexHome, "AGENTS.md")).isDirectory()).toBe(true);
+  });
+
+  it("returns an error result and leaves no .hq-tmp orphan when the write fails", () => {
+    // Root ignores mode bits, so this deterministic perms-based failure only
+    // holds for a non-root user (agent boxes + CI run non-root).
+    if (typeof process.getuid === "function" && process.getuid() === 0) return;
+    fs.writeFileSync(path.join(capDir(), AGENT_CONTRACT_FILE), "CONTRACT body");
+    // Read-only codex home → the temp write inside it fails (EACCES). The
+    // write+rename block's catch must unlink any temp before rethrowing, so no
+    // `*.hq-tmp` is left behind.
+    fs.mkdirSync(codexHome, { recursive: true });
+    fs.chmodSync(codexHome, 0o500);
+    try {
+      const res = materializeCodexAgents({ hqRoot, codexHome });
+      expect(res.written).toBe(false);
+      expect(res.skippedReason).toBe("error");
+      const leftovers = fs
+        .readdirSync(codexHome)
+        .filter((f) => f.endsWith(".hq-tmp"));
+      expect(leftovers).toEqual([]);
+    } finally {
+      fs.chmodSync(codexHome, 0o700); // restore so afterEach cleanup works
+    }
+  });
+
+  it("writes the file with owner-only perms (0o600)", () => {
+    fs.writeFileSync(path.join(capDir(), AGENT_CONTRACT_FILE), "CONTRACT body");
+    materializeCodexAgents({ hqRoot, codexHome });
+    const mode = fs.statSync(path.join(codexHome, "AGENTS.md")).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it("emits a distinct event when the overlay is empty but a prior file exists", () => {
+    fs.mkdirSync(codexHome, { recursive: true });
+    fs.writeFileSync(path.join(codexHome, "AGENTS.md"), "PRIOR\n");
+    const events: string[] = [];
+    const res = materializeCodexAgents({
+      hqRoot, // capDir empty, no profile → empty overlay
+      codexHome,
+      log: (e) => events.push(e.event),
+    });
+    expect(res.skippedReason).toBe("empty-overlay");
+    expect(events).toContain(
+      "runner.agent_codex_instructions.skipped_empty_target_exists",
+    );
+    // Prior file left intact.
+    expect(fs.readFileSync(path.join(codexHome, "AGENTS.md"), "utf8")).toBe(
+      "PRIOR\n",
+    );
+  });
+});
+
+describe("codexHomeDir (CODEX_HOME validation)", () => {
+  const orig = process.env.CODEX_HOME;
+  afterEach(() => {
+    if (orig === undefined) delete process.env.CODEX_HOME;
+    else process.env.CODEX_HOME = orig;
+  });
+
+  it("defaults to ~/.codex when CODEX_HOME is unset", () => {
+    delete process.env.CODEX_HOME;
+    expect(codexHomeDir()).toBe(path.join(os.homedir(), ".codex"));
+  });
+
+  it("honors an absolute CODEX_HOME with no traversal", () => {
+    process.env.CODEX_HOME = "/var/lib/agent-codex";
+    expect(codexHomeDir()).toBe("/var/lib/agent-codex");
+  });
+
+  it("rejects a relative CODEX_HOME (falls back to ~/.codex)", () => {
+    process.env.CODEX_HOME = "relative/codex";
+    expect(codexHomeDir()).toBe(path.join(os.homedir(), ".codex"));
+  });
+
+  it("rejects a traversing CODEX_HOME (falls back to ~/.codex)", () => {
+    process.env.CODEX_HOME = "/tmp/../../etc";
+    expect(codexHomeDir()).toBe(path.join(os.homedir(), ".codex"));
+  });
+});

package/src/agent-codex-instructions.ts

@@ -0,0 +1,309 @@
+/**
+ * Agent codex-instructions materialization.
+ *
+ * Projects the synced HQ agent overlay into `~/.codex/AGENTS.md` — the codex
+ * GLOBAL instruction file, which `codex exec` natively merges on every run
+ * (alongside the project `AGENTS.md`, which on an HQ box symlinks to the
+ * `.claude/CLAUDE.md` charter). This is the codex mirror of how Claude reads
+ * `~/.claude/CLAUDE.md`: it carries the agent OPERATING CONTRACT (build your
+ * own tools, resolve credentials via group grants, follow team policy, the
+ * safety boundary) on top of the generic HQ charter.
+ *
+ * Why here (the sync runner), and why this file:
+ *   - DURABLE: `~/.codex/AGENTS.md` lives OUTSIDE the hq-root, so `hq rescue`
+ *     (`--hq-root`) and core upgrades never touch it. (In-tree `AGENTS.md` is
+ *     classified regenerable and silently overwritten by rescue.)
+ *   - SCALABLE: every agent box runs `@indigoai-us/hq-cloud@latest`
+ *     `hq-sync-runner` each cycle, so shipping the projection here reaches the
+ *     whole fleet — new and existing agents — with no reprovision or SSM push.
+ *   - AGENT-ONLY: the caller gates on `custom:entityType === "agent"`, so a
+ *     human running `hq sync` never materializes this file.
+ *
+ * Trust + isolation boundary (where it is actually enforced):
+ *   - Tenant isolation is enforced UPSTREAM at the sync boundary: an agent's
+ *     `--personal` sync resolves the agent's OWN vault (`pickAgentSelfEntity`,
+ *     server-authorized by the agent's machine JWT). This function trusts that
+ *     `hqRoot/personal/` was populated by that agent-scoped sync; it does not
+ *     re-fetch entity membership (the gate claim is the SAME one the runner
+ *     already trusts for `--personal` resolution; tampering it requires local
+ *     compromise of the 0o600 token cache, i.e. the box is already owned).
+ *   - DEFENCE-IN-DEPTH against a tampered local tree: every read is restricted
+ *     to REGULAR files (symlinks/dirs are skipped), so a planted symlink in the
+ *     overlay can't exfiltrate arbitrary files into `~/.codex/AGENTS.md`.
+ *   - The projection NEVER reads release-shipped `core/` content — the charter
+ *     reaches codex via the project `AGENTS.md` symlink, not this file.
+ *
+ * Deployment assumption: ONE agent identity per machine (the EC2 agent box
+ * model). `~/.codex/AGENTS.md` is a single, non-namespaced path; multiple agent
+ * identities sharing one OS home would last-write-wins. Not a concern in the
+ * one-agent-per-box fleet; revisit (per-agent namespacing) if that changes.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+/** hq-root-relative location of the (locally-written) agent identity briefing. */
+export const AGENTS_PROFILE_REL = "personal/agents-profile.md";
+
+/** hq-root-relative dir holding the synced agent-capability overlay docs. */
+export const AGENT_CAPABILITIES_REL =
+  "personal/knowledge/public/agent-capabilities";
+
+/** The capability doc carrying the operating contract — ordered first. */
+export const AGENT_CONTRACT_FILE = "hq-agent-contract.md";
+
+/** Leading marker so the file is self-describing and recognizable as generated. */
+export const CODEX_AGENTS_MARKER =
+  "<!-- hq-agent: generated by hq-sync-runner";
+
+export interface CodexSection {
+  /** hq-root-relative source path (for diagnostics; not written to the file). */
+  name: string;
+  content: string;
+}
+
+/**
+ * Pure: compose the codex global `AGENTS.md` body from ordered sections.
+ * Trims and drops empty/whitespace-only sections. Returns "" when nothing
+ * substantive remains, so the caller can SKIP the write (never emit an
+ * empty/marker-only file, never wipe a previously-materialized one).
+ *
+ * Deliberately carries NO timestamp: the output is a deterministic projection
+ * of its inputs, so a no-change sync rewrites byte-identical content (no churn;
+ * the write/skip/error events are timestamped in the diagnostic log instead).
+ */
+export function composeCodexAgentsMd(sections: CodexSection[]): string {
+  const body = sections
+    .map((s) => s.content.trim())
+    .filter((c) => c.length > 0)
+    .join("\n\n");
+  if (body.length === 0) return "";
+  const header =
+    `${CODEX_AGENTS_MARKER} from the synced HQ agent overlay. ` +
+    `Do not edit by hand — regenerated on every agent sync. ` +
+    `Source: ${AGENTS_PROFILE_REL} + ${AGENT_CAPABILITIES_REL}/*.md -->`;
+  return `${header}\n\n${body}\n`;
+}
+
+/**
+ * Pure: order capability filenames — the operating contract first, then the
+ * remaining `*.md` alphabetically. Non-markdown entries are dropped.
+ */
+export function orderCapabilityFiles(files: string[]): string[] {
+  const md = files.filter((f) => f.endsWith(".md")).sort();
+  const contractFirst = md.filter((f) => f === AGENT_CONTRACT_FILE);
+  const rest = md.filter((f) => f !== AGENT_CONTRACT_FILE);
+  return [...contractFirst, ...rest];
+}
+
+/** True iff `p` exists and is a REGULAR file (symlinks/dirs/etc. → false). */
+function isRegularFile(p: string): boolean {
+  try {
+    return fs.lstatSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read `p` only when it is a regular file (best-effort, never throws). lstat
+ * gates the read so a symlink is never followed — a planted symlink in the
+ * overlay cannot exfiltrate an out-of-tree file into the materialized output.
+ */
+function readRegularFileIfPresent(p: string): string | null {
+  if (!isRegularFile(p)) return null;
+  try {
+    const s = fs.readFileSync(p, "utf8");
+    return s.trim().length > 0 ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * IO: gather the agent overlay sections present under `hqRoot`. Order:
+ *   1. identity briefing (`personal/agents-profile.md`)
+ *   2. the operating contract (`agent-capabilities/hq-agent-contract.md`)
+ *   3. any other `agent-capabilities/*.md`, alphabetically
+ * Each is included only when it is a regular file and non-whitespace-only.
+ * Symlinks and directories are skipped (containment / no symlink-escape).
+ */
+export function gatherCodexAgentSections(hqRoot: string): CodexSection[] {
+  const sections: CodexSection[] = [];
+
+  const profile = readRegularFileIfPresent(path.join(hqRoot, AGENTS_PROFILE_REL));
+  if (profile) sections.push({ name: AGENTS_PROFILE_REL, content: profile });
+
+  const capDir = path.join(hqRoot, AGENT_CAPABILITIES_REL);
+  // Reject a symlinked capability DIR (only descend into a real directory).
+  let capDirIsRealDir = false;
+  try {
+    capDirIsRealDir = fs.lstatSync(capDir).isDirectory();
+  } catch {
+    capDirIsRealDir = false;
+  }
+  if (capDirIsRealDir) {
+    let entries: string[] = [];
+    try {
+      entries = fs.readdirSync(capDir);
+    } catch {
+      entries = [];
+    }
+    for (const f of orderCapabilityFiles(entries)) {
+      const content = readRegularFileIfPresent(path.join(capDir, f));
+      if (content) {
+        sections.push({ name: `${AGENT_CAPABILITIES_REL}/${f}`, content });
+      }
+    }
+  }
+  return sections;
+}
+
+export interface MaterializeLog {
+  (e: {
+    event: string;
+    message: string;
+    err?: unknown;
+    context?: Record<string, unknown>;
+  }): void;
+}
+
+export interface MaterializeResult {
+  written: boolean;
+  path: string;
+  sectionCount: number;
+  skippedReason?: "empty-overlay" | "target-not-regular-file" | "error";
+}
+
+/**
+ * Resolve the codex home dir. Honors `CODEX_HOME` only when it is an ABSOLUTE
+ * path with no `..` traversal; otherwise falls back to `~/.codex` (an injected
+ * relative/traversing value must not redirect the write off-target).
+ */
+export function codexHomeDir(): string {
+  const env = process.env.CODEX_HOME?.trim();
+  if (env && path.isAbsolute(env) && !env.split(path.sep).includes("..")) {
+    return env;
+  }
+  return path.join(os.homedir(), ".codex");
+}
+
+/**
+ * Best-effort: project the synced agent overlay into `~/.codex/AGENTS.md`.
+ * Idempotent atomic rewrite (write entropy-named temp + rename). NEVER throws —
+ * logs and returns a result.
+ *
+ * Non-destructive guarantees:
+ *   - SKIPS (no write, no delete) when the overlay yields no content, so a
+ *     transient empty/unsynced tree can never wipe a previously-materialized
+ *     file. (Emits a distinct event when a prior file exists — a possible
+ *     provisioning regression worth an operator's eye.)
+ *   - SKIPS when the target already exists but is NOT a regular file (a symlink
+ *     or directory), rather than silently clobbering an external config
+ *     relationship (or failing opaquely with EISDIR).
+ *   - On any write/rename failure, the entropy-named temp file is cleaned up so
+ *     repeated failures can't accumulate `*.hq-tmp` orphans.
+ *
+ * First boot: before the first `--personal` sync lands, the overlay is absent
+ * and this skips — the agent operates on the project `AGENTS.md` (charter)
+ * alone until the first sync materializes the contract (~one cycle).
+ */
+export function materializeCodexAgents(opts: {
+  hqRoot: string;
+  codexHome?: string;
+  log?: MaterializeLog;
+}): MaterializeResult {
+  const codexHome = opts.codexHome ?? codexHomeDir();
+  const target = path.join(codexHome, "AGENTS.md");
+  const log = opts.log ?? (() => {});
+  try {
+    const sections = gatherCodexAgentSections(opts.hqRoot);
+    const body = composeCodexAgentsMd(sections);
+
+    if (body.length === 0) {
+      const targetExists = (() => {
+        try {
+          fs.lstatSync(target);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      log({
+        // A pre-existing target + now-empty overlay is a likely regression
+        // (broken provisioning / seed), distinct from a clean first-boot skip.
+        event: targetExists
+          ? "runner.agent_codex_instructions.skipped_empty_target_exists"
+          : "runner.agent_codex_instructions.skipped",
+        message:
+          "no agent overlay content found; leaving ~/.codex/AGENTS.md untouched",
+        context: { target, targetExists },
+      });
+      return {
+        written: false,
+        path: target,
+        sectionCount: 0,
+        skippedReason: "empty-overlay",
+      };
+    }
+
+    // Refuse to clobber a non-regular target (symlink / directory): preserve an
+    // external config relationship + surface EISDIR-class problems distinctly.
+    let targetStat: fs.Stats | null = null;
+    try {
+      targetStat = fs.lstatSync(target);
+    } catch {
+      targetStat = null; // absent — fine, we create it
+    }
+    if (targetStat && !targetStat.isFile()) {
+      log({
+        event: "runner.agent_codex_instructions.config_error",
+        message:
+          "~/.codex/AGENTS.md exists but is not a regular file (symlink or directory); refusing to overwrite",
+        context: {
+          target,
+          isSymbolicLink: targetStat.isSymbolicLink(),
+          isDirectory: targetStat.isDirectory(),
+        },
+      });
+      return {
+        written: false,
+        path: target,
+        sectionCount: sections.length,
+        skippedReason: "target-not-regular-file",
+      };
+    }
+
+    fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+    const tmp = `${target}.${process.pid}.${crypto
+      .randomBytes(6)
+      .toString("hex")}.hq-tmp`;
+    try {
+      fs.writeFileSync(tmp, body, { mode: 0o600 });
+      fs.renameSync(tmp, target);
+    } catch (writeErr) {
+      // Clean up the orphaned temp so repeated failures don't accumulate.
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        /* best-effort */
+      }
+      throw writeErr;
+    }
+    log({
+      event: "runner.agent_codex_instructions.written",
+      message: `materialized codex global AGENTS.md from ${sections.length} overlay section(s)`,
+      context: { target, sectionCount: sections.length },
+    });
+    return { written: true, path: target, sectionCount: sections.length };
+  } catch (err) {
+    log({
+      event: "runner.agent_codex_instructions.error",
+      message: "failed to materialize codex global AGENTS.md",
+      err,
+      context: { target },
+    });
+    return { written: false, path: target, sectionCount: 0, skippedReason: "error" };
+  }
+}