@aitne/daemon 0.1.0

package/dist/core/skills-compiler.js

@@ -0,0 +1,1271 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { APP_NAME, BACKEND_IDS, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, applyIntegrationModeFilter, collectSessionDeniedTools, filterDeniedToolsForBackend, selectSkillVariantFile, selectTaskFlowVariantSuffix, substituteBrandTokens, } from "@aitne/shared";
+import { getProfileForEvent, getProfileForProcess, getSkillsForEvent, getSkillsForProcess } from "./skills-manifest.js";
+import { applyCharacterBlockRewrite, buildCharacterBlock } from "./character-block.js";
+import { createLogger } from "../logging.js";
+import { loadCurationDeclaration, } from "./skill-curation/declarations.js";
+import { OverlayStore } from "./skill-curation/overlay-store.js";
+import { hasCurationAnchors, spliceCurationAnchors, } from "./skill-curation/splicer.js";
+// Exported so tests can spy on `logger.warn` (e.g. the missing-reference
+// branch of `renderReferenceIncludes`). Production callers do not import it.
+export const logger = createLogger("skills-compiler");
+/**
+ * Check whether the skill AND task-flow variants a given integration would
+ * require when delegated to `delegatedBackend` are all present on disk.
+ * Returns missing file paths split by kind.
+ *
+ * DELEGATED-MODE-V2-DESIGN.md §4.1.1 — variant filenames are keyed on
+ * **session backend**, not the delegated backend. Three resolutions:
+ *  - sessionBackend === delegatedBackend → `null` (no skill body, native MCP)
+ *  - sessionBackend !== delegatedBackend → `SKILL.delegated.<sessionBackend>.md`
+ *    (cross-backend; the daemon proxy spawns delegatedBackend)
+ *  - non-delegated touch → `SKILL.md` (no delegated variant required)
+ *
+ * Task flow variants always fire as `delegated.<sessionBackend>` whenever
+ * any touched integration is delegated, regardless of same- vs cross-backend
+ * (`selectTaskFlowVariantSuffix`).
+ *
+ * The gate enumerates every potential session backend (`BACKEND_IDS`) and
+ * defers to the resolvers; that keeps the gate automatically aligned with
+ * `selectSkillVariantFile` / `selectTaskFlowVariantSuffix` if those grow new
+ * cases. We pin the integration's mode locally as `delegated` with the
+ * supplied `delegatedBackend` so the resolvers see the post-PATCH state.
+ *
+ * Consumed by:
+ *  - `SkillsCompiler.validateDelegatedVariants()` — startup aggregate
+ *  - `PATCH /api/integrations/:key` — pre-commit hard reject (§4.7)
+ *  - `buildIntegrationHealthMap` — surfaces the list in
+ *    `/health.integrationModes.<key>.variantsMissing`
+ */
+/**
+ * Walk a materialized session subdirectory and rewrite every `.md` file with
+ * `{APP_NAME}` tokens resolved. Called immediately after `cpSync(src, dest, …)`
+ * so the verbatim copy from `agent-assets/` becomes brand-substituted before
+ * any downstream transform (renderReferenceIncludes, applyIntegrationModeFilter,
+ * tool-deny filter) reads it. Idempotent — running it twice is a no-op.
+ */
+function substituteBrandTokensInDir(dir) {
+    if (!existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            substituteBrandTokensInDir(full);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            const original = readFileSync(full, "utf-8");
+            const substituted = substituteBrandTokens(original);
+            if (substituted !== original) {
+                writeFileSync(full, substituted, "utf-8");
+            }
+        }
+    }
+}
+export function missingDelegatedVariants(workspaceDir, integrationKey, delegatedBackend) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const skillsRoot = join(workspaceDir, "agent-assets", "skills");
+    const taskFlowsRoot = join(workspaceDir, "agent-assets", "task-flows");
+    // Synthetic post-PATCH state. The resolvers consume only `mode` and
+    // `delegatedBackend`; `lastChangedAt` is required by the type but not
+    // read here.
+    const integrationsState = {
+        [integrationKey]: {
+            mode: "delegated",
+            delegatedBackend,
+            deniedTools: [],
+            lastChangedAt: "1970-01-01T00:00:00.000Z",
+        },
+    };
+    // De-dup with sets — the same file path can come up under multiple
+    // session backends when descriptors share a slug, even though the
+    // current registry doesn't produce that today.
+    const skills = new Set();
+    for (const slug of descriptor.skillsTouched) {
+        for (const sessionBackend of BACKEND_IDS) {
+            const variantFile = selectSkillVariantFile(slug, sessionBackend, integrationsState);
+            // null  → same-backend, no body materialized; no file required.
+            // SKILL.md → resolver fell back to direct/disabled; no delegated file.
+            if (variantFile === null || variantFile === "SKILL.md")
+                continue;
+            const variantPath = join(skillsRoot, slug, variantFile);
+            if (!existsSync(variantPath))
+                skills.add(variantPath);
+        }
+    }
+    const taskFlows = new Set();
+    for (const flowKey of descriptor.taskFlowsTouched) {
+        for (const sessionBackend of BACKEND_IDS) {
+            const suffix = selectTaskFlowVariantSuffix(flowKey, sessionBackend, integrationsState);
+            if (suffix === "direct")
+                continue;
+            const variantPath = join(taskFlowsRoot, `${flowKey}.${suffix}.md`);
+            if (!existsSync(variantPath))
+                taskFlows.add(variantPath);
+        }
+    }
+    return { skills: [...skills], taskFlows: [...taskFlows] };
+}
+/**
+ * Materializes backend-specific instruction files for session workdirs
+ * by reading directly from the source tree (agent-assets/agent-profiles/ and
+ * agent-assets/skills/). User-authored skills are managed separately via workdir.ts.
+ *
+ * Previous versions maintained a "deploy" layer at {dataDir}/prompts/{backendId}/
+ * that was an exact copy of source. That layer was removed in favour of reading
+ * source directly — every session now always gets the latest files.
+ */
+export class SkillsCompiler {
+    workspaceDir;
+    configuredServices;
+    mailAccounts;
+    integrations;
+    character;
+    constructor(workspaceDir, 
+    /** Set of configured service names (e.g. 'calendar', 'obsidian', 'notion', 'github'). */
+    configuredServices = new Set(), 
+    /**
+     * Snapshot of active mail accounts (§Phase 5). When non-empty and the
+     * `mail` skill is part of the session, an `accounts.md` file is written
+     * into the session's mail skill dir so the agent can resolve labels →
+     * accountId without a round-trip to the daemon.
+     *
+     * Intentionally generated at session-materialization time (not into the
+     * checked-in `agent-assets/skills/mail/` source tree) so the repo stays
+     * git-clean. Deviation from the design-doc phrasing — see
+     * `docs/design/appendices/multi-mail-provider.md` §7.
+     */
+    mailAccounts = [], 
+    /**
+     * Current integration states (Phase 3). Used by `selectSkillVariantFile`
+     * to choose the right SKILL.*.md variant at session-materialization time.
+     * Defaults to empty (all integrations treated as non-delegated → SKILL.md).
+     */
+    integrations = {}, 
+    /**
+     * User-defined communication style / persona (design §15.4). When
+     * non-empty, a `## Character (user-defined)` block is rendered into
+     * every backend's instruction file (CLAUDE.md / AGENTS.md / GEMINI.md)
+     * between the safety preamble and the profile body. Defaults to the
+     * empty string, which omits the block.
+     */
+    character = "") {
+        this.workspaceDir = workspaceDir;
+        this.configuredServices = configuredServices;
+        this.mailAccounts = mailAccounts;
+        this.integrations = integrations;
+        this.character = character;
+    }
+    /**
+     * P22 — skill-curation overlay context. When set, the materializer runs an
+     * extra pass that resolves `<!-- CURATION:<kind> id="<id>" -->` anchors in
+     * each skill's SKILL.md against `<dataDir>/skills/overlays/<slug>/<id>.json`
+     * (overlay) or `agent-assets/skills/<slug>/seeds/<id>.seed.json` (seed).
+     *
+     * Optional and default-OFF — daemon code is expected to call
+     * `setSkillCurationContext({ dataDir })` at startup. Test workspaces and
+     * lint passes that don't need overlays leave it unset, which short-circuits
+     * the pass and is safe (anchors already render to nothing if there's no
+     * overlay AND no seed; a missing context_dir simply skips the pass).
+     */
+    skillCurationDataDir = null;
+    skillCurationCacheInvalidated = new Set();
+    setSkillCurationContext(opts) {
+        this.skillCurationDataDir = opts.dataDir;
+    }
+    /** Called by the apply / revert flow so future session materializations
+     *  re-render the affected skill's anchors. The cache itself is per-session
+     *  (we always read overlays from disk fresh inside the materializer) — this
+     *  flag exists so an in-process consumer can react to writes. */
+    invalidateSkillCurationCache(skillSlug) {
+        this.skillCurationCacheInvalidated.add(skillSlug);
+    }
+    /**
+     * Validate that all skill AND task-flow variants required by
+     * currently-delegated integrations exist on disk. Called at daemon
+     * startup after integration state is loaded; returns missing variant
+     * paths grouped by kind (empty arrays = everything present).
+     *
+     * §4.7 "Missing-variant policy": if any paths come back, the caller
+     * should refuse to enter delegated mode or at least log a loud warning.
+     * The per-integration variant for the hypothetical PATCH path lives in
+     * the standalone `missingDelegatedVariants` helper below; this method
+     * aggregates across every currently-delegated integration using its
+     * declared `delegatedBackend` (not the session backend — see the helper
+     * docstring for the rationale).
+     */
+    validateDelegatedVariants() {
+        const skills = [];
+        const taskFlows = [];
+        for (const key of INTEGRATION_KEYS) {
+            const state = this.integrations[key];
+            if (state?.mode !== "delegated" || !state.delegatedBackend)
+                continue;
+            const result = missingDelegatedVariants(this.workspaceDir, key, state.delegatedBackend);
+            skills.push(...result.skills);
+            taskFlows.push(...result.taskFlows);
+        }
+        return { skills, taskFlows };
+    }
+    /**
+     * Resolve the effective SKILL.md filename for a skill + session backend pair.
+     *
+     *   - `"SKILL.md"`                     — direct/default body
+     *   - `"SKILL.delegated.<backend>.md"` — cross-backend variant (only if it
+     *                                         exists on disk; falls back to
+     *                                         `"SKILL.md"` when missing)
+     *   - `null`                           — same-backend native MCP; do NOT
+     *                                         materialize the skill at all
+     *                                         (DELEGATED-MODE-V2-DESIGN.md §4.1.2).
+     */
+    resolveSkillVariantFile(skillSlug, backendId) {
+        const candidate = selectSkillVariantFile(skillSlug, backendId, this.integrations);
+        if (candidate === null)
+            return null;
+        if (candidate === "SKILL.md")
+            return "SKILL.md";
+        const candidatePath = join(this.getSourceSkillsRoot(), skillSlug, candidate);
+        return existsSync(candidatePath) ? candidate : "SKILL.md";
+    }
+    getSourceSkillsRoot() {
+        return join(this.workspaceDir, "agent-assets", "skills");
+    }
+    getSourceProfilesRoot() {
+        return join(this.workspaceDir, "agent-assets", "agent-profiles");
+    }
+    getSourceTaskFlowsRoot() {
+        return join(this.workspaceDir, "agent-assets", "task-flows");
+    }
+    /** Read all source skill and profile files (for dashboard inspection). */
+    readSourceFiles() {
+        const files = [];
+        const profilesRoot = this.getSourceProfilesRoot();
+        const skillsRoot = this.getSourceSkillsRoot();
+        if (existsSync(profilesRoot)) {
+            for (const file of readTreeFiles(profilesRoot)) {
+                files.push({ ...file, path: join("agent-profiles", file.path) });
+            }
+        }
+        if (existsSync(skillsRoot)) {
+            for (const file of readTreeFiles(skillsRoot)) {
+                files.push({ ...file, path: join("skills", file.path) });
+            }
+        }
+        return files;
+    }
+    materializeSessionBundle(params) {
+        const profileName = params.processKey
+            ? getProfileForProcess(params.processKey)
+            : getProfileForEvent(params.eventType);
+        const manifestSkills = params.processKey
+            ? getSkillsForProcess(params.processKey)
+            : getSkillsForEvent(params.eventType);
+        // Custom bang command override: when the dispatcher passes a slug array
+        // we use it verbatim, ignoring the manifest. Empty array is allowed and
+        // means "no skills." `null` keeps manifest behavior — the override is a
+        // partial replacement so a future caller can pass just `profileBody`
+        // without affecting skill selection.
+        const skills = params.override?.skillSlugs !== null
+            && params.override?.skillSlugs !== undefined
+            ? [...params.override.skillSlugs]
+            : manifestSkills;
+        const profileBodyOverride = params.override?.profileBody ?? null;
+        // Always materialize the `mail` skill when the manifest asks for it —
+        // even if the current account list is empty. The skill is inert when
+        // `accounts.md` is empty (it carries an explicit "no accounts
+        // configured" marker), and materializing unconditionally gives
+        // `refreshSessionMailAccountsMd` a skill dir to target when the user
+        // adds their first account mid-session (0→N transition). Filtering
+        // here would leave the skill dir absent forever since refresh only
+        // writes into existing dirs.
+        if (params.backendId === "claude") {
+            this.materializeClaudeSession(params.sessionDir, profileName, skills, profileBodyOverride);
+        }
+        else {
+            this.materializeCliSession(params.sessionDir, profileName, skills, params.backendId, params.processKey ?? params.eventType, profileBodyOverride);
+        }
+        return { profile: profileName, skills };
+    }
+    /** Read raw profile .md without safety injection. */
+    readProfile(profileName) {
+        const profilePath = join(this.getSourceProfilesRoot(), `${profileName}.md`);
+        if (!existsSync(profilePath))
+            return null;
+        return substituteBrandTokens(readFileSync(profilePath, "utf-8"));
+    }
+    /**
+     * Read the shared safety preamble (_safety.md) and append the
+     * `<!-- safety:end -->` sentinel so downstream helpers (notably
+     * `insertCharacterBlock` in `character-block.ts`) can place the
+     * Character block directly below safety rather than above whichever
+     * `## ` heading the preamble opens with. See design §15.4.2 / §15.5.
+     */
+    readSafetyPreamble() {
+        const safetyPath = join(this.getSourceProfilesRoot(), "_safety.md");
+        if (!existsSync(safetyPath))
+            return null;
+        const content = substituteBrandTokens(readFileSync(safetyPath, "utf-8")).trim();
+        if (!content)
+            return null;
+        return `${content}\n\n<!-- safety:end -->`;
+    }
+    /**
+     * Read a profile .md and prepend the shared safety preamble (_safety.md).
+     * Used for Claude SDK sessions where skills are separate files.
+     * Returns null if the profile file doesn't exist.
+     *
+     * The safety preamble is emitted with a trailing `<!-- safety:end -->`
+     * sentinel so the Character-block rewriter can insert below safety even
+     * when the preamble itself starts with `## Safety Invariants` (design
+     * §15.4.2 / §15.5).
+     */
+    readProfileWithSafety(profileName) {
+        const profilePath = join(this.getSourceProfilesRoot(), `${profileName}.md`);
+        if (!existsSync(profilePath))
+            return null;
+        const profile = substituteBrandTokens(readFileSync(profilePath, "utf-8"));
+        const safety = this.readSafetyPreamble();
+        if (!safety)
+            return profile;
+        // Inject safety preamble after the first heading line
+        const lines = profile.split("\n");
+        const headingIdx = lines.findIndex((l) => l.startsWith("# "));
+        if (headingIdx >= 0) {
+            // Insert after heading + its following blank line (if any)
+            let insertIdx = headingIdx + 1;
+            while (insertIdx < lines.length && lines[insertIdx].trim() === "")
+                insertIdx++;
+            // Insert before the first non-blank content after heading
+            const descriptionEnd = lines.findIndex((l, i) => i > headingIdx && l.startsWith("## "));
+            const insertAt = descriptionEnd >= 0 ? descriptionEnd : insertIdx;
+            lines.splice(insertAt, 0, safety, "");
+            return lines.join("\n");
+        }
+        // No heading found — prepend
+        return `${safety}\n\n${profile}`;
+    }
+    /**
+     * Compose a synthesized profile document from a user-supplied body — used
+     * by custom bang commands whose `instruction_md` replaces the
+     * conversational profile. Wraps the body in a top-level heading so the
+     * downstream `applyCharacterBlockRewrite` insertion logic finds the
+     * `# ` anchor it expects, then prepends the safety preamble using the
+     * same shape as `readProfileWithSafety` so safety always lands above
+     * Character + body. Empty body inputs are caller-responsibility — the
+     * storage layer normalises whitespace-only strings to null.
+     */
+    composeClaudeProfileFromBody(body) {
+        const safety = this.readSafetyPreamble();
+        const heading = "# Custom command instructions";
+        const trimmedBody = body.trim();
+        if (!safety) {
+            return `${heading}\n\n${trimmedBody}\n`;
+        }
+        return `${heading}\n\n${safety}\n\n${trimmedBody}\n`;
+    }
+    materializeClaudeSession(sessionDir, profileName, skillSlugs, profileBodyOverride) {
+        let profileContent = profileBodyOverride !== null
+            ? this.composeClaudeProfileFromBody(profileBodyOverride)
+            : this.readProfileWithSafety(profileName);
+        if (profileContent) {
+            // Insert the user-defined character block between the safety
+            // preamble and the first profile `## ` section (design §15.4.2).
+            // `applyCharacterBlockRewrite` is idempotent — the input here is
+            // a fresh render with no existing block, so this is always the
+            // "insert" branch.
+            profileContent = applyCharacterBlockRewrite(profileContent, this.character);
+            profileContent += "\n\n" + renderDaemonApiUsageSection(true);
+            mkdirSync(dirname(join(sessionDir, "CLAUDE.md")), { recursive: true });
+            writeFileSync(join(sessionDir, "CLAUDE.md"), profileContent, "utf-8");
+        }
+        const skillsRoot = this.getSourceSkillsRoot();
+        const destSkillsRoot = join(sessionDir, ".claude", "skills");
+        mkdirSync(destSkillsRoot, { recursive: true });
+        // Re-materialize cleanup: a previous turn (especially one with a wider
+        // skill set or a different custom-command override) may have left
+        // built-in skill dirs that aren't in the current `skillSlugs`. Remove
+        // them so the next turn's tool inventory matches expectations.
+        // User-authored skills live alongside built-ins in the same dir but
+        // are recognised by absence-from-source — those we never touch here;
+        // `syncAllUserSkills` is the authoritative writer for that subset.
+        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, skillSlugs);
+        for (const skillSlug of skillSlugs) {
+            const src = join(skillsRoot, skillSlug);
+            if (!existsSync(join(src, "SKILL.md"))) {
+                continue;
+            }
+            const variantFile = this.resolveSkillVariantFile(skillSlug, "claude");
+            const destDir = join(destSkillsRoot, skillSlug);
+            // DELEGATED-MODE-V2-DESIGN.md §4.1.2 — same-backend native MCP. The
+            // agent already has the connector's tools in its inventory; a skill
+            // body would mis-direct it at the daemon proxy (which 409s in this
+            // case). Remove any prior-materialization leftovers from disk so a
+            // mode flip (direct ↔ delegated.same-backend) doesn't leave stale
+            // prose in the workdir.
+            if (variantFile === null) {
+                if (existsSync(destDir)) {
+                    rmSync(destDir, { recursive: true, force: true });
+                }
+                continue;
+            }
+            cpSync(src, destDir, { recursive: true });
+            // Resolve `{APP_NAME}` brand tokens in the verbatim copy before any
+            // downstream transform reads them. Source-of-truth: branding.ts.
+            substituteBrandTokensInDir(destDir);
+            if (variantFile !== "SKILL.md") {
+                // Render variant (resolving {{> base }} partials) and overwrite SKILL.md.
+                // Wrap the inliner output: renderPartialIncludes reads from src verbatim,
+                // so an `{APP_NAME}` token in SKILL.base.md would slip through if we only
+                // substituted `raw`. Idempotent — re-running on already-substituted text
+                // is a no-op.
+                const raw = substituteBrandTokens(readFileSync(join(src, variantFile), "utf-8"));
+                const rendered = substituteBrandTokens(renderPartialIncludes(raw, join(src, "SKILL.base.md")));
+                writeFileSync(join(destDir, "SKILL.md"), rendered, "utf-8");
+            }
+            // Resolve `{{> ref:<name> }}` directives by inlining
+            // `references/<name>.md` from the SOURCE skill dir. Read from src so
+            // the references content is canonical (the directory copy under
+            // `destDir/references/` is identical, but reading from src makes the
+            // dependency direction explicit and matches the CLI path).
+            //
+            // Order: refs BEFORE strip-services. The CLI paths
+            // (`materializeCliSession` inline + directory copy) both run refs
+            // before strip; aligning Claude here preserves the byte-equivalence
+            // contract (plan §3.1) for the case where a reference file carries
+            // `<!-- service:* -->` markers — strip-first would leak those on
+            // Claude while CLI scrubs them.
+            const destSkillMdForRefs = join(destDir, "SKILL.md");
+            if (existsSync(destSkillMdForRefs)) {
+                const raw = readFileSync(destSkillMdForRefs, "utf-8");
+                // renderReferenceIncludes inlines `references/*.md` directly from src,
+                // bypassing the post-cpSync substitution walk. Wrap the result so a
+                // future `{APP_NAME}` token added to a reference file resolves cleanly.
+                const expanded = substituteBrandTokens(renderReferenceIncludes(raw, src));
+                if (expanded !== raw) {
+                    writeFileSync(destSkillMdForRefs, expanded, "utf-8");
+                }
+            }
+            // Strip unconfigured service sections from external-services
+            if (skillSlug === "external-services" && this.configuredServices.size > 0) {
+                const destSkillMd = join(destDir, "SKILL.md");
+                const raw = readFileSync(destSkillMd, "utf-8");
+                const stripped = stripUnconfiguredServices(raw, this.configuredServices);
+                if (stripped !== raw) {
+                    writeFileSync(destSkillMd, stripped, "utf-8");
+                }
+            }
+            // Mode-conditional sections (`<!-- mode:<predicate>:<key> -->`)
+            // collapse to the right branch for the current integration state.
+            // Runs AFTER service-strip so unrelated service sections that carry
+            // mode markers still see them. Runs BEFORE the deny pass so any
+            // `allowed-tools` entry inside a struck branch gets removed before
+            // deny-list filtering inspects the frontmatter.
+            const destSkillMdForMode = join(destDir, "SKILL.md");
+            if (existsSync(destSkillMdForMode)) {
+                const raw = readFileSync(destSkillMdForMode, "utf-8");
+                const filtered = applyIntegrationModeFilter(raw, this.integrations, "claude");
+                if (filtered !== raw) {
+                    writeFileSync(destSkillMdForMode, filtered, "utf-8");
+                }
+            }
+            // §7.7 — apply tool-deny policy AFTER partial includes and
+            // service-section stripping. For Claude this rewrites the
+            // `allowed-tools` frontmatter; the SDK enforces hard.
+            const destSkillMdForDeny = join(destDir, "SKILL.md");
+            if (existsSync(destSkillMdForDeny)) {
+                const raw = readFileSync(destSkillMdForDeny, "utf-8");
+                const filtered = applyAllDeniedToolsForSkill(raw, skillSlug, "claude", this.integrations);
+                if (filtered !== raw) {
+                    writeFileSync(destSkillMdForDeny, filtered, "utf-8");
+                }
+            }
+            // P22 — skill-curation anchor splicer pass. Runs LAST so anchors
+            // resolve over the fully transformed body (mode-conditional + deny
+            // already applied). No-op when no curation context is configured or
+            // when the skill ships no curation.json.
+            this.spliceCurationAnchorsInSkill(destDir, skillSlug);
+            if (skillSlug === "mail") {
+                // Always write accounts.md — the empty marker (rendered when the
+                // list is empty) tells the agent not to guess ids, and having the
+                // file unconditionally keeps the refresh hook's existsSync checks
+                // truthful on both 0→N and N→0 transitions.
+                writeFileSync(join(destDir, "accounts.md"), this.mailAccounts.length > 0
+                    ? renderMailAccountsMd(this.mailAccounts)
+                    : EMPTY_MAIL_ACCOUNTS_MD, "utf-8");
+            }
+        }
+    }
+    /**
+     * P22 §1.5 — splice CURATION anchors in a single skill's materialized
+     * SKILL.md against overlay/seed JSON. Pure file I/O — overlay store
+     * dictates payload precedence (overlay > seed > strip-line). No-op when
+     * no curation context is configured or when the skill has no anchors.
+     */
+    spliceCurationAnchorsInSkill(destDir, skillSlug) {
+        if (!this.skillCurationDataDir)
+            return;
+        const skillMdPath = join(destDir, "SKILL.md");
+        if (!existsSync(skillMdPath))
+            return;
+        const md = readFileSync(skillMdPath, "utf-8");
+        if (!hasCurationAnchors(md))
+            return;
+        let decl;
+        try {
+            decl = loadCurationDeclaration(this.getSourceSkillsRoot(), skillSlug);
+        }
+        catch (err) {
+            logger.warn({ skillSlug, err: err instanceof Error ? err.message : String(err) }, "skill_curation.declaration.invalid");
+            return;
+        }
+        const overlay = new OverlayStore(this.skillCurationDataDir, this.getSourceSkillsRoot());
+        const knownIds = decl ? new Set(decl.sections.map((s) => s.id)) : undefined;
+        const result = spliceCurationAnchors(md, (sectionId, kind) => overlay.readPayload(skillSlug, sectionId, kind), { knownSectionIds: knownIds });
+        if (result.warnings.length > 0) {
+            for (const w of result.warnings) {
+                logger.warn({ skillSlug, anchorId: w.anchorId, code: w.code, message: w.message }, w.code);
+            }
+        }
+        if (result.body !== md) {
+            writeFileSync(skillMdPath, result.body, "utf-8");
+        }
+    }
+    materializeCliSession(sessionDir, profileName, skillSlugs, backendId, processKey, profileBodyOverride) {
+        // Skills are inlined in the instruction file (AGENTS.md / GEMINI.md) for
+        // guaranteed availability AND copied to the backend-specific skill
+        // directory for native CLI skill discovery. The directory copy only adds
+        // ~20 tokens per skill at session start (name + description); full body
+        // is lazy-loaded on activation. Belt-and-suspenders: inline ensures task
+        // flow prompts always have API references in context; directories let the
+        // CLI's native skill activation and tooling work.
+        const skillsRoot = this.getSourceSkillsRoot();
+        const skillContents = {};
+        for (const skillSlug of skillSlugs) {
+            const src = join(skillsRoot, skillSlug);
+            const variantFile = this.resolveSkillVariantFile(skillSlug, backendId);
+            // DELEGATED-MODE-V2-DESIGN.md §4.1.2 — same-backend native MCP path:
+            // skip the inline. The connector's own tool descriptions, present in
+            // the CLI's tool inventory at session-init, are the authoritative
+            // surface for the agent.
+            if (variantFile === null)
+                continue;
+            const skillMdPath = join(src, variantFile);
+            if (!existsSync(skillMdPath)) {
+                continue;
+            }
+            let raw = substituteBrandTokens(readFileSync(skillMdPath, "utf-8"));
+            // Resolve {{> base }} partials before inlining. Wrap the result —
+            // SKILL.base.md is read directly from src and would slip past the
+            // single-point-of-change contract if it grew an `{APP_NAME}` token.
+            raw = substituteBrandTokens(renderPartialIncludes(raw, join(src, "SKILL.base.md")));
+            // Resolve `{{> ref:<name> }}` directives by inlining
+            // `references/<name>.md` from the source skill dir. Runs AFTER the
+            // base-partial resolver so a base-partial fragment can itself carry
+            // `{{> ref:* }}` markers (one-level nesting cap; references inside
+            // references are intentionally NOT resolved per §4.7 / NG5). Same
+            // src-bypass concern as above — wrap the result.
+            raw = substituteBrandTokens(renderReferenceIncludes(raw, src));
+            // Strip unconfigured service sections before inlining
+            if (skillSlug === "external-services" && this.configuredServices.size > 0) {
+                raw = stripUnconfiguredServices(raw, this.configuredServices);
+            }
+            // Mode-conditional sections — see materializeClaudeSession for the
+            // ordering rationale. Same filter, same ordering: service-strip
+            // then mode-filter then deny.
+            raw = applyIntegrationModeFilter(raw, this.integrations, backendId);
+            // §7.7 — apply tool-deny policy. For CLI backends this appends the
+            // soft-enforcement prose block; the inline-into-AGENTS.md path
+            // strips frontmatter below, so the deny block must already be in
+            // body content before that strip.
+            raw = applyAllDeniedToolsForSkill(raw, skillSlug, backendId, this.integrations);
+            // Inline content for instruction file — strip frontmatter (Claude-specific
+            // YAML metadata like allowed-tools has no meaning for CLI backends).
+            skillContents[skillSlug] = stripFrontmatter(raw);
+        }
+        // Read profile and safety separately so renderCliInstructionFile can
+        // place safety at the top level for prominence (instead of burying it
+        // inside the profile section). For custom bang commands the dispatcher
+        // passes a `profileBodyOverride` that replaces the persona body; the
+        // safety + character + skills sections still wrap around it via
+        // `renderCliInstructionFile`.
+        const profileContent = profileBodyOverride !== null
+            ? profileBodyOverride.trim()
+            : (this.readProfile(profileName) ?? "");
+        const safetyContent = this.readSafetyPreamble();
+        const characterBlock = buildCharacterBlock(this.character);
+        // DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — same-backend deny prose.
+        // Codex's connector apps (`mcp__codex_apps__*`) are built into the CLI
+        // and have no admin-policy or per-tool deny surface (γ outcome). Prose
+        // injection into AGENTS.md is the only enforcement available. For
+        // Gemini, the admin-policy already hard-denies the same tools; the
+        // prose duplicates intent so the agent doesn't waste tokens drafting
+        // calls that will be denied at the policy layer.
+        const sameBackendDenyBlock = buildSameBackendDenyBlock(this.integrations, backendId);
+        const instruction = renderCliInstructionFile({
+            backendId,
+            processKey,
+            profileName,
+            profileContent,
+            safetyContent,
+            characterBlock,
+            skillSlugs,
+            skillContents,
+            sameBackendDenyBlock,
+        });
+        writeFileSync(join(sessionDir, backendId === "codex" ? "AGENTS.md" : "GEMINI.md"), instruction, "utf-8");
+        // Copy skills to the backend-specific skill directory for native CLI
+        // discovery:  .codex/skills/<slug>/  or  .gemini/skills/<slug>/
+        const cliSkillsDir = cliSkillsDirName(backendId);
+        const destSkillsRoot = join(sessionDir, cliSkillsDir, "skills");
+        mkdirSync(destSkillsRoot, { recursive: true });
+        // See `materializeClaudeSession` — same prune contract for CLI workdirs.
+        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, skillSlugs);
+        for (const skillSlug of skillSlugs) {
+            const src = join(skillsRoot, skillSlug);
+            const variantFile = this.resolveSkillVariantFile(skillSlug, backendId);
+            const destDir = join(destSkillsRoot, skillSlug);
+            // §4.1.2 same-backend short-circuit: no SKILL.md / .codex/skills/<slug>
+            // / .gemini/skills/<slug> directory written. The connector ships its
+            // own descriptions; injecting prose only confuses the dispatch.
+            // Remove any prior-materialization leftovers so a mode flip doesn't
+            // leak stale prose into the workdir.
+            if (variantFile === null) {
+                if (existsSync(destDir)) {
+                    rmSync(destDir, { recursive: true, force: true });
+                }
+                continue;
+            }
+            const variantPath = join(src, variantFile);
+            if (!existsSync(variantPath)) {
+                continue;
+            }
+            // Copy the whole skill directory (scripts/, references/, etc.)
+            cpSync(src, destDir, { recursive: true });
+            // Resolve `{APP_NAME}` brand tokens in the verbatim copy before any
+            // downstream transform reads them. Source-of-truth: branding.ts.
+            substituteBrandTokensInDir(destDir);
+            // Render variant (resolving partials), adapt frontmatter for CLI, and
+            // write as SKILL.md in the dest dir.
+            let adapted = substituteBrandTokens(readFileSync(variantPath, "utf-8"));
+            // SKILL.base.md and references/*.md are read directly from src by these
+            // inliners; wrap the results so future tokens added to those files still
+            // reach single-point-of-change. Idempotent.
+            adapted = substituteBrandTokens(renderPartialIncludes(adapted, join(src, "SKILL.base.md")));
+            // Resolve `{{> ref:<name> }}` directives — keeps the
+            // `.codex/skills/<slug>/SKILL.md` and `.gemini/skills/<slug>/SKILL.md`
+            // bodies byte-identical to the inline-into-AGENTS.md / GEMINI.md
+            // copy emitted above (modulo CLI frontmatter strip), preserving the
+            // "guaranteed availability" contract that motivated this resolver.
+            adapted = substituteBrandTokens(renderReferenceIncludes(adapted, src));
+            if (skillSlug === "external-services" && this.configuredServices.size > 0) {
+                adapted = stripUnconfiguredServices(adapted, this.configuredServices);
+            }
+            // Mode-conditional filter — keep this dest-dir copy byte-aligned with
+            // the inline copy emitted into AGENTS.md / GEMINI.md (modulo
+            // adaptSkillForCli's frontmatter strip). The filter is idempotent so
+            // running it on both copies independently is safe.
+            adapted = applyIntegrationModeFilter(adapted, this.integrations, backendId);
+            // §7.7 — apply tool-deny policy BEFORE adaptSkillForCli strips
+            // frontmatter so the soft-enforcement prose block lands in body
+            // content (CLI skills carry only `name` + `description` in
+            // frontmatter, no `allowed-tools` to filter).
+            adapted = applyAllDeniedToolsForSkill(adapted, skillSlug, backendId, this.integrations);
+            adapted = adaptSkillForCli(adapted);
+            writeFileSync(join(destDir, "SKILL.md"), adapted, "utf-8");
+            // P22 — splice CURATION anchors against overlay/seed JSON so the
+            // CLI-side .codex/.gemini skill copy stays byte-equivalent to the
+            // Claude-side copy after curation. No-op when no curation context.
+            this.spliceCurationAnchorsInSkill(destDir, skillSlug);
+            if (skillSlug === "mail") {
+                writeFileSync(join(destDir, "accounts.md"), this.mailAccounts.length > 0
+                    ? renderMailAccountsMd(this.mailAccounts)
+                    : EMPTY_MAIL_ACCOUNTS_MD, "utf-8");
+            }
+        }
+    }
+}
+export const EMPTY_MAIL_ACCOUNTS_MD = [
+    "# Mail accounts",
+    "",
+    "No active mail accounts are configured right now. The `mail` skill's API",
+    "calls will fail without an `accountId` — do NOT guess account ids. If no",
+    "account matches, tell the user no active mail account is configured and",
+    "stop — account setup is outside this skill's scope.",
+    "",
+].join("\n");
+export function renderMailAccountsMd(accounts) {
+    const rows = accounts.map((a) => {
+        const label = a.label ? ` (${a.label})` : "";
+        return `| \`${a.id}\` | ${a.kind} | ${a.email}${label} | ${a.idleEnabled ? "IDLE" : "poll"} |`;
+    });
+    return [
+        "# Mail accounts",
+        "",
+        "Active mail accounts this session can use. Resolve `accountId` from this",
+        "table before calling `/api/mail/:accountId/*`. Inactive / unhealthy",
+        "accounts are omitted by design — no global \"primary\" default exists;",
+        "pick the account from conversation context (reply thread, user mention,",
+        "or a single active row) and ask when ambiguous.",
+        "",
+        "| accountId | kind | email | transport |",
+        "|---|---|---|---|",
+        ...rows,
+        "",
+    ].join("\n");
+}
+/**
+ * Return the backend-specific skills directory name for a given backend.
+ * Returns null for Claude (which uses `.claude/skills/` managed separately).
+ */
+export function cliSkillsDirName(backendId) {
+    switch (backendId) {
+        case "codex": return ".codex";
+        case "gemini": return ".gemini";
+        default: return null;
+    }
+}
+/**
+ * Session instruction files the live-overwrite path (design §15.6.1 /
+ * §15.9) walks when the owner PATCHes `character` mid-session. Each file
+ * corresponds to a backend (CLAUDE.md = Claude Code SDK, AGENTS.md =
+ * Codex CLI, GEMINI.md = Gemini CLI). A workdir that has already seen a
+ * heavy-tier fallback can contain two of these side-by-side — see
+ * CLAUDE.md "Fallback re-materialization".
+ */
+const CHARACTER_INSTRUCTION_FILES = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+];
+/**
+ * Rewrite the `## Character (user-defined)` block inside every backend
+ * instruction file that currently lives in `workdir`. Used by the
+ * `PATCH /api/config` live-overwrite path (§15.6.1) so an owner editing
+ * character on the dashboard doesn't have to wait for the next session
+ * spawn for the change to land.
+ *
+ * Multi-backend aware: a workdir that has seen a Claude→Codex fallback
+ * contains both CLAUDE.md and AGENTS.md, and both must end up byte-
+ * identical in their character block. Each write is atomic (tmp +
+ * rename, both on the same filesystem so rename stays cheap) and
+ * per-file errors are logged without failing the whole call.
+ *
+ * Returns a summary of how many files were rewritten. Useful for
+ * instrumentation and for the dashboard PATCH handler to log.
+ *
+ * The helper is an FS wrapper: its pure parse/compose half lives in
+ * `character-block.ts` and is covered 100% there. This side is excluded
+ * from coverage along with the rest of `skills-compiler.ts`.
+ */
+export function rewriteCharacterBlock(workdir, character) {
+    const summary = { rewritten: 0, skipped: 0, failed: 0 };
+    for (const name of CHARACTER_INSTRUCTION_FILES) {
+        const target = join(workdir, name);
+        if (!existsSync(target)) {
+            summary.skipped++;
+            continue;
+        }
+        try {
+            const current = readFileSync(target, "utf-8");
+            const next = applyCharacterBlockRewrite(current, character);
+            if (next === current) {
+                summary.skipped++;
+                continue;
+            }
+            // `.tmp` lives next to the target so the rename stays on one
+            // filesystem (design R1 mitigation).
+            const tmp = `${target}.tmp`;
+            writeFileSync(tmp, next, "utf-8");
+            renameSync(tmp, target);
+            summary.rewritten++;
+        }
+        catch (err) {
+            // Per-file logging so a partial failure (e.g. CLAUDE.md written,
+            // AGENTS.md EACCES) is recoverable post-hoc — the outer PATCH
+            // handler only sees aggregate totals.
+            logger.warn({ err, target }, "rewriteCharacterBlock failed to update instruction file");
+            summary.failed++;
+        }
+    }
+    return summary;
+}
+function renderCliInstructionFile(params) {
+    const toolName = params.backendId === "codex" ? "AGENTS.md" : "GEMINI.md";
+    const parts = [
+        `# ${APP_NAME} ${toolName}`,
+        "",
+        `Process key: \`${params.processKey}\``,
+        `Profile: \`${params.profileName}\``,
+        "",
+    ];
+    // Safety invariants at top level for prominence — CLI backends don't
+    // have a separate project-instruction layer, so burying safety inside
+    // the profile section risks it being overlooked by weaker models.
+    if (params.safetyContent) {
+        parts.push(params.safetyContent, "");
+    }
+    // User-defined character sits immediately after safety so it strictly
+    // outranks every profile / skill / task-flow layer below it, and
+    // strictly below safety (design §15.4.2 / §15.5).
+    if (params.characterBlock) {
+        parts.push(params.characterBlock, "");
+    }
+    // DELEGATED-MODE-V2-DESIGN.md §4.3.4 — same-backend integration deny block.
+    // Sits right after character / safety (above behavioral rules + skills) so
+    // weak models cannot miss it. For Codex this is the only enforcement
+    // surface; for Gemini it duplicates the admin-policy hard-deny.
+    if (params.sameBackendDenyBlock) {
+        parts.push(params.sameBackendDenyBlock, "");
+    }
+    // Behavioral rules that Claude Code receives via system prompt append but
+    // CLI backends don't have a system prompt layer for.
+    parts.push("## Behavioral rules", "", "- WhatsApp outbound messages are prefixed by the daemon. Do not add that prefix yourself unless the user explicitly asks.", "");
+    // Daemon-API usage hoisted ABOVE the skills (was: appended at the end
+    // of the file). Skill bodies inline below carry hundreds of `curl
+    // http://localhost:8321/api/...` examples; for Codex specifically those
+    // examples target endpoints that return 401 because Codex does not
+    // hold the read-sensitive token. Surfacing the constraint up-front
+    // gives the agent the routing rule before it reads the first skill.
+    // For Gemini / Claude the section is informational; the position is
+    // kept consistent so the rendered file shape is uniform.
+    parts.push(renderDaemonApiUsageSection(params.backendId !== "codex"), "");
+    parts.push("## Runtime profile", "", params.profileContent.trim(), "", "## Skills", "");
+    if (params.skillSlugs.length === 0) {
+        parts.push("No process-scoped built-in skills were selected for this turn.");
+    }
+    else {
+        for (const slug of params.skillSlugs) {
+            const content = params.skillContents[slug];
+            if (content) {
+                parts.push(`### ${slug}`, "", content.trim(), "");
+            }
+            else {
+                parts.push(`### ${slug}`, "", `See \`skills/${slug}/SKILL.md\` for details.`, "");
+            }
+        }
+    }
+    parts.push("", "User-authored skills may also exist under `skills/<name>/SKILL.md`.");
+    return parts.join("\n");
+}
+function renderDaemonApiUsageSection(readSensitiveAvailable) {
+    const lines = [
+        "## Daemon API Usage",
+        "",
+        "- Use plain `curl` for daemon API calls. The daemon prepends a session-local wrapper on PATH.",
+        "- Never use absolute curl paths, alternative HTTP clients, connection overrides, or custom auth headers.",
+    ];
+    if (readSensitiveAvailable) {
+        lines.push("- The wrapper auto-attaches session auth for read-sensitive endpoints.");
+    }
+    else {
+        lines.push("", "### Read-sensitive endpoints are UNAVAILABLE on this backend", "", "Codex sessions do not receive the read-sensitive daemon token. The", "wrapper still prepends headers it can supply, but the daemon answers", "personal-data reads with `401 Unauthorized` regardless. Endpoints", "below are affected; the skill bodies in `## Skills` describe them", "as if they were available — treat the section as a contract you", "cannot satisfy on this backend.", "", "- Context vault: `GET /api/context/*`, `GET /api/context/list/*`", "- Mail (multi-provider): `GET /api/mail/*` (read), search, providers", "- Calendar (direct mode): `GET /api/calendar/*`", "- Notion (direct mode): `GET /api/notion/{query,search,pages}`", "- Obsidian: `GET /api/obsidian/*`", "- Observations: `GET /api/observations`", "- Reading list / receipts / travel bookings", "", "If a skill body directs you at one of these reads, stop and tell", "the user the task needs a different backend (Claude or Gemini).", "Do not hammer the endpoint — the 401 is permanent for this", "session, not transient. Writes and autonomous-tier endpoints", "stay reachable; the gate is read-sensitive scope only.");
+    }
+    return lines.join("\n");
+}
+/**
+ * Strip service sections from external-services/SKILL.md that correspond to
+ * unconfigured integrations. Sections are delimited by HTML comments:
+ *   <!-- service:calendar --> ... <!-- /service:calendar -->
+ * When `configuredServices` is empty the content is returned unchanged — the
+ * "no services configured yet" case keeps every section so the agent can see
+ * the full menu. Only strips once the user has configured at least one
+ * service (and therefore expressed an intent to narrow the surface).
+ */
+export function stripUnconfiguredServices(content, configuredServices) {
+    if (configuredServices.size === 0)
+        return content;
+    const servicePattern = /<!-- service:(\w+) -->\n([\s\S]*?)<!-- \/service:\1 -->\n?/g;
+    return content.replace(servicePattern, (match, service) => configuredServices.has(service) ? match : "");
+}
+/** Strip YAML frontmatter (--- ... ---) from markdown content. */
+function stripFrontmatter(content) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx < 0)
+        return content;
+    return content.slice(endIdx + 4).replace(/^\n+/, "");
+}
+/**
+ * Adapt a SKILL.md for CLI backends (Codex / Gemini): retain only `name`,
+ * `description`, and `when_to_use` frontmatter fields, stripping
+ * Claude-specific fields like `allowed-tools`. The body content is
+ * preserved unchanged.
+ *
+ * `when_to_use` is the secondary trigger-shape clarification documented
+ * in `SKILLS-PHASE-2-PLAN.md` §3.2 / §5; the Claude Agent SDK reads it
+ * verbatim from `q.when_to_use` (verified against
+ * `claude-agent-sdk@0.2.98/cli.js`). Preserving it on the CLI side keeps
+ * the per-backend skill frontmatter aligned even though Codex / Gemini
+ * do not currently consume the field — drift would surface as a missing
+ * activation hint when they eventually do.
+ *
+ * Assumes `name`, `description`, and `when_to_use` are each single-line
+ * YAML scalars (no `|` / `>` block forms). A multi-line `when_to_use:`
+ * is matched only by its first line — the `.+` regex stops at the
+ * newline — but since YAML block scalars start with the line that
+ * contains only `|` or `>`, the captured value would be the empty
+ * indicator and the inlined value would be useless. Phase 2 v1 keeps
+ * this conservative: callers must use single-line scalars (NG5).
+ */
+export function adaptSkillForCli(content) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx < 0)
+        return content;
+    const frontmatter = content.slice(4, endIdx);
+    const body = content.slice(endIdx + 4);
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    const whenMatch = frontmatter.match(/^when_to_use:\s*(.+)$/m);
+    // Reject multi-line block scalars (`when_to_use: |` / `when_to_use: >`):
+    // their first-line capture would just be the indicator. Falling through
+    // to "no when_to_use" matches the documented contract (§3.4.2 #9).
+    const whenIsBlockScalar = whenMatch !== null && /^[|>][-+]?\s*$/.test(whenMatch[1].trim());
+    const parts = ["---"];
+    if (nameMatch)
+        parts.push(`name: ${nameMatch[1].trim()}`);
+    if (descMatch)
+        parts.push(`description: ${descMatch[1].trim()}`);
+    if (whenMatch && !whenIsBlockScalar) {
+        parts.push(`when_to_use: ${whenMatch[1].trim()}`);
+    }
+    parts.push("---");
+    return parts.join("\n") + body;
+}
+/**
+ * Resolve `{{> base }}` include directives in a skill/task-flow variant file.
+ * Reads `SKILL.base.md` (or `<key>.base.md` for task flows) from `basePath`
+ * and replaces every occurrence of `{{> base }}` with the base file's content
+ * (frontmatter stripped). A missing or empty base file is silently ignored.
+ *
+ * Only `{{> base }}` is supported — this is intentionally minimal (§4.7
+ * design note: "~40 lines of pure TS").
+ *
+ * @deprecated DELEGATED-PROXY-API-DESIGN.md §11 — after Phase D no in-tree
+ * skill uses `{{> base }}`: mail / external-services unified their bodies
+ * during Phase D, and the lone surviving `notion/SKILL.base.md` was
+ * removed in Phase 9 (its hourly-check read-only constraint moved to
+ * `routine.hourly_check.md` task-flow where the rule applies in every
+ * integration mode, including same-backend delegated where the skill
+ * body is dropped). The helper is retained for future composition needs;
+ * remove the call sites in `materializeClaudeSession` /
+ * `materializeCliSession` when no consumer reappears.
+ */
+export function renderPartialIncludes(content, basePath) {
+    if (!content.includes("{{> base }}"))
+        return content;
+    if (!existsSync(basePath))
+        return content.replace(/\{\{> base \}\}/g, "");
+    const baseRaw = readFileSync(basePath, "utf-8");
+    const baseContent = stripFrontmatter(baseRaw).trim();
+    return content.replace(/\{\{> base \}\}/g, baseContent);
+}
+/**
+ * Resolve `{{> ref:<name> }}` directives in a skill body by inlining
+ * `references/<name>.md` (frontmatter stripped) from the skill's source dir.
+ *
+ * Mirrors `renderPartialIncludes` but is intra-skill, not cross-skill: each
+ * skill carries its own `references/` dir. Used by progressive-disclosure
+ * skills (planned for `mail`, `roadmap`, `reading`, `user-interview` after
+ * Phase 2-B) so heavy reference tables can live next to the skill body
+ * without bloating the navigation overview.
+ *
+ * Behaviour:
+ *  - Missing `references/<name>.md` → directive replaced with empty string;
+ *    logged at WARN. (Mirrors the deprecated helper's missing-base behaviour.)
+ *  - The directive matches `{{> ref:<name> }}` with the strict-kebab name
+ *    pattern `[a-z][a-z0-9-]*`. Path-traversal (`../`, leading underscore,
+ *    uppercase) is rejected at the regex level — `existsSync` is never
+ *    consulted for invalid names.
+ *  - Multiple occurrences each inline the same file's content (re-read per
+ *    occurrence — pinned by the unit tests so a later caching refactor must
+ *    surface as a deliberate change).
+ *  - Frontmatter on the reference file (if present) is stripped before
+ *    inline, so reference files can carry `---\nkind: reference\n---`
+ *    headers for tooling without leaking YAML into skill bodies.
+ *  - The resolver is NOT fence-aware; a directive inside a triple-backtick
+ *    fence is still expanded. This matches `renderPartialIncludes` and is
+ *    deliberate for v1 — fence-aware resolution would be a separate refactor.
+ *
+ * Phase 2-A ships compiler-only; no in-tree skill carries a directive yet
+ * (`skills-manifest.test.ts` pins `0` as the lockstep count). Phase 2-B
+ * starts emitting them per the migration map in `SKILLS-PHASE-2-PLAN.md`.
+ */
+export function renderReferenceIncludes(content, skillSrcDir) {
+    return content.replace(/\{\{> ref:([a-z][a-z0-9-]*) \}\}/g, (_match, name) => {
+        const refPath = join(skillSrcDir, "references", `${name}.md`);
+        if (!existsSync(refPath)) {
+            logger.warn({ skillSrcDir, name }, "renderReferenceIncludes: missing reference file");
+            return "";
+        }
+        return stripFrontmatter(readFileSync(refPath, "utf-8")).trim();
+    });
+}
+/**
+ * §7.7 — apply the per-integration tool-deny policy to a delegated skill
+ * body. Two enforcement modes:
+ *
+ *  - **Claude (hard enforcement):** parse the YAML frontmatter and remove
+ *    every `allowed-tools` entry whose unsuffixed name (after the
+ *    descriptor's `toolNamespace`) is in `deniedTools`. The Claude Agent
+ *    SDK refuses to invoke any tool not present in `allowed-tools`, so
+ *    this is hard enforcement at the SDK boundary.
+ *
+ *  - **Codex / Gemini (soft enforcement):** append a "Denied tools (do
+ *    not invoke)" prose block at the end of the skill body listing the
+ *    full namespaced tool names. The CLI surfaces have no per-tool deny
+ *    mechanism comparable to Claude's `allowed-tools`; the prose is the
+ *    only guard. Documented soft-enforcement gap.
+ *
+ * Stale entries (a deniedTools name that doesn't match any tool in the
+ * active backend's `capabilityTools`) are silently ignored — the API
+ * already rejects them at PATCH time, but a delegatedBackend swap can
+ * leave Claude-namespaced names in a list now active for Codex.
+ *
+ * Run AFTER `renderPartialIncludes` and `stripUnconfiguredServices` so
+ * partial includes and service-section gating land first.
+ */
+export function applyDeniedTools(content, integrationKey, backendId, deniedTools) {
+    if (deniedTools.length === 0)
+        return content;
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    if (!connector)
+        return content;
+    const { active } = filterDeniedToolsForBackend(integrationKey, backendId, deniedTools);
+    if (active.length === 0)
+        return content;
+    const namespacedDenied = active.map((t) => `${connector.toolNamespace}${t}`);
+    if (backendId === "claude") {
+        return filterClaudeAllowedTools(content, new Set(namespacedDenied));
+    }
+    return appendCliDenyBlock(content, namespacedDenied);
+}
+/**
+ * Strip every `allowed-tools` frontmatter entry whose name appears in
+ * `deniedSet`. Preserves frontmatter ordering, line breaks, and any other
+ * fields. Tolerates two YAML shapes:
+ *
+ *   allowed-tools:
+ *     - name1
+ *     - name2
+ *
+ *   allowed-tools: [name1, name2]
+ *
+ * The first form is what every skill in `agent-assets/skills/` uses today;
+ * the inline form is supported because it's valid YAML and the API + UI
+ * have no way to prevent a hand-edited skill from using it.
+ */
+function filterClaudeAllowedTools(content, deniedSet) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx < 0)
+        return content;
+    const frontmatter = content.slice(4, endIdx);
+    const body = content.slice(endIdx + 4);
+    const lines = frontmatter.split("\n");
+    const out = [];
+    let inAllowedTools = false;
+    for (const line of lines) {
+        if (/^allowed-tools:\s*\[/.test(line)) {
+            // Inline-array form: parse, filter, re-emit on one line.
+            const m = /^(allowed-tools:\s*)\[([^\]]*)\]/.exec(line);
+            if (m) {
+                const items = m[2]
+                    .split(",")
+                    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                    .filter((s) => s.length > 0 && !deniedSet.has(s));
+                out.push(`${m[1]}[${items.join(", ")}]`);
+                continue;
+            }
+        }
+        if (/^allowed-tools:\s*$/.test(line)) {
+            inAllowedTools = true;
+            out.push(line);
+            continue;
+        }
+        if (inAllowedTools) {
+            // Block-list form continuation. A block-list item is `  - <name>`;
+            // anything else (next top-level key, blank, or end of frontmatter)
+            // ends the section.
+            const itemMatch = /^\s*-\s*(.+?)\s*$/.exec(line);
+            if (itemMatch) {
+                const name = itemMatch[1].replace(/^["']|["']$/g, "");
+                if (!deniedSet.has(name))
+                    out.push(line);
+                continue;
+            }
+            // Anything else closes the block.
+            inAllowedTools = false;
+        }
+        out.push(line);
+    }
+    return `---\n${out.join("\n")}\n---${body}`;
+}
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — render a top-level prose
+ * deny block listing every same-backend integration tool the user has
+ * denied. Returns `null` when no integration is in same-backend mode for
+ * this backend or the deny lists are empty.
+ *
+ * Codex (γ outcome): this prose is the ONLY enforcement surface — the
+ * Codex CLI's connector apps have no admin-policy or per-tool deny config.
+ * The agent profile (`AGENTS.md`) inlines this block above the behavioral
+ * rules so it is impossible to miss.
+ *
+ * Gemini: duplicate intent — admin-policy already hard-denies these tools
+ * (§4.3.3 hard enforcement), but echoing the deny in prose saves tokens
+ * the model would otherwise spend drafting a doomed call.
+ */
+export function buildSameBackendDenyBlock(integrations, sessionBackend) {
+    const map = collectSessionDeniedTools(integrations, sessionBackend);
+    if (map.size === 0)
+        return null;
+    const lines = [
+        "## Denied tools (per-integration)",
+        "",
+        "The user has restricted the following connector tools for this session.",
+        "Do NOT invoke them in any flow — including hourly check, morning routine,",
+        "or DM responses. If a workflow appears to require one, stop and tell the",
+        "user the tool is denied.",
+    ];
+    for (const [key, names] of map.entries()) {
+        lines.push("", `### ${key}`, "");
+        for (const n of names)
+            lines.push(`- \`${n}\``);
+    }
+    return lines.join("\n");
+}
+/**
+ * Append a soft-enforcement deny block to a CLI skill body. The block is
+ * idempotent — re-running with the same denied set produces identical
+ * output.
+ */
+function appendCliDenyBlock(content, namespacedDenied) {
+    // Strip any prior deny block we wrote, so re-materialization with a
+    // changed list doesn't accumulate stale ones. The block starts with
+    // `\n## Denied tools (do not invoke)` (one preceding newline, the join
+    // contributes the second) and runs until either the next `## ` heading
+    // or end of file.
+    const stripped = content.replace(/\n+## Denied tools \(do not invoke\)[\s\S]*?(?=\n## (?!Denied tools)|$)/, "");
+    const items = namespacedDenied.map((n) => `- \`${n}\``).join("\n");
+    // Two leading empty strings → block begins with "\n\n## " so the heading
+    // sits on its own paragraph (markdown convention) regardless of what
+    // trailing whitespace the body carried.
+    const block = [
+        "",
+        "",
+        "## Denied tools (do not invoke)",
+        "",
+        "The user has restricted these connector tools for this integration. Do",
+        "NOT invoke them in any flow — including hourly check, morning routine,",
+        "or DM responses. If a workflow appears to require one, stop and tell",
+        "the user the tool is denied.",
+        "",
+        items,
+        "",
+    ].join("\n");
+    return stripped.replace(/\s*$/, "") + block;
+}
+/**
+ * Apply the deny pass for every integration whose `skillsTouched` OR
+ * `deniedToolsAppliesToSkills` includes the given skill slug. A skill that
+ * touches no integration leaves content unchanged. Touching multiple
+ * integrations runs the pass once per integration so each contributes its
+ * own deny list.
+ *
+ * Hard enforcement of the same deny list for cross-backend delegated
+ * calls lives at the `POST /api/integrations/:key/invoke` chokepoint
+ * (DELEGATED-MODE-V2-DESIGN.md §4.3.2). For same-backend native MCP it
+ * is enforced via SDK `disallowedTools` (Claude) / admin policy
+ * (Gemini); see `collectSessionDeniedTools` (§4.3.3).
+ */
+export function applyAllDeniedToolsForSkill(content, skillSlug, backendId, integrations) {
+    let result = content;
+    for (const key of INTEGRATION_KEYS) {
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        const touched = descriptor.skillsTouched.includes(skillSlug)
+            || (descriptor.deniedToolsAppliesToSkills?.includes(skillSlug) ?? false);
+        if (!touched)
+            continue;
+        const state = integrations[key];
+        if (!state)
+            continue;
+        if (state.mode !== "delegated")
+            continue;
+        if (!state.delegatedBackend || state.delegatedBackend !== backendId)
+            continue;
+        const denied = state.deniedTools ?? [];
+        if (denied.length === 0)
+            continue;
+        result = applyDeniedTools(result, key, backendId, denied);
+    }
+    return result;
+}
+/**
+ * Remove any built-in skill directory under `destRoot` whose slug is not
+ * in `keep`. Recognises a directory as a built-in by its presence under
+ * the source `agent-assets/skills/` tree — anything else (user-authored
+ * skill, accounts.md, etc.) is left alone, since `syncAllUserSkills` is
+ * the canonical writer for those.
+ *
+ * Idempotent and side-effect-free when there is nothing to prune.
+ * Exported for unit testing only.
+ */
+export function pruneStaleBuiltinSkillDirs(destRoot, sourceSkillsRoot, keep) {
+    if (!existsSync(destRoot))
+        return;
+    if (!existsSync(sourceSkillsRoot))
+        return;
+    const keepSet = new Set(keep);
+    const builtinSlugs = new Set();
+    for (const entry of readdirSync(sourceSkillsRoot, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            builtinSlugs.add(entry.name);
+    }
+    for (const entry of readdirSync(destRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!builtinSlugs.has(entry.name))
+            continue;
+        if (keepSet.has(entry.name))
+            continue;
+        rmSync(join(destRoot, entry.name), { recursive: true, force: true });
+    }
+}
+function readTreeFiles(root) {
+    if (!existsSync(root)) {
+        return [];
+    }
+    const files = [];
+    for (const relPath of walkTree(root)) {
+        const absPath = join(root, relPath);
+        const stat = statSync(absPath);
+        files.push({
+            path: relPath,
+            content: readFileSync(absPath, "utf-8"),
+            updatedAt: stat.mtime.toISOString(),
+        });
+    }
+    return files;
+}
+function walkTree(root, current = root) {
+    if (!existsSync(current)) {
+        return [];
+    }
+    const entries = readdirSync(current, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const absPath = join(current, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkTree(root, absPath));
+            continue;
+        }
+        files.push(relative(root, absPath));
+    }
+    return files.sort();
+}
+//# sourceMappingURL=skills-compiler.js.map