@aitne/daemon 0.1.7 → 0.1.9

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

@@ -0,0 +1,234 @@
+import { classifyContextWriteStaleness } from "../../../core/context-staleness.js";
+import { createLogger } from "../../../logging.js";
+const logger = createLogger("context-api");
+/**
+ * Write-permission whitelist (CONTEXT_VAULT_REDESIGN_PLAN.md §7.1).
+ *
+ * After the six-class restructure the table collapses from 26 explicit
+ * patterns to one per class prefix plus a small number of exceptions
+ * (`CREATE_ONLY_PUT`, `git/{slug}` placeholders, lifecycle DELETEs).
+ * Legacy URLs (`PUT /api/context/today.md` etc.) are normalised by the
+ * API alias resolver before this table is consulted, so canonical paths
+ * are the only inputs we have to enumerate.
+ */
+export const CONTEXT_WRITE_PERMISSIONS = {
+    // Top-level survivors.
+    _index: ["PUT", "PATCH"],
+    // state/
+    "state/today": ["PUT", "PATCH"],
+    "state/yesterday": ["PUT", "PATCH"],
+    "state/profile-questions": ["PUT", "PATCH"],
+    "state/inbox/*": ["PUT", "PATCH", "DELETE"],
+    "state/scratch/*": ["PUT", "PATCH", "DELETE"],
+    "state/activity/*": ["PUT", "PATCH"],
+    // identity/
+    "identity/_index": ["PUT", "PATCH"],
+    "identity/*": ["PUT", "PATCH"],
+    // plans/
+    "plans/roadmap": ["PUT", "PATCH"],
+    "plans/projects/_index": ["PUT", "PATCH"],
+    "plans/projects/_active": ["PUT"],
+    "plans/projects/*": ["PUT", "PATCH"],
+    // policies/ — DELETE intentionally omitted for management-captures:
+    // policy files use `status: removed` in lieu of physical deletion so
+    // the captured history (origin DM, why, linked routine) survives.
+    "policies/_index": ["PUT", "PATCH"],
+    "policies/management": ["PUT", "PATCH"],
+    "policies/mcp": ["PUT", "PATCH"],
+    "policies/redaction": ["PUT", "PATCH"],
+    "policies/journal-format": ["PUT", "PATCH"],
+    "policies/journal-export": ["PUT", "PATCH"],
+    "policies/integrations": ["PUT", "PATCH"],
+    "policies/management-captures/_index": ["PUT", "PATCH"],
+    "policies/management-captures/*": ["PUT", "PATCH"],
+    "policies/routines/_index": ["PUT", "PATCH"],
+    "policies/routines/*": ["PUT", "PATCH"],
+    // Custom routines support DELETE so the agent can retire a routine
+    // when the user asks via DM.
+    "policies/routines/custom/*": ["PUT", "PATCH", "DELETE"],
+    // User Agent definitions (AGENT_DEFINITIONS_DESIGN.md §9.5 / §3.3). The
+    // dashboard's "+ New Agent" scaffold and the YAML editor write user Agents
+    // to `policies/agents/<slug>/agent.md` through the context-vault chokepoint;
+    // DELETE retires one. Built-in Agents never live here — they ship under
+    // `agent-assets/agents/` and their overrides live in the DB, so this path
+    // only ever owns user-authored definitions. `{slug}/{file}` matches the
+    // two-segment `policies/agents/<slug>/agent` form `normalizeContextPath`
+    // produces (the `.md` extension is stripped before the whitelist check).
+    "policies/agents/{slug}/{file}": ["PUT", "PATCH", "DELETE"],
+    // journal/ — append-only narrative. `journal/agent.md` is
+    // `CREATE_ONLY_PUT` and only accepts append-style PATCH.
+    "journal/daily/*": ["PUT", "PATCH"],
+    "journal/weekly/*": ["PUT", "PATCH"],
+    "journal/monthly/*": ["PUT", "PATCH"],
+    "journal/agent": ["PUT", "PATCH"],
+    "journal/repos/{slug}/{date}": ["PUT", "PATCH"],
+    // knowledge/ — dossiers + per-repo overviews + entity files.
+    "knowledge/dossiers/_index": ["PUT", "PATCH"],
+    "knowledge/dossiers/*": ["PUT", "PATCH"],
+    "knowledge/repos/{slug}/overview": ["PUT", "PATCH"],
+    // Legacy git-repos registry preserved read-only under
+    // knowledge/repos/legacy-registry/ — left writable so the user can
+    // clean up dangling entries; no new writes target this path.
+    "knowledge/repos/legacy-registry/*": ["PUT", "PATCH"],
+    "knowledge/entities/{domain}/_index": ["PUT", "PATCH"],
+    "knowledge/entities/{domain}/{typePlural}/{slug}": ["PUT", "PATCH"],
+    // research/ — browser-history research-cluster journals
+    // (BROWSER_HISTORY_INTEGRATION_PLAN). The routine.research_dispatch /
+    // research_wiki_summary / research_cluster_update task-flows persist the
+    // per-cluster journal via PUT/PATCH /api/context/research/<slug>.md (plus
+    // `<slug>-assistance-<date>.md` and `<slug>-wiki.md`). These are flat,
+    // single-segment files under research/. DELETE is intentionally omitted —
+    // concluding a cluster *preserves* its journal (commands-research.ts), so
+    // there is no agent-driven delete path. Without this entry every research
+    // write returned 403 context.write_forbidden, silently breaking the flow.
+    "research/*": ["PUT", "PATCH"],
+};
+/**
+ * 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.
+ *
+ * The contract has two sides — PUT-after-creation is denied here; the
+ * PATCH handler additionally restricts these paths to {@link APPEND_ONLY_PATCH_MODES},
+ * so `mode:"replace"` / `"clear"` / `"clear_before"` cannot erase existing
+ * sections behind the agent's back.
+ */
+export const CREATE_ONLY_PUT = new Set(["journal/agent"]);
+/**
+ * PATCH modes that count as "append-style" for paths in {@link CREATE_ONLY_PUT}.
+ * Every other mode (`"replace"`, `"clear"`, `"clear_before"`) MUST be
+ * rejected on append-only paths — otherwise a prompt-injected agent (or
+ * any caller with a valid bearer token) could PATCH `agent/journal` with
+ * `mode:"replace"` against a section and destroy historical entries the
+ * "create-only PUT" gate was meant to protect.
+ */
+export const APPEND_ONLY_PATCH_MODES = new Set([
+    "append",
+    "append_to_file",
+]);
+/**
+ * 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.
+ */
+export const PLACEHOLDER_SEGMENT_RE = /^[a-z0-9._-]+$/;
+export 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 + "$");
+}
+export 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("/");
+                /* c8 ignore next 2 — segment-length mismatch after a regex match is
+                 * unreachable: patternToRegex already validates the full path structure. */
+                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 /* c8 ignore next 2 — literal mismatch after a full-pattern regex match
+                            * is unreachable: the regex enforces exact literal equality. */ 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.
+ */
+export function shouldRefreshPromptContext(path, method) {
+    if (path === "state/today" ||
+        path === "plans/roadmap" ||
+        path === "_index") {
+        return true;
+    }
+    // Any policies/*.md edit feeds the policy-files injection hub, so
+    // changes should invalidate the owner-session prompt cache.
+    // policies/routines/* drives task-flow prompts.
+    if (path.startsWith("policies/")) {
+        return true;
+    }
+    if (path.startsWith("knowledge/dossiers/")) {
+        return true;
+    }
+    if (path === "identity/profile" && method === "PUT") {
+        return true;
+    }
+    return false;
+}
+export 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) {
+        /* c8 ignore next 5 — DB INSERT failure inside a best-effort audit path;
+         * triggering requires closing the DB mid-request, which destroys the
+         * test harness. */
+        logger.warn({ err, path, method: input.method }, "Failed to record context_write agent_actions row (Stage C metrics)");
+    }
+}

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

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

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

@@ -0,0 +1,306 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { localDateStr } from "@aitne/shared";
+import { CONTEXT_FILE_EXTENSIONS } from "../../../core/context-paths.js";
+import { buildContextHealthReport } from "../../../core/context-health.js";
+import { toTodayScheduleCandidate, validateTodayContent, } from "../../../core/context-validation/index.js";
+import { buildTodayAgentPlanMetadata, extractTodayAgentPlanRows, extractTodayDate, readTodayAgentPlanMetadata, } from "../../../core/today-agent-plan.js";
+import { createLogger } from "../../../logging.js";
+import { composeIssue, respondWithAgentError, } from "../../helpers/agent-errors.js";
+import { isWriteAllowed } from "./permissions.js";
+import { normalizeContextPath, safePath } from "./path-resolve.js";
+const logger = createLogger("context-api");
+export function registerReadRoutes(app, ctx) {
+    const { deps, getCurrentContextDir } = ctx;
+    const { db, config } = deps;
+    // GET /context/list/:dir — List files in directory.
+    //
+    // Accepts both the new canonical names ("identity", "policies",
+    // "policies/routines", "plans/projects", "journal/daily", ...) and
+    // the legacy aliases ("user", "rules", "routines", "projects",
+    // "daily", ...) — the latter are translated to the new dir before
+    // listing. Legacy aliases are removed in the same minor-release
+    // window as the §14.4 agent-asset prose sweep (PR-6).
+    // `:dir{.+}` (not bare `:dir`) so the param captures slashes — after the
+    // context-vault restructure the canonical dir names are nested
+    // ("journal/daily", "knowledge/repos", "policies/routines", ...). A bare
+    // single-segment `:dir` matches `[^/]+`, so those requests fell through to
+    // Hono's default 404 and the dashboard file tree showed only the
+    // single-segment dirs (identity, policies). The handler's `allowedDirs`
+    // whitelist + `legacyDirAlias` map already expect the nested names.
+    app.get("/context/list/:dir{.+}", (c) => {
+        const rawDir = c.req.param("dir");
+        const legacyDirAlias = {
+            user: "identity",
+            rules: "policies",
+            routines: "policies/routines",
+            projects: "plans/projects",
+            daily: "journal/daily",
+            weekly: "journal/weekly",
+            monthly: "journal/monthly",
+            dossiers: "knowledge/dossiers",
+            inbox: "state/inbox",
+            git: "knowledge/repos",
+            "git-repos": "knowledge/repos/legacy-registry",
+        };
+        const dir = legacyDirAlias[rawDir] ?? rawDir;
+        const allowedDirs = [
+            "identity",
+            "policies",
+            "policies/routines",
+            "policies/management-captures",
+            "plans/projects",
+            "journal/daily",
+            "journal/weekly",
+            "journal/monthly",
+            "knowledge/dossiers",
+            "knowledge/repos",
+            "knowledge/repos/legacy-registry",
+            "state/inbox",
+        ];
+        if (!allowedDirs.includes(dir)) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.directory_invalid", {
+                    field: "dir",
+                    received: { dir: rawDir, allowed: allowedDirs },
+                }),
+            ]);
+        }
+        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() };
+        });
+        // Surface custom routines so the dashboard routines editor sees
+        // them alongside the built-ins. After the restructure the parent
+        // dir is `policies/routines` and the custom sub-dir is
+        // `policies/routines/custom/`.
+        if (dir === "policies/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 — surface every per-repo file under
+        // the `knowledge/repos` listing so the Knowledge page tree shows
+        // them. Overview lives under `knowledge/repos/<slug>/overview.md`;
+        // per-day journals live under `journal/repos/<slug>/` and are
+        // surfaced as part of the journal/daily listing.
+        if (dir === "knowledge/repos") {
+            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(),
+                    });
+                }
+            }
+        }
+        // Surface policy capture files under `policies/management-captures/`
+        // flattened into the `policies` listing for skill consumers.
+        if (dir === "policies") {
+            const policiesDir = join(dirPath, "management-captures");
+            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: `management-captures/${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 respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: "today",
+                }),
+            ]);
+        }
+        if (!existsSync(fullPath)) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.path_not_found", {
+                    field: "path",
+                    received: "today",
+                }),
+            ]);
+        }
+        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));
+    });
+    // GET /context/* — Read context file. Registered LAST in this file so
+    // the specific routes above (`/list/:dir`, `/today/reconciliation`,
+    // `/health`) take precedence under Hono's first-match dispatch.
+    app.get("/context/*", (c) => {
+        const rawPath = c.req.path.replace("/api/context/", "");
+        if (!rawPath || rawPath === "list") {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_required", {
+                    field: "path",
+                    received: rawPath === "list" ? "list (route ambiguous with /list/:dir)" : "<empty>",
+                }),
+            ]);
+        }
+        const path = normalizeContextPath(rawPath);
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, rawPath);
+        if (!fullPath) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
+        }
+        if (!existsSync(fullPath)) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.path_not_found", {
+                    field: "path",
+                    received: path,
+                }),
+            ]);
+        }
+        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 === "state/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) {
+                /* c8 ignore next 5 — DB INSERT failure inside a best-effort audit path;
+                 * triggering requires closing the DB mid-request which destroys
+                 * the test harness. */
+                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"),
+        });
+    });
+}

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

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

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

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomically } from "../../../core/atomic-write.js";
+import { serializeContextFileWrite } from "../../../core/context-file-serializer.js";
+import { REPAIRABLE_STUB_TARGETS, normalizeRepairStubPath, } from "../../../core/context-health.js";
+import { resolveTemplatesRoot } from "../../../core/skeleton.js";
+import { createLogger } from "../../../logging.js";
+import { composeIssue, respondWithAgentError, } from "../../helpers/agent-errors.js";
+import { notifyPromptContextChanged, shouldRefreshPromptContext, } from "./permissions.js";
+import { normalizeContextPath, safePath } from "./path-resolve.js";
+const logger = createLogger("context-api");
+export function registerRepairRoutes(app, ctx) {
+    const { deps, getCurrentContextDir, readOptionalJsonBody, } = ctx;
+    const { config, writeTracker } = deps;
+    // 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 respondWithAgentError(c, 400, [
+                composeIssue("context.path_required", {
+                    field: "path",
+                    received: typeof rawPath,
+                }),
+            ], {
+                // repair-stub previously returned `error: "validation_error"` for
+                // the missing-path branch (not `"path_required"`); preserve that
+                // legacy alias so dashboard / older tests don't break.
+                legacyErrorCode: "validation_error",
+            });
+        }
+        const normalizedPath = normalizeRepairStubPath(rawPath);
+        if (!normalizedPath || !REPAIRABLE_STUB_TARGETS.has(normalizedPath)) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.stub_target_unsupported", {
+                    field: "path",
+                    received: { path: rawPath, allowed: Array.from(REPAIRABLE_STUB_TARGETS) },
+                }),
+            ]);
+        }
+        const templatesRoot = resolveTemplatesRoot(config.workspaceDir);
+        /* c8 ignore next 9 — resolveTemplatesRoot always succeeds via import.meta.url
+         * fallback in tests; the 503 branch requires a broken install where the
+         * agent-assets directory is absent from every candidate path. */
+        if (!templatesRoot) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("context.template_unavailable", {
+                    field: "templatesRoot",
+                    received: "<unresolved>",
+                }),
+            ]);
+        }
+        const templatePath = join(templatesRoot, normalizedPath);
+        if (!existsSync(templatePath)) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("context.template_not_found", {
+                    field: "path",
+                    received: { path: normalizedPath, templatePath },
+                }),
+            ]);
+        }
+        const contextDir = getCurrentContextDir();
+        const fullPath = safePath(contextDir, normalizedPath);
+        if (!fullPath) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("context.path_invalid", {
+                    field: "path",
+                    received: normalizedPath,
+                }),
+            ]);
+        }
+        return serializeContextFileWrite(fullPath, () => {
+            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");
+            // Mark before the rename so FS-watch consumers attribute the
+            // resulting event to the agent. Roll back on failure (C2).
+            writeTracker?.markWriting(fullPath, content);
+            try {
+                writeFileAtomically(fullPath, content);
+            }
+            catch (writeErr) {
+                writeTracker?.unmark(fullPath);
+                throw writeErr;
+            }
+            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(),
+            });
+        });
+    });
+}

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

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