@aitne/daemon 0.1.7 → 0.1.9

package/dist/api/routes/context/snapshots.js

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { localDateStr } from "@aitne/shared";
+import { writeFileAtomically } from "../../../core/atomic-write.js";
+import { serializeContextFileWrite } from "../../../core/context-file-serializer.js";
+import { validateContextContent } from "../../../core/context-validation/index.js";
+import { createLogger } from "../../../logging.js";
+import { composeIssue, respondWithAgentError, } from "../../helpers/agent-errors.js";
+import { isWriteAllowed, notifyPromptContextChanged, shouldRefreshPromptContext, } from "./permissions.js";
+import { resolveContextTarget, safePath } from "./path-resolve.js";
+const logger = createLogger("context-api");
+export function registerSnapshotsRoutes(app, ctx) {
+    const { deps, getCurrentContextDir, morningRoutineLock, roadmapWriteLock, saveSnapshot, } = ctx;
+    const { db, writeTracker } = deps;
+    // 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) => {
+        const contextDir = getCurrentContextDir();
+        const todayPath = join(contextDir, "state", "today.md");
+        const yesterdayPath = join(contextDir, "state", "yesterday.md");
+        // The rotation source is fixed to state/today.md, so the same
+        // morning-routine-lock guard that PUT/PATCH/restore-snapshot apply
+        // to state/today must hold here too. The per-path serializer below
+        // only prevents byte-level interleaving — it does NOT stop a
+        // concurrent non-morning session from logically rotating
+        // today.md → yesterday.md while the morning routine holds the
+        // exclusive lock mid-build, which would defeat the lock's
+        // exclusivity invariant. Mirror restore-snapshot's guard.
+        if (morningRoutineLock.getHolder()) {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!morningRoutineLock.isHeldBy(lockId)) {
+                logger.info({ path: "state/today" }, "Archive-today rejected — morning routine lock held");
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.morning_routine_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
+            }
+        }
+        // Acquire today.md FIRST, then yesterday.md inside. The fixed
+        // lock order (alphabetical by absolute path is the convention)
+        // prevents deadlock against any other caller that needs both.
+        // Both gates are required: the SOURCE (today.md) read must not
+        // race with a concurrent today.md writer (else we'd snapshot
+        // a half-written state), and the DESTINATION (yesterday.md)
+        // write must not race with a concurrent yesterday.md PATCH
+        // (else the rotation could be clobbered by — or could clobber —
+        // an in-flight user edit). The legacy in-router `withWriteLock`
+        // serialized ALL writes so this race was masked; the new
+        // per-path serializer requires explicit composition.
+        return serializeContextFileWrite(todayPath, () => serializeContextFileWrite(yesterdayPath, () => {
+            if (!existsSync(todayPath)) {
+                return respondWithAgentError(c, 404, [
+                    composeIssue("context.path_not_found", {
+                        field: "path",
+                        received: "today",
+                    }),
+                ]);
+            }
+            const content = readFileSync(todayPath, "utf-8");
+            const dateStr = content.match(/^#.*(\d{4}-\d{2}-\d{2})/)?.[1] ??
+                localDateStr(new Date());
+            // 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("state/today", content, "rotate-to-yesterday", true);
+            return c.json({
+                status: "archived",
+                archivePath: "state/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 idRaw = c.req.param("id");
+        const id = Number(idRaw);
+        if (!Number.isSafeInteger(id) || id <= 0) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.snapshot_id_invalid", {
+                    field: "id",
+                    received: idRaw,
+                }),
+            ]);
+        }
+        const row = db
+            .prepare("SELECT id, file_path, content FROM md_file_snapshots WHERE id = ?")
+            .get(id);
+        if (!row) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.snapshot_not_found", {
+                    field: "id",
+                    received: id,
+                }),
+            ]);
+        }
+        const target = resolveContextTarget(row.file_path);
+        const path = target.base;
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, row.file_path);
+        if (!fullPath) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
+        }
+        if (!isWriteAllowed(path, "PUT") && !isWriteAllowed(path, "PATCH")) {
+            logger.warn({ path, method: "RESTORE" }, "Snapshot restore forbidden");
+            return respondWithAgentError(c, 403, [
+                composeIssue("context.write_forbidden", {
+                    field: "path",
+                    received: { path, method: "RESTORE" },
+                }),
+            ]);
+        }
+        if (morningRoutineLock.getHolder() && path === "state/today") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!morningRoutineLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Snapshot restore rejected — morning routine lock held");
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.morning_routine_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
+            }
+        }
+        if (roadmapWriteLock.getHolder() && path === "plans/roadmap") {
+            const lockId = c.req.header("X-Lock-Id");
+            if (!roadmapWriteLock.isHeldBy(lockId)) {
+                logger.info({ path }, "Snapshot restore rejected — roadmap write lock held");
+                return respondWithAgentError(c, 409, [
+                    composeIssue("context.roadmap_write_lock_held", {
+                        field: "X-Lock-Id",
+                        received: lockId ?? "<missing>",
+                    }),
+                ]);
+            }
+        }
+        const contentError = validateContextContent(target, row.content, {
+            skipFrontmatterValidation: true,
+        });
+        if (contentError) {
+            return respondWithAgentError(c, contentError.status, [
+                composeIssue("context.content_validation_failed", {
+                    field: contentError.path ?? "content",
+                    received: contentError.message,
+                }),
+            ], {
+                legacyFields: {
+                    message: contentError.message,
+                    path: contentError.path,
+                },
+            });
+        }
+        return serializeContextFileWrite(fullPath, () => {
+            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.
+            // Mark before the rename so FS-watch consumers attribute the
+            // resulting event to the agent. Roll back on failure (C2).
+            writeTracker?.markWriting(fullPath, row.content);
+            try {
+                writeFileAtomically(fullPath, row.content);
+            }
+            catch (writeErr) {
+                writeTracker?.unmark(fullPath);
+                throw writeErr;
+            }
+            if (shouldRefreshPromptContext(path, "PUT")) {
+                notifyPromptContextChanged(deps, path, `context_restore_snapshot:${path}`, { path, method: "RESTORE" });
+            }
+            if (path.startsWith("policies/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(),
+            });
+        });
+    });
+}

package/dist/api/routes/context/write-step.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `performContextFileWrite` — the shared write chokepoint for both the
+ * HTTP context API (`PUT /api/context/*`, `PATCH /api/context/* mode=append_to_file`)
+ * and any in-process daemon writer that targets the same files (today
+ * exercised by `DailyJournalComposer` in `core/morning/`).
+ *
+ * Spec: `docs/design/appendices/daily-journal-daemon-write.md` §4.9.
+ *
+ * Scope (deliberate):
+ *   - Daily-skeleton frontmatter validation for `daily/*.md` on PUT (the
+ *     same `validateDailySkeletonFrontmatter` the HTTP route runs today).
+ *   - Atomic symlink-safe write via `writeFileAtomically`.
+ *   - `md_file_snapshots` insert through the same debounced helper the
+ *     HTTP route uses (passed in via `saveSnapshot`).
+ *   - `writeTracker.markWriting` / `unmark` framing so obsidian / git
+ *     observers tag the resulting fs event with `actor='agent'`.
+ *   - `onIndexableContextChange` hint for the context-index reconciler.
+ *
+ * Out of scope (stays on the HTTP route):
+ *   - Permission gates (`isWriteAllowed`, append-only PUT, write locks,
+ *     degraded-mode 503, migration 503).
+ *   - Body parsing + Zod schema validation.
+ *   - Optimistic mtime conflict checks.
+ *   - `prepareContextContentForWrite` (roadmap-validation aware, section
+ *     parsing). Callers compose the final byte stream BEFORE calling.
+ *   - `notifyPromptContextChanged` (per-request side effect; the
+ *     in-process composer fires a different change-hint chain).
+ *
+ * The helper is intentionally tight — pulling everything into it would
+ * force the in-process composer to either drag in Hono Context shapes or
+ * to short-circuit half the HTTP route's validation. Sharing only the
+ * "raw write step" keeps both paths on the same atomic-write +
+ * snapshot + tracker invariants without coupling them to each other's
+ * request/response idioms.
+ */
+import { validateDailySkeletonFrontmatter } from "../../../core/context-frontmatter.js";
+import type { AgentWriteTracker } from "../../../safety/agent-write-tracker.js";
+export interface PerformContextFileWriteDeps {
+    /** Snapshot helper. Pass through `ctx.saveSnapshot` for HTTP callers; the
+     *  in-process composer supplies a thin direct-INSERT wrapper. */
+    saveSnapshot: (
+    /** Stem-only path used as the `md_file_snapshots.file_path` column
+     *  (matches the HTTP route's stem semantics — no `.md` suffix). */
+    snapshotKey: string, content: string, trigger: string, force?: boolean, sessionId?: string | null) => number | null;
+    /** Optional write-tracker so obsidian / git observers can attribute the
+     *  resulting fs event to the agent. */
+    writeTracker?: Pick<AgentWriteTracker, "markWriting" | "unmark">;
+    /** Optional indexable-change hint. */
+    onIndexableContextChange?: (relativePath: string) => void;
+}
+export type ContextFileWriteMode = "put" | "append_block";
+export interface PerformContextFileWriteArgs {
+    /** Absolute on-disk path. Caller is responsible for resolving via
+     *  `safePath` first when the path comes from user / agent input. */
+    absolutePath: string;
+    /** Relative-to-contextDir path for snapshot key + indexable hint
+     *  (e.g. `"daily/2026-05-22.md"`). */
+    relativePath: string;
+    /** Snapshot key (stem only — `"daily/2026-05-22"`, not `".md"`). The
+     *  HTTP route uses `target.base` as this key; the composer derives it
+     *  from `relativePath` by stripping the `.md` suffix. Passing it
+     *  explicitly avoids re-deriving it differently between callers. */
+    snapshotKey: string;
+    /**
+     * - `"put"`: full-replace write. The atomic write replaces the file
+     *   wholesale; if the file exists we snapshot the pre-state first.
+     * - `"append_block"`: read-modify-write that appends `content` to EOF
+     *   with a leading newline if needed. When `blockHeader` is set and
+     *   already present at H2-line granularity, the matching block is
+     *   replaced (LAST-wins, mirrors `appendBlockToJournal`). The file
+     *   MUST exist for this mode — callers gate on `existsSync` first.
+     */
+    mode: ContextFileWriteMode;
+    /**
+     * For `put`: full file content. For `append_block`: the block to
+     *  append (must start with the `blockHeader` line when supplied).
+     *  The helper does not trim or rewrite — the byte stream is exactly
+     *  what lands on disk.
+     */
+    content: string;
+    /**
+     * For `append_block`: the H2 header line (e.g.
+     *  `"## Agent revision — 2026-05-22T19:01:12.345Z"`) that anchors
+     *  LAST-wins replacement on retry. Required when `mode = "append_block"`
+     *  and the caller wants idempotent retries; omit to force pure
+     *  append-without-dedupe.
+     */
+    blockHeader?: string;
+    /** `md_file_snapshots.trigger` label. */
+    trigger: string;
+    /** Force snapshot regardless of `SNAPSHOT_DEBOUNCE_MS`. */
+    forceSnapshot?: boolean;
+    /** Pass-through to `saveSnapshot`. */
+    sessionId?: string | null;
+    /** When true (the default for the HTTP PUT route), run
+     *  `validateDailySkeletonFrontmatter` against `content` for paths
+     *  inside `daily/` and refuse the write if it returns drift errors.
+     *  Returned as a structured `validation_failed` error rather than
+     *  throwing so the HTTP route can map it to a 422 response. */
+    validateDailySkeleton?: boolean;
+}
+export type PerformContextFileWriteResult = {
+    ok: true;
+    bytesWritten: number;
+    snapshotId: number | null;
+    /** Final on-disk content (after any append-block read-modify-write).
+     *  Useful for the composer to compute byte-counts for the audit row
+     *  without a re-read. */
+    finalContent: string;
+} | {
+    ok: false;
+    reason: "daily_skeleton_drift";
+    driftErrors: ReturnType<typeof validateDailySkeletonFrontmatter>;
+} | {
+    ok: false;
+    reason: "missing_for_append";
+};
+export declare function performContextFileWrite(deps: PerformContextFileWriteDeps, args: PerformContextFileWriteArgs): PerformContextFileWriteResult;
+/**
+ * Resolve the absolute path under contextDir for the daily journal of
+ * `dateStr`. The composer uses this to feed `performContextFileWrite`
+ * without duplicating the layout convention defined in
+ * `context-paths.ts:dailyJournalPath`.
+ */
+export declare function dailyJournalAbsolutePath(contextDir: string, dateStr: string): string;
+/**
+ * Re-export the canonical daily-relative path helper so callers needing
+ * both shapes don't have to import from two modules. (`relativePath` for
+ * snapshot + indexable, `snapshotKey` for the snapshot column.)
+ */
+export declare function dailyJournalSnapshotKey(dateStr: string): string;
+export declare const AGENT_JOURNAL_RELATIVE_PATH: "journal/agent.md";

package/dist/api/routes/context/write-step.js

@@ -0,0 +1,151 @@
+// drift-allow-file: documents the `daily/*.md` legacy validator path —
+// the docstring is the load-bearing reference for callers porting from
+// the pre-restructure layout.
+/**
+ * `performContextFileWrite` — the shared write chokepoint for both the
+ * HTTP context API (`PUT /api/context/*`, `PATCH /api/context/* mode=append_to_file`)
+ * and any in-process daemon writer that targets the same files (today
+ * exercised by `DailyJournalComposer` in `core/morning/`).
+ *
+ * Spec: `docs/design/appendices/daily-journal-daemon-write.md` §4.9.
+ *
+ * Scope (deliberate):
+ *   - Daily-skeleton frontmatter validation for `daily/*.md` on PUT (the
+ *     same `validateDailySkeletonFrontmatter` the HTTP route runs today).
+ *   - Atomic symlink-safe write via `writeFileAtomically`.
+ *   - `md_file_snapshots` insert through the same debounced helper the
+ *     HTTP route uses (passed in via `saveSnapshot`).
+ *   - `writeTracker.markWriting` / `unmark` framing so obsidian / git
+ *     observers tag the resulting fs event with `actor='agent'`.
+ *   - `onIndexableContextChange` hint for the context-index reconciler.
+ *
+ * Out of scope (stays on the HTTP route):
+ *   - Permission gates (`isWriteAllowed`, append-only PUT, write locks,
+ *     degraded-mode 503, migration 503).
+ *   - Body parsing + Zod schema validation.
+ *   - Optimistic mtime conflict checks.
+ *   - `prepareContextContentForWrite` (roadmap-validation aware, section
+ *     parsing). Callers compose the final byte stream BEFORE calling.
+ *   - `notifyPromptContextChanged` (per-request side effect; the
+ *     in-process composer fires a different change-hint chain).
+ *
+ * The helper is intentionally tight — pulling everything into it would
+ * force the in-process composer to either drag in Hono Context shapes or
+ * to short-circuit half the HTTP route's validation. Sharing only the
+ * "raw write step" keeps both paths on the same atomic-write +
+ * snapshot + tracker invariants without coupling them to each other's
+ * request/response idioms.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomically } from "../../../core/atomic-write.js";
+import { validateDailySkeletonFrontmatter } from "../../../core/context-frontmatter.js";
+import { CONTEXT_RELATIVE_PATHS } from "../../../core/context-paths.js";
+import { parseVaultFrontmatter } from "../../../core/context-validation/frontmatter.js";
+import { createLogger } from "../../../logging.js";
+const logger = createLogger("context-write-step");
+export function performContextFileWrite(deps, args) {
+    if (args.mode === "put" && args.validateDailySkeleton === true) {
+        if (args.relativePath.startsWith("journal/daily/")) {
+            const driftErrors = validateDailySkeletonFrontmatter(args.content, args.relativePath);
+            if (driftErrors.length > 0) {
+                return { ok: false, reason: "daily_skeleton_drift", driftErrors };
+            }
+        }
+    }
+    // CONTEXT_VAULT_REDESIGN_PLAN.md §5.3 — Phase 1 advisory parse of the
+    // new vault contract fields (kind / authority / mutability / slug /
+    // title). Advisories log a warning; nothing rejects the write. The
+    // Phase 2 cut-over swaps these warnings for a structured 422 once
+    // `runtimeSettings.contextVault.enforceFrontmatter` lands.
+    if (args.mode === "put") {
+        const advisory = parseVaultFrontmatter(args.content, args.relativePath);
+        if (advisory.advisories.length > 0) {
+            logger.warn({
+                relativePath: args.relativePath,
+                advisories: advisory.advisories.map((a) => ({
+                    code: a.code,
+                    message: a.message,
+                })),
+            }, "Vault frontmatter advisory (Phase 1 non-blocking)");
+        }
+    }
+    let snapshotId = null;
+    let toWrite;
+    if (args.mode === "put") {
+        if (existsSync(args.absolutePath)) {
+            const existing = readFileSync(args.absolutePath, "utf-8");
+            snapshotId = deps.saveSnapshot(args.snapshotKey, existing, args.trigger, args.forceSnapshot ?? true, args.sessionId ?? null);
+        }
+        toWrite = args.content;
+    }
+    else {
+        if (!existsSync(args.absolutePath)) {
+            return { ok: false, reason: "missing_for_append" };
+        }
+        const existing = readFileSync(args.absolutePath, "utf-8");
+        snapshotId = deps.saveSnapshot(args.snapshotKey, existing, args.trigger, args.forceSnapshot ?? false, args.sessionId ?? null);
+        toWrite = appendBlockWithLastWins(existing, args.content, args.blockHeader);
+    }
+    deps.writeTracker?.markWriting(args.absolutePath, toWrite);
+    try {
+        writeFileAtomically(args.absolutePath, toWrite);
+    }
+    catch (writeErr) {
+        deps.writeTracker?.unmark(args.absolutePath);
+        throw writeErr;
+    }
+    deps.onIndexableContextChange?.(args.relativePath);
+    // Compute bytes from the byte representation rather than re-stat'ing —
+    // a successful atomic write means the on-disk size is exactly this.
+    // Avoids a TOCTOU race where another process modifies the file between
+    // rename and stat.
+    const bytesWritten = Buffer.byteLength(toWrite, "utf-8");
+    return { ok: true, bytesWritten, snapshotId, finalContent: toWrite };
+}
+/**
+ * Append `block` to `original`. Pure append-with-newline-separator —
+ * the helper deliberately does NOT do LAST-wins H2-boundary
+ * replacement.
+ *
+ * Why no LAST-wins: the agent-journal-appender uses LAST-wins because
+ * each block is wrapped in a predictable `## YYYY-MM-DD morning routine`
+ * H2 and there are no other H2s. Daily-journal `## Agent revision —`
+ * blocks DO contain inner H2s (`## Summary`, `## Tasks`, etc.) emitted
+ * by the journal body, so an H2-anchored replacement would collapse to
+ * the first inner H2 and corrupt the file. Design §4.8 explicitly
+ * calls for "preserve any user edits" via pure append.
+ *
+ * Stage B idempotency on retry is guaranteed elsewhere: the orchestrator
+ * does NOT re-fire Stage B on retry (`MorningRoutinePipelineOrchestrator`
+ * §"Retry semantics"), so the same revision header cannot land twice in
+ * a single morning's run.
+ *
+ * The `blockHeader` parameter is accepted but unused — kept for caller
+ * symmetry with the agent-journal-appender's API and to leave room for
+ * a future H2-aware variant if a different file shape needs it.
+ */
+function appendBlockWithLastWins(original, block, _blockHeader) {
+    const trimmed = original.replace(/\n+$/, "");
+    return `${trimmed}\n\n${block}\n`;
+}
+/**
+ * Resolve the absolute path under contextDir for the daily journal of
+ * `dateStr`. The composer uses this to feed `performContextFileWrite`
+ * without duplicating the layout convention defined in
+ * `context-paths.ts:dailyJournalPath`.
+ */
+export function dailyJournalAbsolutePath(contextDir, dateStr) {
+    return join(contextDir, "journal", "daily", `${dateStr}.md`);
+}
+/**
+ * Re-export the canonical daily-relative path helper so callers needing
+ * both shapes don't have to import from two modules. (`relativePath` for
+ * snapshot + indexable, `snapshotKey` for the snapshot column.)
+ */
+export function dailyJournalSnapshotKey(dateStr) {
+    return `journal/daily/${dateStr}`;
+}
+// Re-export so the agent-journal-appender (which shares the snapshot
+// trigger label) can keep importing the constant from one place.
+export const AGENT_JOURNAL_RELATIVE_PATH = CONTEXT_RELATIVE_PATHS.agent.journal;

package/dist/api/routes/context/write.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from "hono";
+import type { ContextRouteContext } from "./index.js";
+export declare function registerWriteRoutes(app: Hono, ctx: ContextRouteContext): void;