@aitne/daemon 0.1.0

package/dist/api/routes/context.js

@@ -0,0 +1,1765 @@
+import { Hono } from "hono";
+import { readFileSync, existsSync, statSync, readdirSync, unlinkSync, realpathSync, lstatSync, readlinkSync, } from "node:fs";
+import { basename, join, dirname, resolve, relative, isAbsolute } from "node:path";
+import { writeFileAtomically } from "../../core/atomic-write.js";
+import { contextPutSchema, contextPatchSchema, getAgentDayDateStr, localDateStr, nowInTimezone, } from "@aitne/shared";
+import { getContextDir } from "../../config.js";
+import { getDegradedMode } from "../../db/runtime-state.js";
+import { InMemoryTodayWriteLockManager, getTodayWriteLockTimeoutMs, } from "../../core/today-write-lock.js";
+import { InMemoryRoadmapWriteLockManager, getRoadmapWriteLockTimeoutMs, } from "../../core/roadmap-write-lock.js";
+import { CONTEXT_BASE_FILE_STEMS, CONTEXT_FILE_EXTENSIONS, } from "../../core/context-paths.js";
+import { REPAIRABLE_STUB_TARGETS, buildContextHealthReport, normalizeRepairStubPath, } from "../../core/context-health.js";
+import { validateContextFileFrontmatter } from "../../core/context-frontmatter.js";
+import { classifyContextWriteStaleness } from "../../core/context-staleness.js";
+import { resolveTemplatesRoot } from "../../core/skeleton.js";
+import { parseCustomRoutineSpec, } from "../../core/custom-routine-scheduler.js";
+import { normalizeRoadmapForWrite, validateRoadmap, validateRoadmapTransition, } from "../../core/roadmap-validate.js";
+import { isValidYmd, } from "../../core/roadmap-horizon.js";
+import { extractRoadmapIds, generateRoadmapId, RoadmapIdGenerationError, } from "../../core/roadmap-ids.js";
+import { buildTodayAgentPlanMetadata, extractTodayAgentPlanRows, extractTodayDate, readTodayAgentPlanMetadata, } from "../../core/today-agent-plan.js";
+import { createLogger } from "../../logging.js";
+import { readJsonBody } from "../json-body.js";
+const logger = createLogger("context-api");
+const CONTEXT_BASE_FILE_STEM_SET = new Set(CONTEXT_BASE_FILE_STEMS);
+function resolveContextTarget(userPath) {
+    for (const ext of CONTEXT_FILE_EXTENSIONS) {
+        if (userPath.endsWith(ext)) {
+            return { base: userPath.slice(0, -ext.length), ext };
+        }
+    }
+    if (CONTEXT_BASE_FILE_STEM_SET.has(userPath)) {
+        return { base: userPath, ext: ".base" };
+    }
+    return { base: userPath, ext: ".md" };
+}
+function normalizeContextPath(userPath) {
+    return resolveContextTarget(userPath).base;
+}
+/**
+ * Subpath prefixes inside contextDir that the API never exposes.
+ * Relative paths from `path.relative` never contain a trailing slash for
+ * the leaf element, so we match on "<name>" exactly OR "<name>/" prefix.
+ *
+ *  - `.git` — local repo artifacts the daemon must not touch
+ *  - `.DS_Store` — macOS filesystem cruft
+ *  - `.obsidian` — Obsidian's own state directory
+ *
+ * `.obsidian` stays denied in every mode. `vaultMode="obsidian"` means the
+ * directory may exist on disk and should be preserved by the daemon, not that
+ * the agent may read or edit Obsidian's workspace state through this API.
+ */
+const DENIED_SUBPATH_ROOTS = [".git", ".DS_Store", ".obsidian"];
+function isDeniedPath(relativePath) {
+    for (const root of DENIED_SUBPATH_ROOTS) {
+        if (relativePath === root || relativePath.startsWith(`${root}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function escapesBase(base, candidate) {
+    const rel = relative(base, candidate);
+    return rel.startsWith("..") || isAbsolute(rel);
+}
+function resolveRealPathBestEffort(path, seen = new Set()) {
+    const abs = resolve(path);
+    try {
+        const stat = lstatSync(abs);
+        if (stat.isSymbolicLink()) {
+            if (seen.has(abs))
+                return null;
+            seen.add(abs);
+            const target = readlinkSync(abs);
+            return resolveRealPathBestEffort(isAbsolute(target) ? target : resolve(dirname(abs), target), seen);
+        }
+        return realpathSync(abs);
+    }
+    catch {
+        const parent = dirname(abs);
+        if (parent === abs)
+            return abs;
+        const parentReal = resolveRealPathBestEffort(parent, seen);
+        return parentReal ? resolve(parentReal, basename(abs)) : null;
+    }
+}
+/**
+ * Resolve a user-supplied path safely within contextDir.
+ * Accepts paths with or without the trailing `.md` / `.base` extension.
+ * Returns null if the resolved path escapes contextDir (path traversal),
+ * targets a reserved `.base` stem with the wrong extension, or is on the
+ * deny list.
+ */
+function safePath(contextDir, userPath) {
+    const { base, ext } = resolveContextTarget(userPath);
+    if (base === "projects/_active" && ext !== ".base") {
+        logger.warn({ userPath, base, ext }, "Base file requested with wrong extension");
+        return null;
+    }
+    const resolved = resolve(contextDir, `${base}${ext}`);
+    const rel = relative(contextDir, resolved);
+    // Reject if path escapes contextDir (starts with .. or is absolute)
+    if (escapesBase(contextDir, resolved)) {
+        logger.warn({ userPath, resolved }, "Path traversal rejected");
+        return null;
+    }
+    if (isDeniedPath(rel)) {
+        logger.warn({ userPath, resolved }, "Denied subpath rejected");
+        return null;
+    }
+    const contextReal = resolveRealPathBestEffort(contextDir);
+    const resolvedReal = resolveRealPathBestEffort(resolved);
+    if (!contextReal || !resolvedReal) {
+        logger.warn({ userPath, resolved }, "Realpath resolution rejected");
+        return null;
+    }
+    if (escapesBase(contextReal, resolvedReal)) {
+        logger.warn({ userPath, resolved, resolvedReal }, "Symlink traversal rejected");
+        return null;
+    }
+    const realRel = relative(contextReal, resolvedReal);
+    if (isDeniedPath(realRel)) {
+        logger.warn({ userPath, resolved, resolvedReal }, "Denied realpath rejected");
+        return null;
+    }
+    return resolved;
+}
+// B-007 §5.1 — write-permission whitelist for the new layout.
+const CONTEXT_WRITE_PERMISSIONS = {
+    // Top-level survivors.
+    today: ["PUT", "PATCH"],
+    yesterday: ["PUT", "PATCH"],
+    roadmap: ["PUT", "PATCH"],
+    _index: ["PUT", "PATCH"],
+    "context-index": ["PUT", "PATCH"],
+    // user/* covers fixed area files AND the §5.5 growth pattern
+    // (e.g. `user/health/sleep-log.md` after an area promotion).
+    "user/*": ["PUT", "PATCH"],
+    // Natural-language rulebooks — §5.8.
+    "rules/_index": ["PUT", "PATCH"],
+    // DELETE intentionally omitted. Policy files under `rules/policies/`
+    // use `status: removed` in lieu of physical deletion so the captured
+    // history (origin DM, why, linked routine) survives. See
+    // MANAGEMENT-POLICY-CAPTURE-PLAN.md §4.6 / §5.1.
+    "rules/*": ["PUT", "PATCH"],
+    "routines/_index": ["PUT", "PATCH"],
+    "routines/*": ["PUT", "PATCH"],
+    // B-007 §5.8 Q3 — custom routines support DELETE so the agent can
+    // retire a routine when the user asks via DM. The scheduler re-reads
+    // the directory via `onCustomRoutinesChanged` and unregisters the
+    // cron job on the next reload pass.
+    "routines/custom/*": ["PUT", "PATCH", "DELETE"],
+    // Projects (`.base` permitted via CONTEXT_FILE_EXTENSIONS).
+    "projects/_index": ["PUT", "PATCH"],
+    "projects/_active": ["PUT"],
+    "projects/*": ["PUT", "PATCH"],
+    // Lightweight registry for watched git repos that are not promoted to a
+    // full project page.
+    // @deprecated Pre-cutover layout (see docs/design/appendices/unified-repositories.md);
+    // retained for transitional reads of legacy files. New writes route to
+    // `git/<slug>/{overview,journal/<YYYY-MM-DD>}`.
+    "git-repos/*": ["PUT", "PATCH"],
+    // Unified repositories — per-repo project overview + per-day journal.
+    // The two specific patterns below carry write permission; arbitrary
+    // paths under `git/` are NOT writable to keep the layout disciplined.
+    // See docs/design/appendices/unified-repositories.md §4.5.
+    "git/{slug}/overview": ["PUT", "PATCH"],
+    "git/{slug}/journal/{date}": ["PUT", "PATCH"],
+    // Journal & reviews.
+    "daily/*": ["PUT", "PATCH"],
+    "weekly/*": ["PUT", "PATCH"],
+    "monthly/*": ["PUT", "PATCH"],
+    // Dossiers + inbox + agent self-areas.
+    "dossiers/_index": ["PUT", "PATCH"],
+    "dossiers/*": ["PUT", "PATCH"],
+    // B-007 §5.9 Step 4 / §5.3 — morning routine triages each inbox file and
+    // moves the original to `agent/scratch/inbox-YYYY-MM-DD-*.md`. Both sides
+    // of the move need DELETE: inbox for the post-triage cleanup, scratch for
+    // the eventual 48h TTL retention sweep (§6.5).
+    "inbox/*": ["PUT", "PATCH", "DELETE"],
+    "agent/journal": ["PUT", "PATCH"],
+    "agent/scratch/*": ["PUT", "PATCH", "DELETE"],
+};
+/**
+ * Paths where PUT is only allowed when the file does not yet exist.
+ * Subsequent writes must go through PATCH (append). This enforces the
+ * append-only contract at the API level rather than relying on prompt
+ * compliance alone.
+ */
+const CREATE_ONLY_PUT = new Set(["agent/journal"]);
+/**
+ * Slug regex shared by `{slug}` and `{date}` placeholders. Matches the
+ * sanitized output of `deriveSlug` (a-z, 0-9, dot, underscore, dash) and
+ * `YYYY-MM-DD` date strings without further validation — the route
+ * handler does the canonical date validation when it parses the URL.
+ */
+const PLACEHOLDER_SEGMENT_RE = /^[a-z0-9._-]+$/;
+function patternToRegex(pattern) {
+    // Escape regex metachars except the placeholder syntax we control.
+    const escaped = pattern.replace(/[.+^$()|\\]/g, "\\$&");
+    // `{name}` → one allowed segment.
+    const withSegments = escaped.replace(/\\?\{[^}]+\\?\}/g, "[a-z0-9._-]+");
+    // `/*` at end → exactly one trailing segment.
+    const withTail = withSegments.replace(/\/\*$/, "/[^/]+");
+    return new RegExp("^" + withTail + "$");
+}
+function isWriteAllowed(path, method) {
+    // Check exact match first
+    if (CONTEXT_WRITE_PERMISSIONS[path]?.includes(method))
+        return true;
+    // Check wildcard patterns
+    for (const [pattern, methods] of Object.entries(CONTEXT_WRITE_PERMISSIONS)) {
+        if (!methods.includes(method))
+            continue;
+        if (pattern.endsWith("/*")) {
+            const prefix = pattern.slice(0, -2);
+            if (path.startsWith(prefix + "/")) {
+                return true;
+            }
+        }
+        if (pattern.includes("{")) {
+            if (patternToRegex(pattern).test(path)) {
+                // Defense-in-depth: each replaced placeholder must match the
+                // sanitized form. The regex already enforces that, but we
+                // double-check the character set explicitly so a future
+                // pattern with `{slug}` mid-string can't drift.
+                const segments = path.split("/");
+                const patternSegments = pattern.split("/");
+                if (segments.length !== patternSegments.length)
+                    continue;
+                let allValid = true;
+                for (let i = 0; i < segments.length; i++) {
+                    const lit = patternSegments[i];
+                    if (lit.startsWith("{") && lit.endsWith("}")) {
+                        if (!PLACEHOLDER_SEGMENT_RE.test(segments[i])) {
+                            allValid = false;
+                            break;
+                        }
+                    }
+                    else if (lit !== segments[i]) {
+                        allValid = false;
+                        break;
+                    }
+                }
+                if (allValid)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Determine if a context file change should trigger a prompt context
+ * refresh consideration. The staleness classifier decides whether the
+ * matching write is loud enough to invalidate active DM sessions.
+ *
+ * B-007 §5.1 — user/profile.md is refreshed on PUT only (setup writes
+ * the full file) but NOT on PATCH (SignalDetector appends to Raw Signals
+ * frequently — refreshing on every append would thrash the owner session).
+ *
+ * The setup.initial PUT fires this, but it does NOT destroy the in-flight
+ * setup conversation — the `onPromptContextChanged` handler in index.ts
+ * skips `markActiveDmSessionsStale` while `currentSetupMode` is active.
+ */
+function shouldRefreshPromptContext(path, method) {
+    if (path === "today" ||
+        path === "roadmap" ||
+        path === "context-index") {
+        return true;
+    }
+    // B-007 — any rules/*.md file feeds the policy-files injection hub, so
+    // edits to any of them should invalidate the owner-session prompt cache.
+    // Routine rulebooks (`routines/*.md`) similarly drive task-flow prompts.
+    if (path.startsWith("rules/") || path.startsWith("routines/")) {
+        return true;
+    }
+    if (path.startsWith("dossiers/")) {
+        return true;
+    }
+    if (path === "user/profile" && method === "PUT") {
+        return true;
+    }
+    return false;
+}
+function notifyPromptContextChanged(deps, path, reason, input) {
+    const classification = classifyContextWriteStaleness(input);
+    deps.onPromptContextChanged?.(path, reason, classification.tier, {
+        tierReason: classification.tierReason,
+    });
+    // STAGE-C-DM-FRESHNESS-PLAN §Task 4 — record the staleness tier in
+    // `agent_actions` so the dashboard's `dm_freshness_metrics` view can
+    // count loud vs. quiet writes that landed within a DM session's
+    // lifetime. Best-effort: a failure here must not break the write.
+    try {
+        deps.db
+            .prepare(`INSERT INTO agent_actions (action_type, trigger, result, detail, started_at, completed_at)
+         VALUES ('context_write', 'reactive', 'success', json(?), datetime('now'), datetime('now'))`)
+            .run(JSON.stringify({
+            path,
+            method: input.method,
+            tier: classification.tier,
+            tierReason: classification.tierReason,
+            reason,
+        }));
+    }
+    catch (err) {
+        logger.warn({ err, path, method: input.method }, "Failed to record context_write agent_actions row (Stage C metrics)");
+    }
+}
+/**
+ * Normalize a section name for matching:
+ * lowercase, spaces → underscores, strip leading ##
+ */
+function normalizeSection(name) {
+    return name
+        .replace(/^#+\s*/, "")
+        .toLowerCase()
+        .replace(/\s+/g, "_");
+}
+/**
+ * Find a section in markdown content and return its boundaries.
+ * Returns [startOfBody, endOfBody] where body is between this ## and next ##.
+ */
+function findSection(content, sectionName) {
+    const normalized = normalizeSection(sectionName);
+    const lines = content.split("\n");
+    let sectionStart = -1;
+    let headerEnd = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith("## ")) {
+            const lineNormalized = normalizeSection(lines[i]);
+            if (lineNormalized === normalized) {
+                sectionStart = i;
+                const lineStart = sumLength(lines, i);
+                const nlPos = content.indexOf("\n", lineStart);
+                // Handle file ending without trailing newline
+                headerEnd = nlPos === -1 ? content.length : nlPos + 1;
+                break;
+            }
+        }
+    }
+    if (sectionStart === -1)
+        return null;
+    // Find end: next ## header or EOF
+    let sectionEnd = content.length;
+    for (let i = sectionStart + 1; i < lines.length; i++) {
+        if (lines[i].startsWith("## ")) {
+            sectionEnd = sumLength(lines, i);
+            break;
+        }
+    }
+    return { start: headerEnd, end: sectionEnd, headerEnd };
+}
+function sumLength(lines, upToIndex) {
+    let len = 0;
+    for (let i = 0; i < upToIndex; i++) {
+        len += lines[i].length + 1; // +1 for \n
+    }
+    return len;
+}
+function getAvailableSections(content) {
+    return content
+        .split("\n")
+        .filter((l) => l.startsWith("## "))
+        .map((l) => normalizeSection(l));
+}
+/**
+ * Parse a timestamp from a bullet entry like `- [2026-04-10 02:32:59] ...`
+ * Returns the timestamp string or null if the line doesn't match.
+ */
+const ENTRY_TIMESTAMP_RE = /^- \[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/;
+function parseEntryTimestamp(line) {
+    const match = ENTRY_TIMESTAMP_RE.exec(line);
+    return match ? match[1] : null;
+}
+/**
+ * Remove entries whose `- [YYYY-MM-DD HH:MM:SS]` timestamp is ≤ cutoff.
+ * Non-matching lines (blank lines, continuation lines) are preserved.
+ * Returns the remaining section body and the count of removed entries.
+ */
+function clearEntriesBefore(sectionBody, cutoff) {
+    const lines = sectionBody.split("\n");
+    const kept = [];
+    let removedCount = 0;
+    let skipContinuation = false;
+    for (const line of lines) {
+        const ts = parseEntryTimestamp(line);
+        if (ts !== null) {
+            // This is a timestamped entry
+            if (ts <= cutoff) {
+                removedCount++;
+                skipContinuation = true;
+                continue;
+            }
+            skipContinuation = false;
+            kept.push(line);
+        }
+        else if (skipContinuation && (line.startsWith("  ") || line.trim() === "")) {
+            // Continuation or trailing blank line of a removed entry
+            continue;
+        }
+        else {
+            skipContinuation = false;
+            kept.push(line);
+        }
+    }
+    return { remaining: kept.join("\n"), removedCount };
+}
+/**
+ * Trim oldest bullet entries (`- ...` lines) from the top of a section
+ * body to keep at most `maxEntries` entries. Non-bullet lines (blank
+ * lines, non-`- ` prefixed lines) are preserved.
+ */
+function trimBulletEntries(body, maxEntries) {
+    const lines = body.split("\n");
+    // Collect indices of bullet entry start lines
+    const bulletIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].startsWith("- ")) {
+            bulletIndices.push(i);
+        }
+    }
+    const excess = bulletIndices.length - maxEntries;
+    if (excess <= 0) {
+        return { body, trimmed: 0 };
+    }
+    // Remove the oldest (topmost) `excess` entries and their continuations.
+    // Also remove blank lines between consecutive removed entries to avoid
+    // orphaned whitespace accumulating over many trim cycles.
+    const removeSet = new Set();
+    for (let i = 0; i < excess; i++) {
+        const start = bulletIndices[i];
+        const end = i + 1 < bulletIndices.length ? bulletIndices[i + 1] : lines.length;
+        for (let j = start; j < end; j++) {
+            if (j === start || lines[j].startsWith("  ") || lines[j].trim() === "") {
+                removeSet.add(j);
+            }
+        }
+    }
+    const kept = lines.filter((_, i) => !removeSet.has(i));
+    return { body: kept.join("\n"), trimmed: excess };
+}
+const SNAPSHOT_DEBOUNCE_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Cap on the JSON body accepted by the Context PUT/PATCH endpoints.
+ *
+ * Real context files are well under this — `today.md` is typically
+ * ~10 KB at the busiest point of the day, `roadmap.md` runs ~50 KB,
+ * project pages ~50 KB, and `agent/journal.md` is bounded by the
+ * retention rollup. 1 MB leaves >10x headroom for legitimate writes
+ * while preventing a runaway-payload denial-of-service:
+ *
+ *   - The agent could otherwise be tricked (prompt injection from a
+ *     poisoned email or Obsidian note) into PATCHing a multi-megabyte
+ *     payload, and each PATCH writes a snapshot row in
+ *     `md_file_snapshots`. Snapshots are pruned at 30 days, so a
+ *     burst of large writes can balloon the DB before retention
+ *     catches up.
+ *
+ *   - 1 MB is an order of magnitude smaller than the attachment route's
+ *     25 MB cap; context files have no legitimate need to be that big.
+ *
+ * Only PUT/PATCH against the wildcard route apply this cap. Smaller
+ * structured endpoints (lock, archive-today, repair/stub) use
+ * `readOptionalJsonBody` whose payloads are tiny by construction.
+ */
+const CONTEXT_BODY_MAX_BYTES = 1024 * 1024;
+export function createContextRoutes(deps) {
+    const app = new Hono();
+    const { db, config, writeTracker } = deps;
+    // Resolve the context directory at request time rather than closing over
+    // the startup value. `/api/setup/migrate-context` mutates `config` in
+    // memory after a successful move, and the Context API must immediately
+    // follow the new primary-vault path without requiring a daemon restart.
+    //
+    // Intentionally omit `db` here: degraded mode is handled by the 503
+    // middleware below, so once a request reaches a handler we want the
+    // actual current target path, never the legacy fallback.
+    const getCurrentContextDir = () => getContextDir(config);
+    /**
+     * Management Mode degraded-mode gate (plan §5.4).
+     * When the primary vault is unreachable, refuse BOTH reads and writes
+     * with 503 so the agent does not read or write a stale fallback
+     * location. Checked per-request so lifting degraded mode in the health
+     * probe takes effect without restart. The lock endpoints under
+     * `/context/lock/*` also participate: acquiring a lock during degraded
+     * mode would leave the lock held with no way to write, so we gate them
+     * too.
+     */
+    app.use("/context/*", async (c, next) => {
+        const state = getDegradedMode(db);
+        if (state) {
+            return c.json({
+                error: "primary_vault_unreachable",
+                reason: state.reason,
+                path: state.path,
+                since: state.since,
+            }, 503);
+        }
+        // Phase 2 — global context-write gate engaged during a
+        // /api/setup/migrate-context run. Refuses WRITES (not reads)
+        // because reads against the still-intact source are safe; the
+        // migration endpoint blocks writes so no handler races the move.
+        const writeMethods = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+        if (deps.contextWriteGate?.isEngaged() && writeMethods.has(c.req.method)) {
+            const gateState = deps.contextWriteGate.getState();
+            return c.json({
+                error: "migration_in_progress",
+                reason: gateState.reason,
+                since: gateState.since,
+            }, 503);
+        }
+        await next();
+    });
+    const morningRoutineLock = deps.morningRoutineLock ??
+        new InMemoryTodayWriteLockManager(getTodayWriteLockTimeoutMs(config.executeTimeoutMinutes));
+    const roadmapWriteLock = deps.roadmapWriteLock ??
+        new InMemoryRoadmapWriteLockManager(getRoadmapWriteLockTimeoutMs(config.executeTimeoutMinutes));
+    // Per-instance state (not shared across tests)
+    const lastSnapshotTimes = new Map();
+    // Mutex for serialized writes
+    let writeLock = Promise.resolve();
+    function withWriteLock(fn) {
+        const prev = writeLock;
+        let resolve;
+        writeLock = new Promise((r) => {
+            resolve = r;
+        });
+        return prev.then(() => {
+            try {
+                return fn();
+            }
+            finally {
+                resolve();
+            }
+        });
+    }
+    function saveSnapshot(filePath, content, trigger, force = false, sessionId) {
+        const now = Date.now();
+        const lastTime = lastSnapshotTimes.get(filePath) ?? 0;
+        if (!force && now - lastTime < SNAPSHOT_DEBOUNCE_MS) {
+            return null;
+        }
+        const result = db
+            .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, ?, ?)")
+            .run(filePath, content, trigger, sessionId ?? null);
+        lastSnapshotTimes.set(filePath, now);
+        return Number(result.lastInsertRowid);
+    }
+    function isRoadmapValidationDisabled(path, headerValue) {
+        return path === "roadmap" && headerValue?.toLowerCase() === "off";
+    }
+    function logRoadmapValidationBypass(c, method, path) {
+        logger.warn({
+            path,
+            method,
+            sessionId: c.req.header("X-Session-Id") ?? null,
+            caller: c.req.header("X-Caller") ??
+                c.req.header("X-Agent-Caller") ??
+                c.req.header("User-Agent") ??
+                null,
+            route: c.req.path,
+        }, "Roadmap validation bypassed by X-Roadmap-Validation: off");
+    }
+    function roadmapDefaultLongTermPlanSource(c) {
+        const caller = (c.req.header("X-Caller") ??
+            c.req.header("X-Agent-Caller") ??
+            "").toLowerCase();
+        return caller.includes("dashboard") ? "dashboard" : "manual";
+    }
+    async function readOptionalJsonBody(c) {
+        const raw = await c.req.text();
+        if (raw.trim() === "")
+            return { ok: true, body: {} };
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return {
+                    ok: false,
+                    response: c.json({
+                        error: "validation_error",
+                        message: "JSON body must be an object.",
+                    }, 400),
+                };
+            }
+            return { ok: true, body: parsed };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            logger.warn({ path: c.req.path, method: c.req.method, detail }, "Request rejected — body is not valid JSON");
+            return {
+                ok: false,
+                response: c.json({ error: "invalid_json_body", message: detail }, 400),
+            };
+        }
+    }
+    // === Routes registered BEFORE wildcards (Hono matches in registration order) ===
+    // POST /context/lock/morning-routine — Acquire exclusive lock
+    app.post("/context/lock/morning-routine", (c) => {
+        const result = morningRoutineLock.acquire();
+        if (!result.ok) {
+            return c.json({ error: "lock_held", holder: result.holder }, 409);
+        }
+        return c.json({ status: "acquired", lockId: result.lockId });
+    });
+    // DELETE /context/lock/morning-routine — Release exclusive lock
+    app.delete("/context/lock/morning-routine", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const lockId = body.lockId;
+        if (lockId && morningRoutineLock.release(lockId)) {
+            return c.json({ status: "released" });
+        }
+        return c.json({ error: "lock_not_held" }, 400);
+    });
+    // POST /context/lock/roadmap — Acquire exclusive roadmap write lock
+    // Dispatcher auto-acquires this for `routine.roadmap_refresh`; other
+    // flows (DM handler via the roadmap skill, evening sweeper) may
+    // acquire it manually. See ROADMAP-REDESIGN.md §3.6.
+    app.post("/context/lock/roadmap", (c) => {
+        const result = roadmapWriteLock.acquire();
+        if (!result.ok) {
+            return c.json({ error: "roadmap_write_lock_held", holder: result.holder }, 409);
+        }
+        return c.json({ status: "acquired", lockId: result.lockId });
+    });
+    // DELETE /context/lock/roadmap — Release the roadmap write lock
+    app.delete("/context/lock/roadmap", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const lockId = body.lockId;
+        if (lockId && roadmapWriteLock.release(lockId)) {
+            return c.json({ status: "released" });
+        }
+        return c.json({ error: "lock_not_held" }, 400);
+    });
+    // POST /context/roadmap/id — Mint a stable daemon-owned roadmap entry id.
+    app.post("/context/roadmap/id", async (c) => {
+        if (roadmapWriteLock.getHolder()) {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!roadmapWriteLock.isHeldBy(lockId)) {
+                logger.info({ path: "roadmap" }, "Roadmap id mint rejected — roadmap write lock held");
+                return c.json({ error: "roadmap_write_lock_held" }, 409);
+            }
+        }
+        const parsedBody = await readOptionalJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const requestedDate = parsedBody.body.creationDate ?? parsedBody.body.sourceDate;
+        const creationDate = typeof requestedDate === "string"
+            ? requestedDate
+            : localDateStr(new Date(), config.timezone || undefined);
+        if (!isValidYmd(creationDate)) {
+            return c.json({
+                error: "validation_error",
+                message: "creationDate must be YYYY-MM-DD.",
+            }, 400);
+        }
+        return withWriteLock(() => {
+            const contextDir = getCurrentContextDir();
+            const fullPath = safePath(contextDir, "roadmap");
+            if (!fullPath) {
+                return c.json({ error: "invalid_path", path: "roadmap" }, 400);
+            }
+            const content = existsSync(fullPath)
+                ? readFileSync(fullPath, "utf-8")
+                : "";
+            const existingIds = extractRoadmapIds(content).map((ref) => ref.id);
+            try {
+                return c.json({
+                    id: generateRoadmapId({
+                        creationDate,
+                        existingIds,
+                        randomBytes: deps.roadmapIdRandomBytes,
+                    }),
+                });
+            }
+            catch (err) {
+                if (err instanceof RoadmapIdGenerationError) {
+                    return c.json({ error: "roadmap_id_generation_failed" }, 503);
+                }
+                throw err;
+            }
+        });
+    });
+    // POST /context/archive-today — B-007 §5.9 day rotation.
+    // Before Phase 1 this copied today.md to `schedule/YYYY-MM-DD.md`; that
+    // mechanical archive has been retired (the synthesized `daily/YYYY-MM-DD.md`
+    // is now written by the morning routine). The endpoint is kept as the
+    // agent-triggered rotation that renames `today.md → yesterday.md` and
+    // returns the previous date so the agent can write the new `today.md`
+    // in the same flow.
+    app.post("/context/archive-today", (c) => {
+        return withWriteLock(() => {
+            const contextDir = getCurrentContextDir();
+            const todayPath = join(contextDir, "today.md");
+            if (!existsSync(todayPath)) {
+                return c.json({ error: "not_found", path: "today" }, 404);
+            }
+            const content = readFileSync(todayPath, "utf-8");
+            const dateStr = content.match(/^#.*(\d{4}-\d{2}-\d{2})/)?.[1] ??
+                localDateStr(new Date());
+            const yesterdayPath = join(contextDir, "yesterday.md");
+            // Atomic write through O_NOFOLLOW + rename so a symlink swap at
+            // `yesterday.md` between request validation and the write cannot
+            // redirect the rotation into an attacker-controlled path. The
+            // legacy `copyFileSync` would silently follow such a symlink.
+            writeFileAtomically(yesterdayPath, content);
+            saveSnapshot("today", content, "rotate-to-yesterday", true);
+            return c.json({
+                status: "archived",
+                archivePath: "yesterday.md",
+                rotatedFrom: dateStr,
+            });
+        });
+    });
+    // POST /context/restore-snapshot/:id — restore a prior md_file_snapshots
+    // row back onto disk. The current on-disk file (if any) is snapshotted
+    // first so the restore itself is reversible from the Knowledge page.
+    app.post("/context/restore-snapshot/:id", (c) => {
+        const id = Number(c.req.param("id"));
+        if (!Number.isSafeInteger(id) || id <= 0) {
+            return c.json({ error: "invalid_id" }, 400);
+        }
+        const row = db
+            .prepare("SELECT id, file_path, content FROM md_file_snapshots WHERE id = ?")
+            .get(id);
+        if (!row) {
+            return c.json({ error: "not_found" }, 404);
+        }
+        const target = resolveContextTarget(row.file_path);
+        const path = target.base;
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, row.file_path);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path }, 400);
+        }
+        if (!isWriteAllowed(path, "PUT") && !isWriteAllowed(path, "PATCH")) {
+            logger.warn({ path, method: "RESTORE" }, "Snapshot restore forbidden");
+            return c.json({ error: "forbidden", path, method: "RESTORE" }, 403);
+        }
+        if (morningRoutineLock.getHolder() && path === "today") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!morningRoutineLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Snapshot restore rejected — morning routine lock held");
+                return c.json({ error: "morning_routine_lock_held" }, 409);
+            }
+        }
+        if (roadmapWriteLock.getHolder() && path === "roadmap") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!roadmapWriteLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Snapshot restore rejected — roadmap write lock held");
+                return c.json({ error: "roadmap_write_lock_held" }, 409);
+            }
+        }
+        const contentError = validateContextContent(target, row.content, {
+            skipFrontmatterValidation: true,
+        });
+        if (contentError) {
+            return c.json({ error: "validation_error", message: contentError.message }, contentError.status);
+        }
+        return withWriteLock(() => {
+            let backupSnapshotId = null;
+            if (existsSync(fullPath)) {
+                const current = readFileSync(fullPath, "utf-8");
+                backupSnapshotId = saveSnapshot(path, current, "api_restore_snapshot", true);
+            }
+            // writeFileAtomically handles parent-dir creation, refuses to
+            // follow a symlink at the destination, and renames into place.
+            writeFileAtomically(fullPath, row.content);
+            writeTracker?.markWriting(fullPath, row.content);
+            if (shouldRefreshPromptContext(path, "PUT")) {
+                notifyPromptContextChanged(deps, path, `context_restore_snapshot:${path}`, { path, method: "RESTORE" });
+            }
+            if (path.startsWith("routines/custom/")) {
+                deps.onCustomRoutinesChanged?.();
+            }
+            const writtenStat = statSync(fullPath);
+            logger.info({
+                path,
+                method: "RESTORE",
+                restoredFromSnapshotId: id,
+                backupSnapshotId: backupSnapshotId ?? undefined,
+            }, "Context snapshot restored");
+            return c.json({
+                status: "restored",
+                path,
+                restoredFromSnapshotId: id,
+                backupSnapshotId,
+                lastModified: writtenStat.mtime.toISOString(),
+            });
+        });
+    });
+    // GET /context/list/:dir — List files in directory
+    app.get("/context/list/:dir", (c) => {
+        const dir = c.req.param("dir");
+        // B-007 §5.1 — canonical listable directories.
+        const allowedDirs = [
+            "projects",
+            "weekly",
+            "monthly",
+            "daily",
+            "user",
+            "rules",
+            "routines",
+            "dossiers",
+            "git",
+            "git-repos",
+            "inbox",
+        ];
+        if (!allowedDirs.includes(dir)) {
+            return c.json({ error: "invalid_directory", allowed: allowedDirs }, 400);
+        }
+        const contextDir = getCurrentContextDir();
+        const dirPath = join(contextDir, dir);
+        if (!existsSync(dirPath)) {
+            return c.json({ files: [] });
+        }
+        const files = readdirSync(dirPath)
+            .filter((f) => CONTEXT_FILE_EXTENSIONS.some((ext) => f.endsWith(ext)))
+            .map((f) => {
+            const stat = statSync(join(dirPath, f));
+            return { name: f, lastModified: stat.mtime.toISOString() };
+        });
+        // B-007 §5.8 Q3 — surface custom routines so the dashboard routines
+        // editor sees them alongside the built-ins. `routines/custom/` is the
+        // only nested directory we need to flatten; other listable dirs are
+        // flat by design (§5.1).
+        if (dir === "routines") {
+            const customDir = join(dirPath, "custom");
+            if (existsSync(customDir)) {
+                for (const f of readdirSync(customDir)) {
+                    if (!CONTEXT_FILE_EXTENSIONS.some((ext) => f.endsWith(ext)))
+                        continue;
+                    const stat = statSync(join(customDir, f));
+                    files.push({
+                        name: `custom/${f}`,
+                        lastModified: stat.mtime.toISOString(),
+                    });
+                }
+            }
+        }
+        // Unified repositories layout (`git/<slug>/overview.md` +
+        // `git/<slug>/journal/<YYYY-MM-DD>.md`) — surface every per-repo file
+        // under the `git` listing so the Knowledge page tree shows them.
+        // Without this the listing only contains files directly under `git/`,
+        // and the per-slug subdirectories silently drop off the dashboard.
+        // Mirrors the `routines/custom/` flatten above.
+        if (dir === "git") {
+            for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const slug = entry.name;
+                const slugDir = join(dirPath, slug);
+                for (const f of readdirSync(slugDir)) {
+                    if (!CONTEXT_FILE_EXTENSIONS.some((ext) => f.endsWith(ext)))
+                        continue;
+                    const stat = statSync(join(slugDir, f));
+                    files.push({
+                        name: `${slug}/${f}`,
+                        lastModified: stat.mtime.toISOString(),
+                    });
+                }
+                const journalDir = join(slugDir, "journal");
+                if (existsSync(journalDir)) {
+                    for (const f of readdirSync(journalDir)) {
+                        if (!CONTEXT_FILE_EXTENSIONS.some((ext) => f.endsWith(ext)))
+                            continue;
+                        const stat = statSync(join(journalDir, f));
+                        files.push({
+                            name: `${slug}/journal/${f}`,
+                            lastModified: stat.mtime.toISOString(),
+                        });
+                    }
+                }
+            }
+        }
+        // MANAGEMENT-POLICY-CAPTURE-PLAN §4.4.1 step 1 — surface policy files
+        // under `rules/policies/` flattened into the `rules` listing so the
+        // `management-policy` skill can use the directory listing as its
+        // source-of-truth (the agent-maintained `_index.md` is only the
+        // convenience snapshot). Mirrors the `routines/custom/` flatten above.
+        if (dir === "rules") {
+            const policiesDir = join(dirPath, "policies");
+            if (existsSync(policiesDir)) {
+                for (const f of readdirSync(policiesDir)) {
+                    if (!CONTEXT_FILE_EXTENSIONS.some((ext) => f.endsWith(ext)))
+                        continue;
+                    const stat = statSync(join(policiesDir, f));
+                    files.push({
+                        name: `policies/${f}`,
+                        lastModified: stat.mtime.toISOString(),
+                    });
+                }
+            }
+        }
+        return c.json({ files });
+    });
+    // GET /context/today/reconciliation — compare open Agent Plan rows with
+    // pending/running schedules for the same local day. This is intentionally
+    // diagnostic only: morning routine may write today.md and register schedules
+    // in separate API calls, so write-time hard failure would create false
+    // conflicts. The endpoint gives operators and future jobs a server-side
+    // reconciliation surface.
+    app.get("/context/today/reconciliation", (c) => {
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, "today");
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path: "today" }, 400);
+        }
+        if (!existsSync(fullPath)) {
+            return c.json({ error: "not_found", path: "today" }, 404);
+        }
+        const content = readFileSync(fullPath, "utf-8");
+        const validationError = validateTodayContent(content);
+        const todayDate = extractTodayDate(content) ??
+            localDateStr(new Date(), config.timezone || undefined);
+        const openRows = extractTodayAgentPlanRows(content).rows.filter((row) => !row.checked);
+        const openRowsWithMetadata = openRows.map((row) => ({
+            row,
+            agentPlan: buildTodayAgentPlanMetadata(todayDate, row),
+        }));
+        const pendingRows = db
+            .prepare(`SELECT id, scheduled_for, task_type, task_description, task_context, status
+           FROM agent_schedule
+          WHERE status IN ('pending', 'running')`)
+            .all();
+        const schedules = pendingRows
+            .map((row) => toTodayScheduleCandidate(row, config.timezone || undefined))
+            .filter((row) => row !== null)
+            .map((row) => ({
+            ...row,
+            agentPlan: readTodayAgentPlanMetadata(row.taskContext),
+        }))
+            .filter((row) => row.agentPlan !== null && row.agentPlan.date === todayDate);
+        const rowMatches = openRowsWithMetadata.map(({ row, agentPlan }) => {
+            const matches = schedules.filter((schedule) => schedule.localDate === todayDate &&
+                schedule.localTime === row.time &&
+                schedule.agentPlan.ref === agentPlan.ref &&
+                schedule.agentPlan.fingerprint === agentPlan.fingerprint &&
+                schedule.agentPlan.category === row.category &&
+                schedule.agentPlan.trigger === row.trigger);
+            return { row, agentPlan, matches };
+        });
+        const rowsWithoutSchedule = rowMatches.filter(({ matches }) => matches.length === 0);
+        const duplicateAgentPlanSchedules = rowMatches.filter(({ matches }) => matches.length > 1);
+        const matchedScheduleIds = new Set();
+        for (const { matches } of rowMatches) {
+            for (const schedule of matches)
+                matchedScheduleIds.add(schedule.id);
+        }
+        const schedulesWithoutRow = schedules.filter((row) => !matchedScheduleIds.has(row.id));
+        const mismatchCount = (rowsWithoutSchedule.length +
+            duplicateAgentPlanSchedules.length +
+            schedulesWithoutRow.length);
+        return c.json({
+            status: validationError
+                ? "invalid_today"
+                : mismatchCount > 0
+                    ? "mismatch"
+                    : "ok",
+            validationError,
+            todayDate,
+            openAgentPlanRows: openRows.length,
+            pendingSchedules: schedules.length,
+            rowsWithoutSchedule: rowsWithoutSchedule.map(({ row, agentPlan }) => ({
+                line: row.line,
+                ref: agentPlan.ref,
+                time: row.time,
+                action: row.action,
+                category: row.category,
+                trigger: row.trigger,
+            })),
+            schedulesWithoutRow: schedulesWithoutRow.map((row) => ({
+                id: row.id,
+                ref: row.agentPlan.ref,
+                localTime: row.localTime,
+                scheduledFor: row.scheduledFor,
+                taskType: row.taskType,
+                status: row.status,
+                description: row.description,
+            })),
+            duplicateAgentPlanSchedules: duplicateAgentPlanSchedules.map(({ row, agentPlan, matches }) => ({
+                line: row.line,
+                ref: agentPlan.ref,
+                time: row.time,
+                action: row.action,
+                scheduleIds: matches.map((match) => match.id),
+            })),
+        });
+    });
+    // GET /context/health — schema drift and missing-file report for the
+    // primary context vault. Registered before the wildcard read route.
+    app.get("/context/health", (c) => {
+        const contextDir = getCurrentContextDir();
+        return c.json(buildContextHealthReport(contextDir));
+    });
+    // POST /context/repair/stub — create a known missing stub from the
+    // templates tree. This is intentionally guarded to a small allow-list;
+    // it is not an arbitrary file creation endpoint.
+    app.post("/context/repair/stub", async (c) => {
+        const parsedBody = await readOptionalJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const rawPath = parsedBody.body.path;
+        if (typeof rawPath !== "string") {
+            return c.json({
+                error: "validation_error",
+                message: "path must be a string.",
+            }, 400);
+        }
+        const normalizedPath = normalizeRepairStubPath(rawPath);
+        if (!normalizedPath || !REPAIRABLE_STUB_TARGETS.has(normalizedPath)) {
+            return c.json({
+                error: "unsupported_stub_target",
+                message: "Only known context stub targets can be repaired.",
+                path: rawPath,
+            }, 400);
+        }
+        const templatesRoot = resolveTemplatesRoot(config.workspaceDir);
+        if (!templatesRoot) {
+            return c.json({
+                error: "templates_unavailable",
+                message: "agent-assets/templates could not be located.",
+            }, 503);
+        }
+        const templatePath = join(templatesRoot, normalizedPath);
+        if (!existsSync(templatePath)) {
+            return c.json({
+                error: "template_not_found",
+                message: `No template exists for ${normalizedPath}.`,
+                path: normalizedPath,
+            }, 404);
+        }
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, normalizedPath);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path: normalizedPath }, 400);
+        }
+        return withWriteLock(() => {
+            if (existsSync(fullPath)) {
+                const existingStat = statSync(fullPath);
+                return c.json({
+                    status: "exists",
+                    path: normalizedPath,
+                    lastModified: existingStat.mtime.toISOString(),
+                });
+            }
+            // Read the template once and write atomically; replaces the
+            // previous copyFileSync, which would have silently followed a
+            // symlink planted at `fullPath` during the TOCTOU window between
+            // safePath validation and the write.
+            const content = readFileSync(templatePath, "utf-8");
+            writeFileAtomically(fullPath, content);
+            writeTracker?.markWriting(fullPath, content);
+            const normalizedBase = normalizeContextPath(normalizedPath);
+            if (shouldRefreshPromptContext(normalizedBase, "PUT")) {
+                notifyPromptContextChanged(deps, normalizedBase, `context_repair_stub:${normalizedBase}`, { path: normalizedBase, method: "REPAIR" });
+            }
+            deps.onIndexableContextChange?.(normalizedPath);
+            const writtenStat = statSync(fullPath);
+            logger.info({ path: normalizedPath, templatePath }, "Context stub repaired from template");
+            return c.json({
+                status: "created",
+                path: normalizedPath,
+                lastModified: writtenStat.mtime.toISOString(),
+            });
+        });
+    });
+    // === Wildcard routes ===
+    // GET /context/* — Read context file
+    app.get("/context/*", (c) => {
+        const rawPath = c.req.path.replace("/api/context/", "");
+        if (!rawPath || rawPath === "list") {
+            return c.json({ error: "path_required" }, 400);
+        }
+        const path = normalizeContextPath(rawPath);
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, rawPath);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path }, 400);
+        }
+        if (!existsSync(fullPath)) {
+            return c.json({ error: "not_found", path }, 404);
+        }
+        const content = readFileSync(fullPath, "utf-8");
+        const stat = statSync(fullPath);
+        // STAGE-C-DM-FRESHNESS-PLAN §Task 4 — record reads of `today` so the
+        // dashboard refetch-hit metric can detect when the agent invokes the
+        // Task 3 directive on a resumed turn. Bounded to `today` reads only
+        // so the agent_actions volume stays small. Best-effort: any logging
+        // failure must not break the read.
+        if (path === "today") {
+            try {
+                deps.db
+                    .prepare(`INSERT INTO agent_actions (action_type, trigger, result, detail, started_at, completed_at)
+             VALUES ('context_read', 'reactive', 'success', json(?), datetime('now'), datetime('now'))`)
+                    .run(JSON.stringify({ path }));
+            }
+            catch (err) {
+                logger.warn({ err, path }, "Failed to record context_read agent_actions row (Stage C metrics)");
+            }
+        }
+        return c.json({
+            content,
+            lastModified: stat.mtime.toISOString(),
+            editable: isWriteAllowed(path, "PUT"),
+        });
+    });
+    // PUT /context/* — Full replace
+    app.put("/context/*", async (c) => {
+        const rawPath = c.req.path.replace("/api/context/", "");
+        const target = resolveContextTarget(rawPath);
+        const path = target.base;
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, rawPath);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path }, 400);
+        }
+        if (!isWriteAllowed(path, "PUT")) {
+            logger.warn({ path, method: "PUT" }, "Context write forbidden");
+            return c.json({ error: "forbidden", path, method: "PUT" }, 403);
+        }
+        // Morning Routine lock: reject writes to today while lock is held
+        if (morningRoutineLock.getHolder() && path === "today") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!morningRoutineLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Context PUT rejected — morning routine lock held");
+                return c.json({ error: "morning_routine_lock_held" }, 409);
+            }
+        }
+        // Roadmap write lock: reject writes to roadmap while another session holds it
+        if (roadmapWriteLock.getHolder() && path === "roadmap") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!roadmapWriteLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Context PUT rejected — roadmap write lock held");
+                return c.json({ error: "roadmap_write_lock_held" }, 409);
+            }
+        }
+        const parsedBody = await readJsonBody(c, { maxBytes: CONTEXT_BODY_MAX_BYTES });
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const parsed = contextPutSchema.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: "validation_error", details: parsed.error }, 400);
+        }
+        const roadmapValidationOff = isRoadmapValidationDisabled(path, c.req.header("X-Roadmap-Validation"));
+        if (roadmapValidationOff) {
+            logRoadmapValidationBypass(c, "PUT", path);
+        }
+        const expectedAgentDay = path === "today"
+            ? getAgentDayDateStr(config.timezone || undefined, config.dayBoundaryHour ?? 4)
+            : undefined;
+        const preflight = prepareContextContentForWrite(target, parsed.data.content, {
+            timezone: config.timezone || undefined,
+            disableRoadmapValidation: roadmapValidationOff,
+            defaultLongTermPlanSource: roadmapDefaultLongTermPlanSource(c),
+            expectedAgentDay,
+        });
+        if (!preflight.ok) {
+            return c.json({
+                error: "validation_error",
+                message: preflight.message,
+                path: preflight.path,
+            }, preflight.status);
+        }
+        const sessionId = c.req.header("X-Session-Id");
+        return withWriteLock(() => {
+            // Append-only files: PUT is only allowed for initial creation.
+            // Once the file exists, all writes must go through PATCH to preserve
+            // the append-only contract. This check MUST be inside withWriteLock
+            // to prevent TOCTOU races where two concurrent PUTs both pass an
+            // outer existsSync check and then sequentially overwrite.
+            if (CREATE_ONLY_PUT.has(path) && existsSync(fullPath)) {
+                logger.warn({ path }, "Context PUT rejected — file exists, use PATCH to append");
+                return c.json({
+                    error: "append_only",
+                    message: `${path} already exists. Use PATCH to append new sections.`,
+                    path,
+                }, 409);
+            }
+            // Optimistic concurrency check: if client supplied expectedMtime,
+            // compare against the current file. On mismatch, return 409 with
+            // the current state so the UI can surface a conflict dialog without
+            // a second round-trip.
+            let snapshotId = null;
+            let contentToWrite = preflight.content;
+            if (existsSync(fullPath)) {
+                const currentStat = statSync(fullPath);
+                const currentMtime = currentStat.mtime.toISOString();
+                const existing = readFileSync(fullPath, "utf-8");
+                if (parsed.data.expectedMtime !== undefined &&
+                    parsed.data.expectedMtime !== currentMtime) {
+                    logger.info({ path, expectedMtime: parsed.data.expectedMtime, currentMtime }, "Context PUT conflict");
+                    return c.json({
+                        error: "conflict",
+                        currentMtime,
+                        currentContent: existing,
+                    }, 409);
+                }
+                const prepared = prepareContextContentForWrite(target, parsed.data.content, {
+                    timezone: config.timezone || undefined,
+                    disableRoadmapValidation: roadmapValidationOff,
+                    previousRoadmapContent: existing,
+                    today: localDateStr(new Date(), config.timezone || undefined),
+                    defaultLongTermPlanSource: roadmapDefaultLongTermPlanSource(c),
+                    expectedAgentDay,
+                });
+                if (!prepared.ok) {
+                    return c.json({
+                        error: "validation_error",
+                        message: prepared.message,
+                        path: prepared.path,
+                    }, prepared.status);
+                }
+                contentToWrite = prepared.content;
+                snapshotId = saveSnapshot(path, existing, "api_put", true, sessionId);
+            }
+            else if (parsed.data.expectedMtime !== undefined) {
+                // Client expected a specific mtime but the file is gone
+                return c.json({
+                    error: "conflict",
+                    currentMtime: "",
+                    currentContent: "",
+                }, 409);
+            }
+            // Symlink-safe atomic write — protects against a TOCTOU swap of
+            // `fullPath` to a symlink between safePath validation and the write.
+            writeFileAtomically(fullPath, contentToWrite);
+            writeTracker?.markWriting(fullPath, contentToWrite);
+            if (shouldRefreshPromptContext(path, "PUT")) {
+                notifyPromptContextChanged(deps, path, `context_put:${path}`, { path, method: "PUT" });
+            }
+            if (path.startsWith("routines/custom/")) {
+                deps.onCustomRoutinesChanged?.();
+            }
+            deps.onIndexableContextChange?.(`${path}${target.ext}`);
+            const writtenStat = statSync(fullPath);
+            logger.info({ path, method: "PUT", bytesWritten: writtenStat.size, snapshotId: snapshotId ?? undefined }, "Context file updated");
+            return c.json({
+                status: "updated",
+                snapshotId: snapshotId ?? 0,
+                lastModified: writtenStat.mtime.toISOString(),
+            });
+        });
+    });
+    // PATCH /context/* — Section operation
+    app.patch("/context/*", async (c) => {
+        const rawPath = c.req.path.replace("/api/context/", "");
+        const target = resolveContextTarget(rawPath);
+        const path = target.base;
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, rawPath);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path }, 400);
+        }
+        if (!isWriteAllowed(path, "PATCH")) {
+            logger.warn({ path, method: "PATCH" }, "Context write forbidden");
+            return c.json({ error: "forbidden", path, method: "PATCH" }, 403);
+        }
+        // Morning Routine lock: reject writes to today while lock is held
+        if (morningRoutineLock.getHolder() && path === "today") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!morningRoutineLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Context PATCH rejected — morning routine lock held");
+                return c.json({ error: "morning_routine_lock_held" }, 409);
+            }
+        }
+        // Roadmap write lock: reject writes to roadmap while another session holds it
+        if (roadmapWriteLock.getHolder() && path === "roadmap") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!roadmapWriteLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Context PATCH rejected — roadmap write lock held");
+                return c.json({ error: "roadmap_write_lock_held" }, 409);
+            }
+        }
+        const parsedBody = await readJsonBody(c, { maxBytes: CONTEXT_BODY_MAX_BYTES });
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const parsed = contextPatchSchema.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ error: "validation_error", details: parsed.error }, 400);
+        }
+        if (target.ext === ".base") {
+            return c.json({
+                error: "unsupported_operation",
+                message: "PATCH is not supported for .base files; use PUT to replace the file.",
+            }, 400);
+        }
+        const { section, mode, content: newContent, cutoff, maxEntries } = parsed.data;
+        const sessionId = c.req.header("X-Session-Id");
+        const roadmapValidationOff = isRoadmapValidationDisabled(path, c.req.header("X-Roadmap-Validation"));
+        if (roadmapValidationOff) {
+            logRoadmapValidationBypass(c, "PATCH", path);
+        }
+        const expectedAgentDay = path === "today"
+            ? getAgentDayDateStr(config.timezone || undefined, config.dayBoundaryHour ?? 4)
+            : undefined;
+        return withWriteLock(() => {
+            if (!existsSync(fullPath)) {
+                return c.json({ error: "not_found", path }, 404);
+            }
+            const fileContent = readFileSync(fullPath, "utf-8");
+            // ── append_to_file: append content to end of file (no section lookup) ──
+            // Designed for agent/journal.md and similar append-only files where
+            // each write adds a new top-level ## section rather than modifying
+            // an existing one. Avoids the hack of targeting the last section's
+            // body and injecting H2 headers inside it.
+            if (mode === "append_to_file") {
+                const separator = fileContent.endsWith("\n") ? "" : "\n";
+                const updated = fileContent + separator + (newContent ?? "") + "\n";
+                const prepared = prepareContextContentForWrite(target, updated, {
+                    timezone: config.timezone || undefined,
+                    disableRoadmapValidation: roadmapValidationOff,
+                    previousRoadmapContent: fileContent,
+                    today: localDateStr(new Date(), config.timezone || undefined),
+                    defaultLongTermPlanSource: roadmapDefaultLongTermPlanSource(c),
+                    allowLegacyToday: path === "today" && isLegacyTodayContent(fileContent),
+                    expectedAgentDay,
+                });
+                if (!prepared.ok) {
+                    return c.json({
+                        error: "validation_error",
+                        message: prepared.message,
+                        path: prepared.path,
+                    }, prepared.status);
+                }
+                saveSnapshot(path, fileContent, "api_patch", false, sessionId);
+                writeFileAtomically(fullPath, prepared.content);
+                writeTracker?.markWriting(fullPath, prepared.content);
+                if (shouldRefreshPromptContext(path, "PATCH")) {
+                    notifyPromptContextChanged(deps, path, `context_patch:${path}`, {
+                        path,
+                        method: "PATCH",
+                        mode,
+                        section,
+                        content: newContent,
+                        previousContent: fileContent,
+                    });
+                }
+                if (path.startsWith("routines/custom/")) {
+                    deps.onCustomRoutinesChanged?.();
+                }
+                deps.onIndexableContextChange?.(`${path}${target.ext}`);
+                logger.info({ path, method: "PATCH", mode }, "Content appended to file");
+                return c.json({ status: "appended" });
+            }
+            // ── Section-based modes: require section lookup ──
+            const sectionBounds = findSection(fileContent, section);
+            if (!sectionBounds) {
+                return c.json({
+                    error: "section_not_found",
+                    section,
+                    availableSections: getAvailableSections(fileContent),
+                }, 400);
+            }
+            let updated;
+            const before = fileContent.slice(0, sectionBounds.start);
+            const after = fileContent.slice(sectionBounds.end);
+            const currentBody = fileContent.slice(sectionBounds.start, sectionBounds.end);
+            let removedCount;
+            let trimmedCount;
+            switch (mode) {
+                case "append": {
+                    // Ensure a single newline separator without destroying existing content
+                    const separator = currentBody.endsWith("\n") ? "" : "\n";
+                    let appendedBody = currentBody + separator + (newContent ?? "") + "\n";
+                    // maxEntries: trim oldest bullet entries from the top
+                    if (maxEntries !== undefined) {
+                        const trimResult = trimBulletEntries(appendedBody, maxEntries);
+                        appendedBody = trimResult.body;
+                        trimmedCount = trimResult.trimmed;
+                    }
+                    updated = before + appendedBody + after;
+                    break;
+                }
+                case "replace":
+                    updated = before + (newContent ?? "") + "\n" + after;
+                    break;
+                case "clear":
+                    updated = before + "\n" + after;
+                    break;
+                case "clear_before": {
+                    // Schema refinements validate format, but defense-in-depth for
+                    // direct API callers that bypass schema validation.
+                    if (!cutoff || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(cutoff)) {
+                        return c.json({
+                            error: "cutoff_required",
+                            message: "clear_before requires cutoff in 'YYYY-MM-DD HH:MM:SS' format (zero-padded)",
+                        }, 400);
+                    }
+                    const clearResult = clearEntriesBefore(currentBody, cutoff);
+                    updated = before + clearResult.remaining + after;
+                    removedCount = clearResult.removedCount;
+                    break;
+                }
+            }
+            const prepared = prepareContextContentForWrite(target, updated, {
+                timezone: config.timezone || undefined,
+                disableRoadmapValidation: roadmapValidationOff,
+                previousRoadmapContent: fileContent,
+                today: localDateStr(new Date(), config.timezone || undefined),
+                defaultLongTermPlanSource: roadmapDefaultLongTermPlanSource(c),
+                allowLegacyToday: path === "today" && isLegacyTodayContent(fileContent),
+                expectedAgentDay,
+            });
+            if (!prepared.ok) {
+                return c.json({
+                    error: "validation_error",
+                    message: prepared.message,
+                    path: prepared.path,
+                }, prepared.status);
+            }
+            // Force snapshot on replace (bypass debounce) to ensure recovery
+            // from accidental overwrites. Other modes use normal debounce.
+            const forceSnapshot = mode === "replace" || mode === "clear" || mode === "clear_before";
+            saveSnapshot(path, fileContent, "api_patch", forceSnapshot, sessionId);
+            writeFileAtomically(fullPath, prepared.content);
+            writeTracker?.markWriting(fullPath, prepared.content);
+            if (shouldRefreshPromptContext(path, "PATCH")) {
+                notifyPromptContextChanged(deps, path, `context_patch:${path}`, {
+                    path,
+                    method: "PATCH",
+                    mode,
+                    section,
+                    content: newContent,
+                    previousContent: fileContent,
+                });
+            }
+            if (path.startsWith("routines/custom/")) {
+                deps.onCustomRoutinesChanged?.();
+            }
+            deps.onIndexableContextChange?.(`${path}${target.ext}`);
+            const resultStatus = mode === "append" ? "appended" : mode === "replace" ? "replaced" : "cleared";
+            logger.info({ path, method: "PATCH", section, mode, removedCount, trimmedCount }, "Context section " + resultStatus);
+            return c.json({ status: resultStatus, removedCount, trimmedCount });
+        });
+    });
+    // DELETE /context/* — File delete (currently limited to `routines/custom/*`
+    // via the write-permission whitelist). B-007 §5.8 Q3: the agent retires a
+    // custom routine after the user confirms. The scheduler listens via
+    // `onCustomRoutinesChanged` and unregisters the cron job on reload.
+    app.delete("/context/*", (c) => {
+        const path = normalizeContextPath(c.req.path.replace("/api/context/", ""));
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, path);
+        if (!fullPath) {
+            return c.json({ error: "invalid_path", path }, 400);
+        }
+        if (!isWriteAllowed(path, "DELETE")) {
+            logger.warn({ path, method: "DELETE" }, "Context delete forbidden");
+            return c.json({ error: "forbidden", path, method: "DELETE" }, 403);
+        }
+        return withWriteLock(() => {
+            if (!existsSync(fullPath)) {
+                return c.json({ error: "not_found", path }, 404);
+            }
+            const existing = readFileSync(fullPath, "utf-8");
+            const snapshotId = saveSnapshot(path, existing, "api_delete", true);
+            unlinkSync(fullPath);
+            if (path.startsWith("routines/custom/")) {
+                deps.onCustomRoutinesChanged?.();
+            }
+            deps.onIndexableContextChange?.(path);
+            logger.info({ path, method: "DELETE", snapshotId: snapshotId ?? undefined }, "Context file deleted");
+            return c.json({ status: "deleted", snapshotId: snapshotId ?? 0 });
+        });
+    });
+    return app;
+}
+function validateContextContent(target, content, options) {
+    if (target.base === "today") {
+        const message = validateTodayContent(content, {
+            allowLegacyToday: options?.allowLegacyToday ?? false,
+            expectedAgentDay: options?.expectedAgentDay,
+        });
+        return message ? { message, status: 400 } : null;
+    }
+    if (target.base === "roadmap") {
+        const result = validateRoadmap(content);
+        if (!result.ok && result.error) {
+            return {
+                message: formatRoadmapValidationError(result.error),
+                status: 400,
+                path: result.error.path,
+            };
+        }
+        return null;
+    }
+    if (target.base.startsWith("routines/custom/")) {
+        const slug = target.base.slice("routines/custom/".length);
+        const result = parseCustomRoutineSpec(slug, content);
+        if (!result.ok) {
+            return {
+                message: explainCustomRoutineValidationError(result.error),
+                status: 400,
+            };
+        }
+        return null;
+    }
+    if (target.base.startsWith("routines/") && target.base !== "routines/_index") {
+        const message = validateBuiltInRoutineRulebook(target.base, content);
+        return message ? { message, status: 400 } : null;
+    }
+    const relativePath = `${target.base}${target.ext}`;
+    if (!options?.skipFrontmatterValidation) {
+        const frontmatterError = validateContextFileFrontmatter(content, relativePath);
+        if (frontmatterError) {
+            return { message: frontmatterError.message, status: 422 };
+        }
+    }
+    if (target.ext !== ".base")
+        return null;
+    const message = validateBaseYamlSyntax(content);
+    return message ? { message, status: 400 } : null;
+}
+const TODAY_REQUIRED_SECTIONS = [
+    "User Schedule",
+    "User Tasks",
+    "Agent Plan",
+    "Agent Notes",
+    "Agent Log",
+    "Handoff",
+];
+const TODAY_H1_RE = /^# \d{4}-\d{2}-\d{2}(?: \([^)]+\))?$/;
+const TODAY_DAY_TYPE_RE = /^> Day type: (Weekday|Weekend) \| Work focus: (on|off) \| Study focus: (on|off) \| Personal focus: (on|off)$/;
+function isLegacyTodayContent(content) {
+    const lines = content.split(/\r?\n/);
+    return (lines[0] ?? "").trim() === "# Today";
+}
+function validateTodayContent(content, options = {}) {
+    if (options.allowLegacyToday && isLegacyTodayContent(content))
+        return null;
+    const lines = content.split(/\r?\n/);
+    const firstLine = (lines[0] ?? "").trim();
+    if (!TODAY_H1_RE.test(firstLine)) {
+        return "today.md line 1 must be `# YYYY-MM-DD (day-of-week)`.";
+    }
+    if (!TODAY_DAY_TYPE_RE.test((lines[1] ?? "").trim())) {
+        return "today.md line 2 must be `> Day type: Weekday|Weekend | Work focus: on|off | Study focus: on|off | Personal focus: on|off`.";
+    }
+    // Agent-day-date check — rejects wrong-date H1 with a clear error echoing
+    // both values. Without this, a wrong-date PUT silently succeeds (regex
+    // passes) and the dispatcher's post-run hasCurrentAgentDayTodayMd() check
+    // schedules a retry while the same session still has the prompt context
+    // loaded, wasting a heavy-tier turn cycle. With this guard the agent gets
+    // immediate feedback and corrects in-session.
+    if (options.expectedAgentDay) {
+        // TODAY_H1_RE already matched, so the YYYY-MM-DD capture is guaranteed.
+        // No optional-chain — the regex precondition guarantees `[1]` is set.
+        const writtenDate = firstLine.match(/^# (\d{4}-\d{2}-\d{2})/)[1];
+        if (writtenDate !== options.expectedAgentDay) {
+            return (`today.md line 1 date '${writtenDate}' does not match the current ` +
+                `agent-day date '${options.expectedAgentDay}'. ` +
+                `Use the date from <current_agent_day date="..."> in your prompt context — ` +
+                `the agent-day differs from calendar today before the day-boundary hour.`);
+        }
+    }
+    let previousSectionIndex = 1;
+    for (const section of TODAY_REQUIRED_SECTIONS) {
+        const index = lines.findIndex((line, lineIndex) => lineIndex > previousSectionIndex && line.trim() === `## ${section}`);
+        if (index < 0) {
+            return `today.md requires \`## ${section}\` in canonical order.`;
+        }
+        previousSectionIndex = index;
+    }
+    const parsed = extractTodayAgentPlanRows(content);
+    if (parsed.invalidRows.length > 0) {
+        const first = parsed.invalidRows[0];
+        return (`today.md Agent Plan line ${first.line} must match ` +
+            `\`- [ ] HH:MM <action> [work|study|personal|home] →DM|→notify|→check-in|→wake\`. ` +
+            `Got: ${JSON.stringify(first.raw)}`);
+    }
+    return null;
+}
+function toTodayScheduleCandidate(row, timezone) {
+    const scheduledAt = parseScheduleDate(row.scheduled_for);
+    if (Number.isNaN(scheduledAt.getTime()))
+        return null;
+    const local = nowInTimezone(timezone, scheduledAt);
+    const localDate = `${local.year}-${String(local.month).padStart(2, "0")}-${String(local.day).padStart(2, "0")}`;
+    const localTime = `${String(local.hours).padStart(2, "0")}:${String(local.minutes).padStart(2, "0")}`;
+    return {
+        id: row.id,
+        scheduledFor: row.scheduled_for,
+        localDate,
+        localTime,
+        taskType: row.task_type,
+        status: row.status,
+        description: row.task_description,
+        taskContext: parseJsonObject(row.task_context),
+    };
+}
+function parseScheduleDate(value) {
+    return new Date(value.includes("T") ? value : value.replace(" ", "T") + "Z");
+}
+function parseJsonObject(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore corrupt metadata for reconciliation diagnostics.
+    }
+    return {};
+}
+function prepareContextContentForWrite(target, content, options) {
+    if (target.base !== "roadmap") {
+        const contentError = validateContextContent(target, content, {
+            allowLegacyToday: options?.allowLegacyToday,
+            expectedAgentDay: options?.expectedAgentDay,
+        });
+        if (contentError) {
+            return {
+                ok: false,
+                message: contentError.message,
+                status: contentError.status,
+                path: contentError.path,
+            };
+        }
+        return { ok: true, content };
+    }
+    if (options?.disableRoadmapValidation) {
+        return { ok: true, content };
+    }
+    const normalized = normalizeRoadmapForWrite(content, {
+        timezone: options?.timezone,
+        defaultLongTermPlanSource: options?.defaultLongTermPlanSource ?? "manual",
+    });
+    const result = validateRoadmap(normalized.content);
+    if (!result.ok && result.error) {
+        return {
+            ok: false,
+            message: formatRoadmapValidationError(result.error),
+            status: 400,
+            path: result.error.path,
+        };
+    }
+    if (options?.previousRoadmapContent !== undefined) {
+        const transition = validateRoadmapTransition(options.previousRoadmapContent, normalized.content, {
+            today: options.today,
+            timezone: options.timezone,
+        });
+        if (!transition.ok && transition.error) {
+            return {
+                ok: false,
+                message: formatRoadmapValidationError(transition.error),
+                status: 400,
+                path: transition.error.path,
+            };
+        }
+    }
+    return { ok: true, content: normalized.content };
+}
+function formatRoadmapValidationError(error) {
+    const line = error.line ? `line ${error.line}: ` : "";
+    return `${line}${error.message}`;
+}
+function validateBuiltInRoutineRulebook(path, content) {
+    const frontmatter = extractRoutineFrontmatter(content);
+    if (frontmatter === null) {
+        return "Routine rulebooks require YAML frontmatter.";
+    }
+    const expectedSlug = path.slice("routines/".length);
+    const typeRaw = readRoutineFrontmatterScalar(frontmatter, "type");
+    if (!typeRaw) {
+        return "Routine rulebooks require `type: rule` in frontmatter.";
+    }
+    if (typeRaw !== "rule") {
+        return "Routine rulebooks must declare `type: rule`.";
+    }
+    const slugRaw = readRoutineFrontmatterScalar(frontmatter, "slug");
+    if (!slugRaw) {
+        return "Routine rulebooks require a `slug` frontmatter field.";
+    }
+    if (slugRaw !== expectedSlug) {
+        return `Routine rulebook slug must match the filename (${expectedSlug}).`;
+    }
+    if (!/^##\s+Checks\s*$/m.test(content)) {
+        return "Routine rulebooks require a `## Checks` section.";
+    }
+    return null;
+}
+function explainCustomRoutineValidationError(error) {
+    switch (error.kind) {
+        case "missing_field":
+            return `Custom routine files require \`${error.field}\` in frontmatter.`;
+        case "invalid_cron":
+            return `Invalid cron expression: \`${error.value}\`.`;
+        case "invalid_slug":
+            return `Custom routine slug is invalid or does not match the filename: \`${error.value}\`.`;
+        case "invalid_type":
+            return `Custom routines must declare \`type: rule\`, got \`${error.value}\`.`;
+        case "invalid_process_key":
+            return `Custom routine \`process_key\` must match the filename-derived key, got \`${error.value}\`.`;
+        case "invalid_enabled":
+            return `Custom routine \`enabled\` must be \`true\` or \`false\`, got \`${error.value}\`.`;
+        case "invalid_tier":
+            return `Custom routine \`backend_tier\` must be \`light\` or \`heavy\`, got \`${error.value}\`.`;
+        case "invalid_budget":
+            return `Custom routine \`max_budget_usd\` must be a positive number, got \`${error.value}\`.`;
+        case "missing_checks_section":
+            return "Custom routines require a `## Checks` section.";
+        case "no_frontmatter":
+            return "Custom routines require YAML frontmatter.";
+    }
+}
+function extractRoutineFrontmatter(content) {
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+        return null;
+    }
+    const afterOpen = content.startsWith("---\r\n") ? 5 : 4;
+    const endIdx = content.indexOf("\n---", afterOpen - 1);
+    if (endIdx < 0)
+        return null;
+    return content.slice(afterOpen, endIdx);
+}
+function readRoutineFrontmatterScalar(frontmatter, field) {
+    const re = new RegExp(`^${field}\\s*:\\s*(.+?)\\s*$`, "m");
+    const match = frontmatter.match(re);
+    if (!match)
+        return null;
+    let value = match[1].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return value;
+}
+function validateBaseYamlSyntax(content) {
+    if (content.trim().length === 0) {
+        return ".base files must not be empty.";
+    }
+    const lines = content.split("\n");
+    let sawMeaningfulLine = false;
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index];
+        const lineNo = index + 1;
+        if (raw.includes("\t")) {
+            return `.base YAML may not contain tab indentation (line ${lineNo}).`;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        sawMeaningfulLine = true;
+        const indent = raw.length - raw.trimStart().length;
+        if (indent % 2 !== 0) {
+            return `.base YAML uses 2-space indentation (line ${lineNo}).`;
+        }
+        const isListItem = /^-\s+\S/.test(trimmed);
+        const isMapping = /^[^:#][^:]*:\s*(?:.*)?$/.test(trimmed);
+        if (!isListItem && !isMapping) {
+            return `Invalid .base YAML structure on line ${lineNo}.`;
+        }
+    }
+    if (!sawMeaningfulLine) {
+        return ".base files must contain at least one mapping entry.";
+    }
+    return null;
+}
+// Export for testing
+export { normalizeSection, findSection, isWriteAllowed, safePath, resolveContextTarget, validateBaseYamlSyntax, validateTodayContent, clearEntriesBefore, trimBulletEntries, parseEntryTimestamp, };
+//# sourceMappingURL=context.js.map