@aitne/daemon 0.1.0

package/dist/core/management-registry.js

@@ -0,0 +1,906 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rename, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import * as chokidar from "chokidar";
+import { isValidOutputPath, sotBindingsSchema, } from "@aitne/shared";
+import { CONTEXT_RELATIVE_PATHS } from "./context-paths.js";
+import { writeFileAtomically } from "./atomic-write.js";
+import { InMemoryManagementMdWriteLockManager, withManagementMdWriteLock, } from "./management-md-write-lock.js";
+import { listManagedTasks, } from "../db/managed-tasks-store.js";
+import { readSotBindings, writeSotBindings, } from "../db/sot-bindings-store.js";
+import { clearManagementParseFailures, recordManagementParseFailure, } from "../db/management-parse-failures-store.js";
+import { recordManagementMdRenderDuration } from "./management-telemetry.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("management-registry");
+/**
+ * `rules/management.md` registry — render / parse / boot / watch
+ * (docs/design/21-management-registry-and-entities.md §7.2, §11, P2).
+ *
+ * Architectural mirror of `core/management-md.ts` (which owns the
+ * top-level `integrations.md`): SQLite is authoritative; the file is a
+ * deterministic render. The registry guarantees:
+ *
+ *   - Boot — read DB → render → write file (NFR-2: ≤ 200 ms for 100 rows).
+ *     If a v2 file exists (no `schema_version` frontmatter), back it up
+ *     to `rules/management.v2.bak.md` and write a fresh v3 (§16.2).
+ *   - Render — preserves §C "Active Policies" stub verbatim and any
+ *     free prose between the four canonical sections (FR-18, §0.1).
+ *   - Parse — round-trips §A and §B tables; rows that fail their
+ *     domain/type-plural/`mt_id` invariants are dropped with a
+ *     `management_parse_failures` entry (§9.1 parse rules, NFR-7).
+ *   - Watch — chokidar-driven; self-writes are stamped + skipped to
+ *     avoid the file→DB→file loop (NFR-4). Fatal parse errors revert
+ *     the file from DB. Section A hand-edits are applied to
+ *     `settings.sot_bindings`. Section B hand-edits to managed tasks
+ *     are NOT applied in P2 — registering / mutating managed tasks
+ *     ships with the API surface in P3 — but a structurally-clean §B
+ *     parse that disagrees with the DB triggers a re-render so the
+ *     file converges back to the DB state (and a parse_failures row
+ *     surfaces a hint on the dashboard).
+ *
+ * Concurrency: every write goes through {@link withManagementMdWriteLock}
+ * so a competing API write or a chokidar reconciliation cannot
+ * interleave between (render → atomic write → snapshot). The
+ * boot reconciler also acquires the lock.
+ */
+// ── Constants ──────────────────────────────────────────────────────────────
+/**
+ * Frontmatter `schema_version` written by this module. Bumped only on
+ * incompatible structural changes (§0.1, §16.3). The package's
+ * `template_version` is owned by the asset-packaging step and lives in
+ * the template file, not here.
+ */
+export const MANAGEMENT_MD_SCHEMA_VERSION = 3;
+const RELATIVE_PATH = CONTEXT_RELATIVE_PATHS.rules.management;
+/** Sibling path for the v2 → v3 backup written by the boot reconciler. */
+const V2_BACKUP_RELATIVE_PATH = "rules/management.v2.bak.md";
+const SECTION_A_HEADER = "## A. Source-of-Truth bindings";
+const SECTION_B_HEADER = "## B. Managed tasks (active only)";
+const SECTION_C_HEADER = "## C. Active Policies";
+const SECTION_A_TABLE_HEADER = "| Category | SoT app | Mirror MD path | Policy | Writer |";
+const SECTION_A_TABLE_DIVIDER = "|---|---|---|---|---|";
+const SECTION_B_TABLE_HEADER = "| ID | Intent | App | Cadence | Output path | Schedule | Last run | Last result |";
+const SECTION_B_TABLE_DIVIDER = "|---|---|---|---|---|---|---|---|";
+const DEFAULT_C_STUB = [
+    SECTION_C_HEADER,
+    "",
+    "Auto-maintained by the daemon (do not edit). Source files live under",
+    "`rules/policies/<slug>.md`; capture new policies via the",
+    "`management-policy` skill. Full index: [[rules/policies/_index.md]]",
+    "",
+    "_No active policies yet._",
+    "",
+].join("\n");
+const DEFAULT_NOTES_BLOCK = [
+    "## Notes",
+    "",
+    "- The agent cannot use `Edit` / `Write` tools on this file — writes go",
+    "  through `/api/context/rules/management` (locked + snapshotted) or the",
+    "  managed-tasks / sot-bindings API surfaces.",
+    "- This file is injected into every flow via `policy-files.ts`. Keep it",
+    "  concise so prompt assembly stays cheap.",
+    "- Free prose between sections (Language, Conflict handling, etc.) is",
+    "  preserved across re-renders. Tables and frontmatter stay English.",
+    "",
+].join("\n");
+/**
+ * `## H1` headers the parser recognizes as canonical section markers.
+ * Anything between two consecutive markers is "free prose" preserved
+ * verbatim across re-renders (§9.1 render rules; §0.1).
+ */
+const SECTION_HEADERS = [
+    SECTION_A_HEADER,
+    SECTION_B_HEADER,
+    SECTION_C_HEADER,
+];
+// ── Path resolution ────────────────────────────────────────────────────────
+export function getManagementMdPath(contextDir) {
+    return resolve(contextDir, RELATIVE_PATH);
+}
+export function getManagementMdV2BackupPath(contextDir) {
+    return resolve(contextDir, V2_BACKUP_RELATIVE_PATH);
+}
+// ── Self-write suppression ─────────────────────────────────────────────────
+//
+// Same pattern as `core/management-md.ts`: every daemon-initiated write
+// stamps the absolute path; the chokidar handler consumes the stamp and
+// short-circuits. The 5 s window matches `management-md.ts` and
+// chokidar's default `awaitWriteFinish` budget.
+const pendingSelfWrites = new Set();
+function markSelfWrite(absPath) {
+    pendingSelfWrites.add(absPath);
+    setTimeout(() => pendingSelfWrites.delete(absPath), 5_000).unref();
+}
+function consumeSelfWrite(absPath) {
+    return pendingSelfWrites.delete(absPath);
+}
+function renderFrontmatter(updatedDate) {
+    return [
+        "---",
+        "type: rule",
+        "slug: management",
+        "owner: shared",
+        `updated: ${updatedDate}`,
+        "template_version: 2",
+        `schema_version: ${MANAGEMENT_MD_SCHEMA_VERSION}`,
+        "---",
+    ].join("\n");
+}
+function escapeCell(value) {
+    // §13.3 — defense-in-depth: pipe and newline characters never appear
+    // in a rendered cell (the parser would split them mid-row). Validators
+    // already strip these from inputs; the renderer's escape is the
+    // belt-and-suspenders layer.
+    return value.replace(/[\r\n]+/g, " ").replace(/\|/g, "\\|").trim();
+}
+function emDashOr(value) {
+    const v = (value ?? "").trim();
+    return v.length === 0 ? "—" : v;
+}
+function renderSotBindingRow(b) {
+    return [
+        "|",
+        escapeCell(b.category),
+        "|",
+        escapeCell(b.sotApp),
+        "|",
+        escapeCell(emDashOr(b.mirrorPath)),
+        "|",
+        escapeCell(emDashOr(b.policy)),
+        "|",
+        escapeCell(b.writer),
+        "|",
+    ].join(" ");
+}
+function renderSectionA(bindings) {
+    const lines = [SECTION_A_HEADER, ""];
+    if (bindings.length === 0) {
+        lines.push(SECTION_A_TABLE_HEADER);
+        lines.push(SECTION_A_TABLE_DIVIDER);
+        lines.push("");
+        lines.push("_No SoT bindings yet — populate via the setup wizard or `PUT /api/sot-bindings`._");
+        lines.push("");
+        return lines.join("\n");
+    }
+    lines.push(SECTION_A_TABLE_HEADER);
+    lines.push(SECTION_A_TABLE_DIVIDER);
+    for (const b of bindings)
+        lines.push(renderSotBindingRow(b));
+    lines.push("");
+    return lines.join("\n");
+}
+function renderManagedTaskRow(row) {
+    return [
+        "|",
+        escapeCell(row.id),
+        "|",
+        escapeCell(row.intent),
+        "|",
+        escapeCell(row.app),
+        "|",
+        escapeCell(row.cadence),
+        "|",
+        escapeCell(emDashOr(row.output_path)),
+        "|",
+        escapeCell(`rs:${row.schedule_id}`),
+        "|",
+        escapeCell(emDashOr(row.last_run_at)),
+        "|",
+        escapeCell(emDashOr(row.last_result)),
+        "|",
+    ].join(" ");
+}
+function renderSectionB(rows) {
+    const lines = [SECTION_B_HEADER, ""];
+    if (rows.length === 0) {
+        lines.push(SECTION_B_TABLE_HEADER);
+        lines.push(SECTION_B_TABLE_DIVIDER);
+        lines.push("");
+        lines.push('_No managed tasks yet — register via DM (e.g. "Zoom 毎日10時にチェック")');
+        lines.push("or the dashboard's Settings → Management page._");
+        lines.push("");
+        return lines.join("\n");
+    }
+    lines.push(SECTION_B_TABLE_HEADER);
+    lines.push(SECTION_B_TABLE_DIVIDER);
+    for (const row of rows)
+        lines.push(renderManagedTaskRow(row));
+    lines.push("");
+    return lines.join("\n");
+}
+function renderSectionC(preserved) {
+    if (preserved && preserved.trim().length > 0) {
+        // The reconciler hands back the §C block verbatim — including its
+        // header — so the renderer doesn't strip a user's annotation.
+        return preserved.replace(/\s*$/, "\n");
+    }
+    return DEFAULT_C_STUB;
+}
+function renderFreeProse(preserved) {
+    if (!preserved || preserved.size === 0)
+        return DEFAULT_NOTES_BLOCK;
+    const blocks = [];
+    for (const [, body] of preserved) {
+        blocks.push(body.replace(/\s*$/, "\n"));
+    }
+    // Always trail with the canonical Notes block so the standard text
+    // does not disappear when the user keeps their own free prose.
+    if (!preserved.has("## Notes"))
+        blocks.push(DEFAULT_NOTES_BLOCK);
+    return blocks.join("\n");
+}
+/**
+ * Render the file body from DB-resident state. Idempotent: same input
+ * → byte-identical output across calls and across releases of the same
+ * `schema_version` (NFR-2 / NFR-1c).
+ */
+export function renderManagementMd(input, options = {}) {
+    const updatedDate = options.updatedDate ?? new Date().toISOString().slice(0, 10);
+    return [
+        renderFrontmatter(updatedDate),
+        "# Management Rules",
+        "",
+        "This file is the agent's structured registry of (a) Source-of-Truth",
+        "bindings and (b) active managed tasks. It is rendered from the",
+        "daemon's DB and re-parsed when hand-edited; see",
+        "`docs/design/21-management-registry-and-entities.md` for the spec.",
+        "",
+        renderSectionA(input.sotBindings),
+        renderSectionB(input.managedTasks),
+        renderSectionC(options.preservedSectionC),
+        renderFreeProse(options.preservedFreeProse),
+    ].join("\n");
+}
+const FRONTMATTER_RE = /^---\r?\n([\s\S]+?)\r?\n---\r?\n?/;
+function parseFrontmatter(body) {
+    const match = FRONTMATTER_RE.exec(body);
+    if (!match) {
+        return { schemaVersion: null, rest: body, hasFrontmatter: false };
+    }
+    const fmBody = match[1];
+    const rest = body.slice(match[0].length);
+    const versionLine = fmBody
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.startsWith("schema_version:"));
+    if (!versionLine) {
+        return { schemaVersion: null, rest, hasFrontmatter: true };
+    }
+    const value = versionLine.slice("schema_version:".length).trim();
+    const n = Number.parseInt(value, 10);
+    return {
+        schemaVersion: Number.isFinite(n) ? n : null,
+        rest,
+        hasFrontmatter: true,
+    };
+}
+function sliceSections(body) {
+    const lines = body.split(/\r?\n/);
+    const canonical = new Map();
+    const freeProse = new Map();
+    let currentHeader = null;
+    let buffer = [];
+    const flush = () => {
+        if (currentHeader === null)
+            return;
+        const sliceBody = buffer.join("\n");
+        if (SECTION_HEADERS.includes(currentHeader)) {
+            canonical.set(currentHeader, { header: currentHeader, body: sliceBody });
+        }
+        else {
+            freeProse.set(currentHeader, `${currentHeader}\n${sliceBody}`);
+        }
+    };
+    for (const line of lines) {
+        if (/^##\s+/.test(line)) {
+            flush();
+            currentHeader = line.trim();
+            buffer = [];
+            continue;
+        }
+        if (currentHeader !== null)
+            buffer.push(line);
+    }
+    flush();
+    return { canonical, freeProse };
+}
+function splitTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
+        return null;
+    return trimmed
+        .slice(1, -1)
+        .split(/(?<!\\)\|/)
+        .map((cell) => cell.replace(/\\\|/g, "|").trim());
+}
+function isDividerRow(cells) {
+    return cells.every((c) => /^:?-{2,}:?$/.test(c.trim()));
+}
+function emDashToNull(value) {
+    const v = value.trim();
+    if (v === "" || v === "—")
+        return null;
+    return v;
+}
+function parseSectionA(slice, failures) {
+    if (!slice)
+        return [];
+    const rawRows = slice.body
+        .split(/\r?\n/)
+        .map(splitTableRow)
+        .filter((r) => r !== null);
+    if (rawRows.length === 0)
+        return [];
+    // Header + divider + data
+    if (rawRows.length < 2 || !isDividerRow(rawRows[1])) {
+        failures.push({
+            section: "A",
+            reason: "section A table missing header/divider",
+        });
+        return [];
+    }
+    const dataRows = rawRows.slice(2);
+    const bindings = [];
+    for (const row of dataRows) {
+        if (row.length < 5) {
+            failures.push({
+                section: "A",
+                reason: `section A row has ${row.length} cells, expected 5`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        if (row.length > 5) {
+            // §9.1 parse rules — "Unknown columns are dropped with a warning in
+            // parse_failures table." Keep the row (best-effort recovery), but
+            // surface the divergence so the dashboard banner prompts the user
+            // to clean up the extra cells.
+            failures.push({
+                section: "A",
+                reason: `section A row has ${row.length} cells; expected 5 (extra columns dropped)`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+        }
+        const candidate = {
+            category: row[0],
+            sotApp: row[1],
+            mirrorPath: emDashToNull(row[2]),
+            policy: emDashToNull(row[3]),
+            writer: row[4],
+        };
+        const parsed = sotBindingsSchema.safeParse([candidate]);
+        if (!parsed.success) {
+            failures.push({
+                section: "A",
+                reason: parsed.error.issues
+                    .map((i) => `${i.path.join(".")}: ${i.message}`)
+                    .join("; "),
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        bindings.push(parsed.data[0]);
+    }
+    return bindings;
+}
+const RS_REF_RE = /^rs:(\d+)$/;
+const MT_ID_RE = /^mt_[1-9]\d*$/;
+function parseSectionB(slice, failures) {
+    if (!slice)
+        return [];
+    const rawRows = slice.body
+        .split(/\r?\n/)
+        .map(splitTableRow)
+        .filter((r) => r !== null);
+    if (rawRows.length === 0)
+        return [];
+    if (rawRows.length < 2 || !isDividerRow(rawRows[1])) {
+        failures.push({
+            section: "B",
+            reason: "section B table missing header/divider",
+        });
+        return [];
+    }
+    const dataRows = rawRows.slice(2);
+    const out = [];
+    for (const row of dataRows) {
+        if (row.length < 8) {
+            failures.push({
+                section: "B",
+                reason: `section B row has ${row.length} cells, expected 8`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        if (row.length > 8) {
+            // §9.1 parse rules — "Unknown columns are dropped with a warning in
+            // parse_failures table." Keep the row (best-effort recovery), but
+            // surface the divergence so the dashboard banner prompts the user
+            // to clean up the extra cells. The id may not be valid yet at this
+            // point in parsing, so the warning is row-shape-only.
+            failures.push({
+                section: "B",
+                reason: `section B row has ${row.length} cells; expected 8 (extra columns dropped)`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+        }
+        const id = row[0].trim();
+        const intent = row[1].trim();
+        const app = row[2].trim();
+        const cadence = row[3].trim();
+        const outputCell = emDashToNull(row[4]);
+        const scheduleCell = row[5].trim();
+        const lastRunAt = emDashToNull(row[6]);
+        const lastResult = emDashToNull(row[7]);
+        if (!MT_ID_RE.test(id)) {
+            failures.push({
+                section: "B",
+                reason: `section B: invalid id "${id}" (must match /^mt_[1-9]\\d*$/)`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        if (app === "") {
+            failures.push({
+                section: "B",
+                reason: `section B (${id}): empty App column`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        let scheduleId = null;
+        if (scheduleCell !== "" && scheduleCell !== "—") {
+            const m = RS_REF_RE.exec(scheduleCell);
+            if (!m) {
+                failures.push({
+                    section: "B",
+                    reason: `section B (${id}): Schedule cell "${scheduleCell}" does not match /^rs:\\d+$/`,
+                    raw: `| ${row.join(" | ")} |`,
+                });
+                continue;
+            }
+            scheduleId = Number.parseInt(m[1], 10);
+        }
+        if (outputCell !== null && !isValidOutputPath(outputCell)) {
+            failures.push({
+                section: "B",
+                reason: `section B (${id}): invalid output_path "${outputCell}"`,
+                raw: `| ${row.join(" | ")} |`,
+            });
+            continue;
+        }
+        out.push({
+            id,
+            intent,
+            app,
+            cadence,
+            outputPath: outputCell,
+            scheduleId,
+            lastRunAt,
+            lastResult,
+        });
+    }
+    return out;
+}
+/**
+ * Parse a v3 management.md body. Frontmatter without `schema_version`
+ * yields `schemaVersion === null`; the boot reconciler interprets that
+ * as "v2 file, back up and replace".
+ *
+ * Section-level errors (missing canonical header, malformed table)
+ * accumulate into `failures` but do not flip `ok` unless they make the
+ * file structurally unparseable. The strict-fail bar is reserved for
+ * frontmatter that does not parse at all.
+ */
+export function parseManagementMd(body) {
+    const failures = [];
+    const errors = [];
+    const fm = parseFrontmatter(body);
+    if (!fm.hasFrontmatter) {
+        errors.push("frontmatter missing");
+    }
+    const { canonical, freeProse } = sliceSections(fm.rest);
+    const sotBindings = parseSectionA(canonical.get(SECTION_A_HEADER), failures);
+    const managedTasks = parseSectionB(canonical.get(SECTION_B_HEADER), failures);
+    const sectionC = canonical.get(SECTION_C_HEADER);
+    // §A.10 — preserve §C *verbatim* including its header so the renderer
+    // round-trips a hand-edited Active Policies block without diff.
+    const preservedSectionC = sectionC
+        ? `${sectionC.header}\n${sectionC.body}`.replace(/\s*$/, "\n")
+        : null;
+    return {
+        ok: errors.length === 0,
+        schemaVersion: fm.schemaVersion,
+        sotBindings,
+        managedTasks,
+        preservedSectionC,
+        preservedFreeProse: freeProse,
+        failures,
+        errors,
+    };
+}
+export async function renderAndWriteManagementMd(contextDir, db, input, options) {
+    if (!options.lockManager.isHeldBy(options.lockId)) {
+        throw new Error("renderAndWriteManagementMd: lockId is not the current holder of the management.md write lock");
+    }
+    // §14.3 `aitne_management_md_render_seconds` — capture wall-clock for
+    // the full render+write+snapshot path so the histogram reflects what
+    // a caller actually pays. Recorded in `finally` so the metric is
+    // emitted even when the snapshot insert below throws.
+    const renderStartedAt = Date.now();
+    try {
+        const path = getManagementMdPath(contextDir);
+        await mkdir(dirname(path), { recursive: true });
+        const body = renderManagementMd(input, options.render);
+        markSelfWrite(path);
+        writeFileAtomically(path, body);
+        let snapshotId = null;
+        try {
+            const result = db
+                .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger) VALUES (?, ?, ?)")
+                .run(RELATIVE_PATH, body, options.trigger);
+            snapshotId = Number(result.lastInsertRowid);
+        }
+        catch (err) {
+            // Snapshot is best-effort: a single insert failure should not
+            // strand the file write itself. Surface the error so observability
+            // catches recurring DB pressure.
+            logger.warn({ err, path: RELATIVE_PATH, trigger: options.trigger }, "management.md snapshot insert failed (file write succeeded)");
+        }
+        return { path, body, snapshotId };
+    }
+    finally {
+        recordManagementMdRenderDuration(Date.now() - renderStartedAt);
+    }
+}
+export async function readAndParseManagementMd(contextDir) {
+    const path = getManagementMdPath(contextDir);
+    try {
+        const body = await readFile(path, "utf-8");
+        return parseManagementMd(body);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * §16.2 detection rule:
+ *
+ *   | schema_version absent | v2 → back up + fresh v3 |
+ *   | schema_version: 2     | pre-release; treat as v3-equivalent |
+ *   | schema_version: 3     | current; reconcile in place |
+ *   | schema_version >= 4   | forward-incompat; fresh v3 + warn   |
+ *
+ * The reconciler always produces a clean v3 render before returning so
+ * downstream readers never see a partially-applied state.
+ */
+export async function bootstrapManagementRegistry(contextDir, db, lockManager = new InMemoryManagementMdWriteLockManager()) {
+    const path = getManagementMdPath(contextDir);
+    const lockResult = await withManagementMdWriteLock(lockManager, async () => {
+        const dbState = {
+            sotBindings: readSotBindings(db),
+            managedTasks: listManagedTasks(db),
+        };
+        let fileExists = true;
+        try {
+            await stat(path);
+        }
+        catch (err) {
+            // Non-ENOENT stat errors (EACCES, EIO) are platform-rare; the
+            // rethrow exists so a permissions issue surfaces loudly instead
+            // of being silently treated as missing.
+            /* c8 ignore next */
+            if (err.code !== "ENOENT")
+                throw err;
+            fileExists = false;
+        }
+        if (!fileExists) {
+            const lockId = lockManager.getHolder();
+            // Defensive guard: held lock invariant means lockId is always
+            // present here. The branch exists only to surface a corrupted-
+            // lock state loudly rather than silently.
+            /* c8 ignore start */
+            if (!lockId) {
+                throw new Error("management-registry: lock holder lost mid-boot (missing-file path)");
+            }
+            /* c8 ignore stop */
+            // Fresh write resets the parse-failure banner: there is no
+            // partially-recovered state to surface, so any prior diagnostic
+            // is moot.
+            clearManagementParseFailures(db);
+            const written = await renderAndWriteManagementMd(contextDir, db, dbState, { lockManager, lockId, trigger: "management-registry.boot.create" });
+            logger.info({ path: written.path }, "management.md created from DB defaults (file was missing)");
+            return {
+                path,
+                rewritten: true,
+                v2BackedUp: false,
+                v2BackupPath: null,
+                rendered: dbState,
+            };
+        }
+        const parsed = await readAndParseManagementMd(contextDir);
+        /* c8 ignore start — race-recovery path: the file existed at stat()
+           but vanished before read (concurrent rm). Tested through the
+           missing-file path above; reproducing the race in unit tests is
+           brittle and the recovery is the same code shape. */
+        if (!parsed) {
+            const raceLockId = lockManager.getHolder();
+            if (!raceLockId) {
+                throw new Error("management-registry: lock holder lost mid-boot (race path)");
+            }
+            await renderAndWriteManagementMd(contextDir, db, dbState, {
+                lockManager,
+                lockId: raceLockId,
+                trigger: "management-registry.boot.race",
+            });
+            return {
+                path,
+                rewritten: true,
+                v2BackedUp: false,
+                v2BackupPath: null,
+                rendered: dbState,
+            };
+        }
+        /* c8 ignore stop */
+        const lockId = lockManager.getHolder();
+        // Defensive guard mirroring the missing-file branch above.
+        /* c8 ignore start */
+        if (!lockId) {
+            throw new Error("management-registry: lock holder lost mid-boot (parsed path)");
+        }
+        /* c8 ignore stop */
+        let v2BackedUp = false;
+        let v2BackupPath = null;
+        let renderOptions = {};
+        if (parsed.schemaVersion === null) {
+            // v2 file detected — back it up before overwriting (§16.2).
+            v2BackupPath = getManagementMdV2BackupPath(contextDir);
+            await rename(path, v2BackupPath);
+            v2BackedUp = true;
+            logger.info({ from: path, to: v2BackupPath }, "management.md v2 backed up before fresh v3 render");
+        }
+        else if (parsed.schemaVersion >= MANAGEMENT_MD_SCHEMA_VERSION + 1) {
+            logger.warn({ detected: parsed.schemaVersion, current: MANAGEMENT_MD_SCHEMA_VERSION }, "management.md schema_version newer than this daemon — re-rendering as v3");
+        }
+        else {
+            // v2 (pre-release) or v3: round-trip parsed §A back into the DB
+            // so a hand-edit lands in the canonical store. §B is render-only
+            // in P2 (the API surface is P3); a divergence triggers a re-render.
+            reconcileSectionAToDb(db, parsed, dbState);
+            renderOptions = {
+                preservedSectionC: parsed.preservedSectionC ?? undefined,
+                preservedFreeProse: parsed.preservedFreeProse,
+            };
+        }
+        if (parsed.failures.length > 0) {
+            // Replay the failures into the DB diagnostic table so the
+            // dashboard banner reflects them; the boot pass clears stale
+            // failures first so a clean parse drops the banner.
+            clearManagementParseFailures(db);
+            for (const f of parsed.failures) {
+                recordManagementParseFailure(db, f);
+            }
+            logger.warn({ failureCount: parsed.failures.length }, "management.md boot parse produced row failures; recorded for the dashboard banner");
+        }
+        else if (parsed.errors.length === 0) {
+            clearManagementParseFailures(db);
+        }
+        // Always re-render so daemon-owned columns and any reverted §B
+        // hand-edits round-trip back to canonical form. The renderer reads
+        // the (possibly updated) DB state again — `dbState` above might be
+        // stale after `reconcileSectionAToDb`.
+        const rendered = {
+            sotBindings: readSotBindings(db),
+            managedTasks: listManagedTasks(db),
+        };
+        await renderAndWriteManagementMd(contextDir, db, rendered, {
+            lockManager,
+            lockId,
+            trigger: v2BackedUp
+                ? "management-registry.boot.v2-upgrade"
+                : "management-registry.boot.reconcile",
+            render: renderOptions,
+        });
+        return {
+            path,
+            rewritten: v2BackedUp,
+            v2BackedUp,
+            v2BackupPath,
+            rendered,
+        };
+    });
+    if (!lockResult.ok) {
+        // Another caller holds the lock (e.g. a competing boot). Render
+        // in read-only mode so callers still see consistent state.
+        logger.warn({ holder: lockResult.holder }, "management-registry boot skipped — write lock contended");
+        return {
+            path,
+            rewritten: false,
+            v2BackedUp: false,
+            v2BackupPath: null,
+            rendered: {
+                sotBindings: readSotBindings(db),
+                managedTasks: listManagedTasks(db),
+            },
+        };
+    }
+    return lockResult.value;
+}
+/**
+ * Apply a parsed §A block to the DB. Compared cell-by-cell against the
+ * current state so semantically-identical edits don't churn the
+ * `settings.updated_at` timestamp.
+ */
+function reconcileSectionAToDb(db, parsed, dbState) {
+    if (parsed.sotBindings.length === 0 && dbState.sotBindings.length === 0) {
+        return;
+    }
+    if (parsed.sotBindings.length === dbState.sotBindings.length &&
+        parsed.sotBindings.every((row, i) => {
+            const cur = dbState.sotBindings[i];
+            return (cur.category === row.category &&
+                cur.sotApp === row.sotApp &&
+                cur.mirrorPath === row.mirrorPath &&
+                cur.policy === row.policy &&
+                cur.writer === row.writer);
+        })) {
+        return;
+    }
+    writeSotBindings(db, parsed.sotBindings);
+    logger.info({ count: parsed.sotBindings.length }, "management.md hand-edit applied to settings.sot_bindings");
+}
+/**
+ * Pure reconciler used by the chokidar watcher. Encapsulates the full
+ * (read-file → parse → mutate-DB → re-render) pipeline so unit tests
+ * can exercise every branch without booting chokidar.
+ */
+export async function reconcileManagementMdFromFile(contextDir, db, lockManager, reason = "manual") {
+    const path = getManagementMdPath(contextDir);
+    if (consumeSelfWrite(path)) {
+        logger.debug({ path, reason }, "management.md self-write ignored");
+        return { kind: "noop" };
+    }
+    const parsed = await readAndParseManagementMd(contextDir);
+    if (!parsed)
+        return { kind: "noop" };
+    let outcome = { kind: "applied", failures: 0 };
+    const result = await withManagementMdWriteLock(lockManager, async () => {
+        const lockId = lockManager.getHolder();
+        /* c8 ignore next 4 — held lock guarantees a holder; defensive only. */
+        if (!lockId) {
+            outcome = { kind: "noop" };
+            return;
+        }
+        if (!parsed.ok) {
+            logger.warn({ path, errors: parsed.errors, failureCount: parsed.failures.length }, "management.md hand-edit failed to parse; reverting from DB");
+            for (const e of parsed.errors) {
+                recordManagementParseFailure(db, { reason: e });
+            }
+            for (const f of parsed.failures)
+                recordManagementParseFailure(db, f);
+            await renderAndWriteManagementMd(contextDir, db, {
+                sotBindings: readSotBindings(db),
+                managedTasks: listManagedTasks(db),
+            }, {
+                lockManager,
+                lockId,
+                trigger: "management-registry.watcher.revert",
+            });
+            outcome = { kind: "revert-fatal-parse" };
+            return;
+        }
+        if (parsed.schemaVersion === null) {
+            logger.warn({ path }, "management.md hand-edit lacks schema_version; reverting from DB (run boot to back up v2 layouts)");
+            await renderAndWriteManagementMd(contextDir, db, {
+                sotBindings: readSotBindings(db),
+                managedTasks: listManagedTasks(db),
+            }, {
+                lockManager,
+                lockId,
+                trigger: "management-registry.watcher.v2-revert",
+            });
+            outcome = { kind: "revert-v2" };
+            return;
+        }
+        reconcileSectionAToDb(db, parsed, {
+            sotBindings: readSotBindings(db),
+            managedTasks: listManagedTasks(db),
+        });
+        if (parsed.failures.length > 0) {
+            for (const f of parsed.failures)
+                recordManagementParseFailure(db, f);
+        }
+        else {
+            clearManagementParseFailures(db);
+        }
+        await renderAndWriteManagementMd(contextDir, db, {
+            sotBindings: readSotBindings(db),
+            managedTasks: listManagedTasks(db),
+        }, {
+            lockManager,
+            lockId,
+            trigger: "management-registry.watcher.reconcile",
+            render: {
+                preservedSectionC: parsed.preservedSectionC ?? undefined,
+                preservedFreeProse: parsed.preservedFreeProse,
+            },
+        });
+        outcome = { kind: "applied", failures: parsed.failures.length };
+    });
+    if (!result.ok) {
+        logger.debug({ holder: result.holder, reason }, "management.md watcher: lock contended; will reconcile on next change");
+        return { kind: "lock-contended", holder: result.holder };
+    }
+    return outcome;
+}
+/**
+ * Watch `rules/management.md` for hand-edits and reconcile them against
+ * the DB (§7.2 watch path). Self-writes are ignored. Fatal parse errors
+ * trigger a re-render from the DB; row-level failures are recorded in
+ * `management_parse_failures` and the dashboard surfaces a banner.
+ *
+ * The watcher does NOT mutate `managed_tasks` from the file in P2 — the
+ * mutation surface is the P3 API. A row-count or column divergence is
+ * treated as a hand-edit-revert: log + re-render from DB.
+ */
+/* c8 ignore start — chokidar wrapper; the logic lives in
+   reconcileManagementMdFromFile, which is fully unit-tested. The
+   wrapper itself is only event-binding glue. */
+export function startManagementRegistryWatcher(contextDir, db, options = {}) {
+    const path = getManagementMdPath(contextDir);
+    const lockManager = options.lockManager ?? new InMemoryManagementMdWriteLockManager();
+    const watcher = chokidar.watch(path, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+    });
+    const handle = async (reason) => {
+        try {
+            await reconcileManagementMdFromFile(contextDir, db, lockManager, reason);
+        }
+        catch (err) {
+            logger.error({ err, path, reason }, "management.md watcher handler error");
+        }
+    };
+    watcher.on("change", () => void handle("change"));
+    watcher.on("add", () => void handle("add"));
+    watcher.on("error", (err) => logger.error({ err }, "management.md watcher error"));
+    logger.info({ path }, "management.md watcher started");
+    return {
+        async stop() {
+            await watcher.close();
+            logger.info({ path }, "management.md watcher stopped");
+        },
+    };
+}
+/* c8 ignore stop */
+// ── policy-files.ts compatibility check (P2 acceptance gate) ───────────────
+/**
+ * §0.2 — `rules/management.md` is the first wildcard ref in
+ * `policy-files.ts`'s registry. The P2 plan calls out a verification
+ * gate: "Verify `policy-files.ts` wildcard ref still loads the v3 file
+ * unchanged." This helper is exposed so the boot path (and tests)
+ * can sanity-check the file is reachable and below the per-file cap.
+ *
+ * Returns `null` when the file is missing — boot is responsible for
+ * creating it. `tooLarge: true` flags a byte count above
+ * `POLICY_FILE_MAX_BYTES` (32 KB) so prompt assembly skipping the file
+ * (a silent failure mode) gets a loud diagnostic instead.
+ */
+export function verifyManagementMdLoadable(contextDir, policyFileMaxBytes) {
+    const path = join(contextDir, RELATIVE_PATH);
+    if (!existsSync(path))
+        return { ok: false, reason: "missing" };
+    const body = readFileSync(path, "utf-8");
+    const bytes = Buffer.byteLength(body, "utf-8");
+    if (bytes > policyFileMaxBytes) {
+        return {
+            ok: false,
+            reason: `exceeds policy-file cap (${bytes} > ${policyFileMaxBytes})`,
+        };
+    }
+    return { ok: true, bytes };
+}
+//# sourceMappingURL=management-registry.js.map