@aitne/daemon 0.1.7 → 0.1.8

package/dist/api/routes/agent.js

@@ -1,129 +1,35 @@
 import { Hono } from "hono";
-import { notifyRequestSchema, redactSensitiveString, scheduleRequestSchema, scheduleUpdateRequestSchema, scheduleDmRequestSchema, actionLogRequestSchema, createEvent, EventPriority, nowInTimezone, formatSqliteDatetime, } from "@aitne/shared";
+import { notifyRequestSchema, redactSensitiveString, actionLogRequestSchema, createEvent, EventPriority, } from "@aitne/shared";
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { getContextDir } from "../../config.js";
 import { createLogger } from "../../logging.js";
 import { loadAuditEventRow } from "../../safety/audit.js";
 import { readJsonBody } from "../json-body.js";
-import { maybeTriggerRoadmapRefresh } from "../../core/schedule-insert-helper.js";
-import { buildTodayAgentPlanMetadata, extractTodayAgentPlanRows, extractTodayDate, normalizeAgentPlanAction, readTodayAgentPlanMetadata, } from "../../core/today-agent-plan.js";
+import { composeIssue, respondWithAgentError, } from "../helpers/agent-errors.js";
+import { registerAgentScheduleRoutes } from "./agent-schedule.js";
 const logger = createLogger("agent-api");
-function parseTaskContextJson(raw) {
-    // The agent_schedule.task_context column has DEFAULT '{}', so `raw` is never
-    // null from a properly-seeded row. This guard handles the edge case of a row
-    // inserted directly without the column value (test or legacy data).
-    /* c8 ignore next */
-    if (!raw)
-        return {};
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
-        }
-    }
-    catch (err) {
-        logger.warn({ err }, "Invalid task_context JSON in agent_schedule row");
-    }
-    return {};
-}
-function enrichAgentPlanTaskContext(taskContext, scheduledAt, description, deps) {
-    const nextContext = taskContext
-        ? { ...taskContext }
-        : {};
-    if (readTodayAgentPlanMetadata(nextContext))
-        return nextContext;
-    const config = deps.config;
-    if (!config?.dataDir)
-        return nextContext;
-    const timezone = config.timezone || undefined;
-    const scheduledLocal = localDateTimeParts(scheduledAt, timezone);
-    let content;
-    try {
-        const todayPath = join(getContextDir(config, deps.db), "today.md");
-        if (!existsSync(todayPath))
-            return nextContext;
-        content = readFileSync(todayPath, "utf-8");
-        /* c8 ignore start */
-    }
-    catch (err) {
-        logger.warn({ err }, "Failed to read today.md for Agent Plan schedule metadata");
-        return nextContext;
-    }
-    /* c8 ignore stop */
-    if (extractTodayDate(content) !== scheduledLocal.date)
-        return nextContext;
-    const candidates = extractTodayAgentPlanRows(content).rows.filter((row) => !row.checked && row.time === scheduledLocal.time);
-    const matched = selectAgentPlanRowForSchedule(candidates, description, nextContext);
-    if (!matched)
-        return nextContext;
-    nextContext.agentPlan = buildTodayAgentPlanMetadata(scheduledLocal.date, matched);
-    return nextContext;
-}
-function selectAgentPlanRowForSchedule(rows, description, taskContext) {
-    let candidates = rows;
-    const triggerHint = contextTriggerHint(taskContext);
-    if (triggerHint) {
-        const filtered = candidates.filter((row) => row.trigger === triggerHint);
-        if (filtered.length > 0)
-            candidates = filtered;
-    }
-    const categoryHint = contextCategoryHint(taskContext);
-    if (categoryHint) {
-        const filtered = candidates.filter((row) => row.category === categoryHint);
-        if (filtered.length > 0)
-            candidates = filtered;
-    }
-    const descriptionMatches = candidates.filter((row) => actionsLikelyMatch(row.action, description));
-    if (descriptionMatches.length === 1)
-        return descriptionMatches[0];
-    if (candidates.length === 1)
-        return candidates[0];
-    return null;
-}
-function actionsLikelyMatch(agentPlanAction, description) {
-    const action = normalizeAgentPlanAction(agentPlanAction);
-    const task = normalizeAgentPlanAction(description);
-    return task.includes(action) || action.includes(task);
-}
-function contextTriggerHint(taskContext) {
-    const value = taskContext.agentPlanTrigger ?? taskContext.trigger;
-    return value === "DM" ||
-        value === "notify" ||
-        value === "check-in" ||
-        value === "wake"
-        ? value
-        : null;
-}
-function contextCategoryHint(taskContext) {
-    const value = taskContext.agentPlanCategory ?? taskContext.category;
-    return value === "work" ||
-        value === "study" ||
-        value === "personal" ||
-        value === "home"
-        ? value
-        : null;
-}
-function localDateTimeParts(date, timezone) {
-    const local = nowInTimezone(timezone, date);
-    return {
-        date: `${local.year}-${String(local.month).padStart(2, "0")}-${String(local.day).padStart(2, "0")}`,
-        time: `${String(local.hours).padStart(2, "0")}:${String(local.minutes).padStart(2, "0")}`,
-    };
-}
 export function createAgentRoutes(deps) {
     const app = new Hono();
     const { db, sendNotification, eventBroadcaster } = deps;
     app.post("/agent/run-now", async (c) => {
         if (deps.isStartupComplete && !deps.isStartupComplete()) {
-            return c.json({
-                error: "daemon_starting",
-                message: "Daemon startup is still in progress. Try again in a moment.",
-            }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("agent.daemon_starting", {
+                    field: "daemon",
+                    received: "<starting>",
+                }),
+            ], {
+                legacyFields: {
+                    message: "Daemon startup is still in progress. Try again in a moment.",
+                },
+            });
         }
         if (!deps.triggerHourlyCheck) {
-            return c.json({ error: "hourly_check_unavailable" }, 503);
+            return respondWithAgentError(c, 503, [
+                composeIssue("agent.hourly_check_unavailable", {
+                    field: "triggerHourlyCheck",
+                    received: "<unavailable>",
+                }),
+            ]);
         }
         const body = await c.req.json().catch(() => ({}));
         const reason = typeof body.reason === "string" && body.reason.trim()
@@ -142,10 +48,16 @@ export function createAgentRoutes(deps) {
                 requestedModel = body.requestedModel;
             }
             else {
-                return c.json({
-                    error: "invalid_requestedModel",
-                    message: "requestedModel must be 'sonnet' or 'opus'",
-                }, 400);
+                return respondWithAgentError(c, 400, [
+                    composeIssue("agent.invalid_requested_model", {
+                        field: "requestedModel",
+                        received: body.requestedModel,
+                    }),
+                ], {
+                    legacyFields: {
+                        message: "requestedModel must be 'sonnet' or 'opus'",
+                    },
+                });
             }
         }
         const result = await deps.triggerHourlyCheck(`manual:${reason}`, {
@@ -154,6 +66,49 @@ export function createAgentRoutes(deps) {
         });
         return c.json(result);
     });
+    // POST /agent/run-now/roadmap-maintenance — Manual fire of the daily
+    // mechanical roadmap.md maintenance pass (evening-review slimdown
+    // §2.2). Same code path as the 17:45 cron callback. Used by
+    // `aitne run-now roadmap_maintenance` for operator debugging and
+    // the parallel-verification rollout phase. Synchronous: blocks
+    // until the pass completes (or is skipped) and returns the
+    // structured result so the CLI can surface counts.
+    app.post("/agent/run-now/roadmap-maintenance", async (c) => {
+        if (deps.isStartupComplete && !deps.isStartupComplete()) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("agent.daemon_starting", {
+                    field: "daemon",
+                    received: "<starting>",
+                }),
+            ], {
+                legacyFields: {
+                    message: "Daemon startup is still in progress. Try again in a moment.",
+                },
+            });
+        }
+        if (!deps.triggerRoadmapMaintenance) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("agent.roadmap_maintenance_unavailable", {
+                    field: "triggerRoadmapMaintenance",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
+        try {
+            const result = deps.triggerRoadmapMaintenance();
+            return c.json({ ok: true, result });
+        }
+        catch (err) {
+            logger.error({ err }, "Manual roadmap maintenance fire threw");
+            const message = err instanceof Error ? err.message : String(err);
+            return respondWithAgentError(c, 500, [
+                composeIssue("agent.roadmap_maintenance_failed", {
+                    field: "maintenance",
+                    received: message,
+                }),
+            ], { legacyFields: { message } });
+        }
+    });
     // POST /escalate — Removed in plan-aware-model-defaults. Automatic
     // Sonnet→Opus handoff was replaced by the opt-in advisor tool + explicit
     // manual Opus runs (dashboard chat model picker, agent_schedule.model,
@@ -266,7 +221,7 @@ export function createAgentRoutes(deps) {
             return parsedBody.response;
         const parsed = notifyRequestSchema.safeParse(parsedBody.body);
         if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
+            return respondWithAgentError(c, 400, [composeIssue("agent.notify_validation_error", { field: "body", received: parsedBody.body })], { legacyFields: { details: parsed.error } });
         }
         const { message, platform, platforms, priority, } = parsed.data;
         const normalizedPlatforms = platforms ?? (platform ? [platform] : undefined);
@@ -318,259 +273,130 @@ export function createAgentRoutes(deps) {
             dispatchId,
         });
     });
-    // POST /schedule — Register dynamic schedule
-    app.post("/schedule", async (c) => {
-        const parsedBody = await readJsonBody(c);
-        if (!parsedBody.ok)
-            return parsedBody.response;
-        const parsed = scheduleRequestSchema.safeParse(parsedBody.body);
-        if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
-        }
-        const { time, taskType, description, prompt, model, taskContext } = parsed.data;
-        // Normalize ISO8601 (possibly with timezone offset) to UTC SQLite format.
-        // Without this, "2026-04-05T07:00:00+09:00" would be stored as-is and
-        // ScheduleWatcher's lexicographic comparison (YYYY-MM-DD HH:MM:SS) would
-        // fail due to the 'T' separator being > ' ' in ASCII.
-        const parsedDate = new Date(time);
-        if (isNaN(parsedDate.getTime())) {
-            return c.json({ error: "invalid_time", details: "Cannot parse time as a valid date" }, 400);
-        }
-        // Reject times more than 1 minute in the past. This mirrors
-        // /schedule/dm and prevents accidental immediate catch-up tasks when a
-        // model resolves a relative time incorrectly.
-        if (parsedDate.getTime() < Date.now() - 60_000) {
-            return c.json({ error: "invalid_time", details: "Scheduled time is in the past" }, 400);
-        }
-        const scheduledForUtc = formatSqliteDatetime(parsedDate);
-        const enrichedTaskContext = enrichAgentPlanTaskContext(taskContext, parsedDate, description, deps);
-        const result = db
-            .prepare(`INSERT INTO agent_schedule (scheduled_for, task_type, task_description, task_prompt, task_context, model, status)
-         VALUES (?, ?, ?, ?, ?, ?, 'pending')`)
-            .run(scheduledForUtc, taskType, description, prompt ?? null, JSON.stringify(enrichedTaskContext), 
-        // NULL when the caller did NOT pin a model so the scheduler
-        // skips `event.requestedModel` and `process_backend_config` for
-        // the resolved ProcessKey is honoured. Forcing 'sonnet' here
-        // silently locked every scheduled task to the light tier.
-        model ?? null);
-        logger.info({ scheduleId: result.lastInsertRowid, taskType, scheduledFor: scheduledForUtc }, "Task scheduled");
-        // Surface long-horizon user-facing schedules in roadmap.md as
-        // `Scheduled:` entries. Internal/short-lived callers opt out via
-        // `taskContext.importance = "low"` or `"transient"`; strategic rows
-        // opt in regardless of horizon.
-        maybeTriggerRoadmapRefresh({ scheduledFor: scheduledForUtc, taskContext: enrichedTaskContext }, deps.triggerRoadmapRefresh, "scheduled_task_created");
-        // 2026-05 skill/API consistency: `/schedule/dm` returns
-        // `scheduledFor` so the caller can confirm the normalized UTC
-        // timestamp without a round-trip GET. The wake-task variant did
-        // not, forcing callers that wanted to log the scheduled time to
-        // either re-parse the input `time` themselves or query the table.
-        // Returning it here is additive and matches the DM variant.
-        return c.json({
-            status: "scheduled",
-            scheduleId: String(result.lastInsertRowid),
-            scheduledFor: scheduledForUtc,
-        });
-    });
-    // POST /schedule/dm — Schedule a direct DM (no agent needed)
-    app.post("/schedule/dm", async (c) => {
-        const parsedBody = await readJsonBody(c);
-        if (!parsedBody.ok)
-            return parsedBody.response;
-        const parsed = scheduleDmRequestSchema.safeParse(parsedBody.body);
-        if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
-        }
-        const { time, message, platform, platforms, importance } = parsed.data;
-        const parsedDate = new Date(time);
-        if (isNaN(parsedDate.getTime())) {
-            return c.json({ error: "invalid_time", details: "Cannot parse time as a valid date" }, 400);
-        }
-        // Reject times more than 1 minute in the past
-        if (parsedDate.getTime() < Date.now() - 60_000) {
-            return c.json({ error: "invalid_time", details: "Scheduled time is in the past" }, 400);
-        }
-        const scheduledForUtc = formatSqliteDatetime(parsedDate);
-        const dmTaskContext = {
-            platforms: platforms ?? (platform ? [platform] : null),
-            importance: importance ?? "transient",
-        };
-        const result = db
-            .prepare(
-        // task_type='dm' is consumed directly by `handleDirectDm` —
-        // the LLM never runs, so `model` is meaningless. Persist NULL
-        // so a reader can't mistake the row for a model-pinned task.
-        `INSERT INTO agent_schedule (scheduled_for, task_type, task_description, task_context, model, status)
-         VALUES (?, 'dm', ?, ?, NULL, 'pending')`)
-            .run(scheduledForUtc, message, JSON.stringify(dmTaskContext));
-        // DM-scheduled reminders are transient by default so short pings do
-        // not pollute roadmap.md. Callers can opt in with `importance`.
-        maybeTriggerRoadmapRefresh({ scheduledFor: scheduledForUtc, taskContext: dmTaskContext }, deps.triggerRoadmapRefresh, "scheduled_task_created");
-        return c.json({
-            status: "scheduled",
-            scheduleId: String(result.lastInsertRowid),
-            scheduledFor: scheduledForUtc,
-        });
-    });
-    // GET /schedule — List scheduled items
-    app.get("/schedule", (c) => {
-        const statusParam = c.req.query("status") ?? "pending,running";
-        const roadmapEligible = c.req.query("roadmapEligible") === "true" ||
-            c.req.query("roadmapEligible") === "1";
-        const statuses = statusParam.split(",").map((s) => s.trim()).filter(Boolean);
-        const allowed = new Set(["pending", "running", "completed", "failed", "skipped"]);
-        for (const s of statuses) {
-            if (!allowed.has(s)) {
-                return c.json({ error: "invalid_status", details: `Unknown status: ${s}` }, 400);
-            }
-        }
-        const placeholders = statuses.map(() => "?").join(",");
-        const where = [`status IN (${placeholders})`];
-        const queryParams = [...statuses];
-        if (roadmapEligible) {
-            const normalHorizonCutoff = formatSqliteDatetime(new Date(Date.now() + 7 * 24 * 60 * 60 * 1000));
-            where.push(`(
-          json_extract(task_context, '$.importance') = 'strategic'
-          OR (
-            (
-              json_extract(task_context, '$.importance') IS NULL
-              OR json_extract(task_context, '$.importance') NOT IN ('transient', 'low', 'strategic')
-            )
-            AND scheduled_for > ?
-          )
-        )`);
-            queryParams.push(normalHorizonCutoff);
-        }
-        const rows = db
-            .prepare(`SELECT id, scheduled_for, task_type, task_description, task_prompt, task_context, model, status, created_at
-         FROM agent_schedule
-         WHERE ${where.join(" AND ")}
-         ORDER BY scheduled_for ASC
-         LIMIT 50`)
-            .all(...queryParams);
-        const items = rows.map((r) => ({
-            id: r.id,
-            scheduledFor: r.scheduled_for,
-            taskType: r.task_type,
-            description: r.task_description,
-            prompt: r.task_prompt,
-            status: r.status,
-            model: r.model,
-            taskContext: parseTaskContextJson(r.task_context),
-            createdAt: r.created_at,
-        }));
-        return c.json({ items });
-    });
-    // PATCH /schedule/:id — Edit a pending scheduled item
-    app.patch("/schedule/:id", async (c) => {
-        const id = Number(c.req.param("id"));
-        if (!Number.isInteger(id) || id <= 0) {
-            return c.json({ error: "invalid_id" }, 400);
+    // PATCH /agent-actions/self — Agent-self-reported structured metadata.
+    //
+    // docs/design/appendices/morning-routine-optimization.md §"PATCH
+    // /api/agent-actions/self". Lets the currently-running agent session
+    // write structured metadata into its own `agent_actions` row, so the
+    // daemon's ⑥ AgentJournalAppender (and other post-hoc consumers)
+    // read structured data rather than parsing LLM final-text prose.
+    //
+    // Auth: the session's per-run identity comes from
+    // `x-pa-event-correlation-id` (matches `agent_actions.event_id`) and
+    // `x-process-key` (matches `agent_actions.action_type`), both auto-
+    // injected by pa-api from dispatcher-set env vars. Aitne's threat
+    // model is single-owner local-only (127.0.0.1 daemon, sole LLM
+    // caller, UUID correlation IDs); the morning-routine-optimization
+    // rev4 banner records why per-run token binding / cross-row 403 was
+    // withdrawn rather than shipped. Lookup miss → 404
+    // `agent_actions.session_row_not_found`.
+    //
+    // Merge: the body's `metadata` slot is shallow-merged into the row's
+    // existing `metadata` JSON column. Repeated PATCHes during the same
+    // session accumulate (later keys win).
+    app.patch("/agent-actions/self", async (c) => {
+        const correlationId = c.req.header("x-pa-event-correlation-id");
+        const processKey = c.req.header("x-process-key");
+        const headerIssues = [];
+        if (!correlationId || correlationId.trim().length === 0) {
+            headerIssues.push(composeIssue("agent_actions.session_identity_missing", {
+                field: "headers.x-pa-event-correlation-id",
+                received: correlationId ?? "<missing>",
+            }));
+        }
+        if (!processKey || processKey.trim().length === 0) {
+            headerIssues.push(composeIssue("agent_actions.session_identity_missing", {
+                field: "headers.x-process-key",
+                received: processKey ?? "<missing>",
+            }));
+        }
+        if (headerIssues.length > 0) {
+            return respondWithAgentError(c, 400, headerIssues);
         }
         const parsedBody = await readJsonBody(c);
         if (!parsedBody.ok)
             return parsedBody.response;
-        const parsed = scheduleUpdateRequestSchema.safeParse(parsedBody.body);
-        if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
-        }
+        if (!parsedBody.body
+            || typeof parsedBody.body !== "object"
+            || Array.isArray(parsedBody.body)) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("agent_actions.body_not_object", {
+                    field: "$",
+                    received: parsedBody.body,
+                }),
+            ]);
+        }
+        const body = parsedBody.body;
+        if (!body.metadata
+            || typeof body.metadata !== "object"
+            || Array.isArray(body.metadata)) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("agent_actions.metadata_field_invalid", {
+                    field: "metadata",
+                    received: body.metadata,
+                }),
+            ]);
+        }
+        // body.metadata has already round-tripped through readJsonBody's
+        // JSON.parse, so its shape is guaranteed plain JSON (no Functions,
+        // Symbols, BigInts, or cyclic refs). The cast is sound.
+        const metadataPatch = body.metadata;
+        // Find the most recent in-flight row matching the session's identity.
+        // The dispatcher's standard pattern is to INSERT after a session
+        // completes, so this lookup only succeeds when an upstream caller
+        // (Phase 5/6 orchestrator) has pre-inserted an in_progress row.
+        // Until then this endpoint returns 404 — a documented expected state
+        // for Phase 1 callers who provide the in_progress row in tests.
+        //
+        // `result = 'in_progress'` is part of the filter so retry chains (a
+        // failed older row + an in_progress newer row sharing identity) can't
+        // accidentally resolve to a terminal row, and so a delayed shim call
+        // arriving after the session has already settled to success/failed
+        // does not overwrite the final metadata. The SKILL.md documents this
+        // explicitly: "or it has already settled to a terminal result."
         const row = db
-            .prepare("SELECT id, status, task_type FROM agent_schedule WHERE id = ?")
-            .get(id);
+            .prepare(`SELECT id, metadata
+         FROM agent_actions
+         WHERE event_id = ? AND action_type = ?
+           AND result = 'in_progress'
+         ORDER BY started_at DESC, id DESC
+         LIMIT 1`)
+            .get(correlationId, processKey);
         if (!row) {
-            return c.json({ error: "not_found" }, 404);
-        }
-        if (row.status !== "pending") {
-            return c.json({ error: "conflict", details: `Cannot edit item with status '${row.status}'. Only 'pending' items can be edited.` }, 409);
-        }
-        // Type-field validation: description ↔ wake/escalation, message ↔ dm,
-        // prompt forbidden on dm (direct DMs do not run an agent so the prompt
-        // override has nothing to override).
-        if (parsed.data.description !== undefined && row.task_type === "dm") {
-            return c.json({ error: "invalid_field", details: "'description' cannot be set on dm-type schedules. Use 'message' instead." }, 400);
-        }
-        if (parsed.data.message !== undefined && row.task_type !== "dm") {
-            return c.json({ error: "invalid_field", details: "'message' can only be set on dm-type schedules. Use 'description' instead." }, 400);
-        }
-        if (parsed.data.prompt !== undefined && row.task_type === "dm") {
-            return c.json({ error: "invalid_field", details: "'prompt' cannot be set on dm-type schedules — direct DMs do not run an agent." }, 400);
-        }
-        const updates = [];
-        const values = [];
-        if (parsed.data.time !== undefined) {
-            const parsedDate = new Date(parsed.data.time);
-            if (isNaN(parsedDate.getTime())) {
-                return c.json({ error: "invalid_time", details: "Cannot parse time as a valid date" }, 400);
+            return respondWithAgentError(c, 404, [
+                composeIssue("agent_actions.session_row_not_found", {
+                    field: "headers.x-process-key",
+                    received: { correlationId, processKey },
+                }),
+            ]);
+        }
+        // Shallow-merge with the existing metadata JSON. The column has
+        // DEFAULT '{}' so the parse is safe; a corrupted JSON (manual DB
+        // edit, e.g.) falls back to an empty object so the PATCH still
+        // succeeds — better than 500ing and losing the agent's write.
+        let existing = {};
+        if (row.metadata) {
+            try {
+                const parsedJson = JSON.parse(row.metadata);
+                if (parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson)) {
+                    existing = parsedJson;
+                }
             }
-            // Reject past times for dm type (consistent with POST /schedule/dm)
-            if (row.task_type === "dm" && parsedDate.getTime() < Date.now() - 60_000) {
-                return c.json({ error: "invalid_time", details: "Scheduled time is in the past" }, 400);
+            catch (err) {
+                logger.warn({ err, rowId: row.id }, "agent_actions.metadata is not valid JSON — overwriting with PATCH body");
             }
-            updates.push("scheduled_for = ?");
-            values.push(formatSqliteDatetime(parsedDate));
-        }
-        if (parsed.data.description !== undefined) {
-            updates.push("task_description = ?");
-            values.push(parsed.data.description);
-        }
-        if (parsed.data.message !== undefined) {
-            updates.push("task_description = ?");
-            values.push(parsed.data.message);
-        }
-        // `prompt: null` is the explicit clear (revert to using task_description
-        // as the agent body). `prompt: <string>` sets an override. `undefined` =
-        // no change. The dm-type rejection is handled in the type-field block above.
-        if (parsed.data.prompt !== undefined) {
-            updates.push("task_prompt = ?");
-            values.push(parsed.data.prompt);
-        }
-        if (parsed.data.model !== undefined) {
-            updates.push("model = ?");
-            values.push(parsed.data.model);
         }
-        if (parsed.data.taskContext !== undefined) {
-            updates.push("task_context = ?");
-            values.push(JSON.stringify(parsed.data.taskContext));
-        }
-        // This branch is unreachable: the zod refine above requires at least one
-        // field to be defined — so updates can only be empty if all field-update
-        // blocks above are individually skipped, which contradicts the refine.
-        /* c8 ignore start */
-        if (updates.length === 0) {
-            return c.json({ error: "no_changes", details: "No valid fields to update" }, 400);
-        }
-        /* c8 ignore stop */
-        // Optimistic lock: only update if still pending
-        values.push(id);
-        const result = db.prepare(`UPDATE agent_schedule SET ${updates.join(", ")} WHERE id = ? AND status = 'pending'`).run(...values);
-        // Unreachable in unit tests: requires a concurrent scheduler tick to
-        // change status from 'pending' to 'running' between the SELECT and this
-        // UPDATE. The prior status !== 'pending' check (line ~660) catches the
-        // row-not-found case; this fires only on a true time-of-check/time-of-use
-        // race that cannot be reproduced without process-level suspension.
-        /* c8 ignore start */
-        if (result.changes === 0) {
-            return c.json({ error: "conflict", details: "Item is no longer pending (may have been picked up by scheduler)" }, 409);
-        }
-        /* c8 ignore stop */
-        return c.json({ status: "updated", id });
-    });
-    // DELETE /schedule/:id — Cancel a pending scheduled item
-    app.delete("/schedule/:id", (c) => {
-        const id = Number(c.req.param("id"));
-        if (!Number.isInteger(id) || id <= 0) {
-            return c.json({ error: "invalid_id" }, 400);
-        }
-        const row = db
-            .prepare("SELECT id, status FROM agent_schedule WHERE id = ?")
-            .get(id);
-        if (!row) {
-            return c.json({ error: "not_found" }, 404);
-        }
-        if (row.status !== "pending") {
-            return c.json({ error: "conflict", details: `Cannot cancel item with status '${row.status}'. Only 'pending' items can be cancelled.` }, 409);
-        }
-        db.prepare("UPDATE agent_schedule SET status = 'skipped' WHERE id = ?").run(id);
-        return c.json({ status: "cancelled", id });
+        const merged = { ...existing, ...metadataPatch };
+        db.prepare(`UPDATE agent_actions SET metadata = ? WHERE id = ?`).run(JSON.stringify(merged), row.id);
+        logger.info({
+            rowId: row.id,
+            keysPatched: Object.keys(metadataPatch),
+        }, "Agent self-reported structured metadata patched");
+        return c.json({
+            ok: true,
+            id: row.id,
+            metadata: merged,
+        });
     });
     // POST /agent/regenerate — Trigger context file regeneration
     app.post("/agent/regenerate", async (c) => {
@@ -579,7 +405,7 @@ export function createAgentRoutes(deps) {
             return parsedBody.response;
         const target = parsedBody.body.target;
         if (!target || !["today", "roadmap"].includes(target)) {
-            return c.json({ error: "Invalid target. Must be one of: today, roadmap" }, 400);
+            return respondWithAgentError(c, 400, [composeIssue("agent.invalid_target", { field: "target", received: target ?? "<missing>" })], { legacyErrorCode: "Invalid target. Must be one of: today, roadmap" });
         }
         if (target === "roadmap") {
             // Emit the real `routine.roadmap_refresh` event (bypassing the
@@ -588,7 +414,12 @@ export function createAgentRoutes(deps) {
             // no longer ship an ad-hoc prompt that short-circuits to a single
             // section write.
             if (!deps.triggerRoadmapRefresh) {
-                return c.json({ error: "Roadmap refresh trigger not available" }, 503);
+                return respondWithAgentError(c, 503, [
+                    composeIssue("agent.roadmap_refresh_unavailable", {
+                        field: "triggerRoadmapRefresh",
+                        received: "<unavailable>",
+                    }),
+                ], { legacyErrorCode: "Roadmap refresh trigger not available" });
             }
             deps.triggerRoadmapRefresh("dashboard_regenerate", { bypassDedup: true });
             logger.info({ target }, "Regeneration triggered");
@@ -599,7 +430,12 @@ export function createAgentRoutes(deps) {
         // delegated MCP tool, depending on integration mode) so this handler
         // does not need a local CalendarService.
         if (!deps.eventBus) {
-            return c.json({ error: "Event bus not available" }, 500);
+            return respondWithAgentError(c, 500, [
+                composeIssue("agent.event_bus_unavailable", {
+                    field: "eventBus",
+                    received: "<unavailable>",
+                }),
+            ], { legacyErrorCode: "Event bus not available" });
         }
         const event = {
             ...createEvent({
@@ -620,7 +456,7 @@ export function createAgentRoutes(deps) {
             return parsedBody.response;
         const parsed = actionLogRequestSchema.safeParse(parsedBody.body);
         if (!parsed.success) {
-            return c.json({ error: "validation_error", details: parsed.error }, 400);
+            return respondWithAgentError(c, 400, [composeIssue("agent.action_log_validation_error", { field: "body", received: parsedBody.body })], { legacyFields: { details: parsed.error } });
         }
         const { actionType, detail, result: actionResult } = parsed.data;
         const insertResult = db.prepare(`INSERT INTO agent_actions (action_type, trigger, result, detail, started_at)
@@ -631,6 +467,13 @@ export function createAgentRoutes(deps) {
         }
         return c.json({ status: "logged" });
     });
+    // Schedule cluster (POST/GET/PATCH/DELETE /schedule, /schedule/batch,
+    // /schedule/dm, /schedule/:id) is registered from agent-schedule.ts.
+    // Per docs/design/appendices/api-route-decomposition.md §5.5 the split
+    // is partial — only the schedule routes were extracted, and the public
+    // `createAgentRoutes` factory remains the single Hono entry registered
+    // in server.ts.
+    registerAgentScheduleRoutes(app, deps);
     return app;
 }
 function parsePositiveIntegerHeader(value) {