@aitne/daemon 0.1.7 → 0.1.9

package/dist/bootstrap/schedule-helpers.d.ts

@@ -10,9 +10,130 @@
  */
 import type Database from "better-sqlite3";
 import type { AgentConfig } from "../config.js";
+/**
+ * Days of week on which the boot-time catchup will fire an unrun
+ * `routine.weekly_review`. Friday is the canonical slot; Saturday and
+ * Sunday extend the window so a Fri-evening daemon outage can still
+ * land the week's file before the new ISO week's morning_routines
+ * begin reading it via `<previous_week>`.
+ *
+ * Exported for tests and for any future cross-package introspection
+ * (e.g. dashboard "next catchup" surface). Reads only — mutating this
+ * set would silently change scheduling behaviour.
+ */
+export declare const WEEKLY_REVIEW_CATCHUP_DAYS_OF_WEEK: Set<number>;
 export declare function getDueCatchupRoutines(db: Database.Database, config: AgentConfig, agentDayStartUtc: string, agentDayEndUtc: string, now: Date): string[];
+/**
+ * Decide whether the boot sequence should immediately fire one
+ * catch-up `routine.hourly_check` (because the cron callback never ran
+ * for the current slot — typically because the host was asleep / the
+ * daemon was stopped during the slot window).
+ *
+ * Slot math mirrors `shouldFireHourlyTickAt` in `scheduler.ts` so the
+ * catch-up always lands on the same slot the cron would have fired at.
+ *
+ * **Wrap-around active hours are NOT supported.** The active-hours
+ * window is interpreted as the contiguous range
+ * `[activeStartHour, activeEndHour)`. A user-set configuration where
+ * `activeStartHour > activeEndHour` (e.g. start=22, end=4 — wanting
+ * "active overnight") would short-circuit on the
+ * `local.hours >= activeEndHour` branch for every hour after 04:00,
+ * silently disabling hourly catch-up. The runtime-settings validator
+ * does not currently cross-check the two values (CLAUDE.md notes the
+ * gap under "Active-hours and quiet-hours strings are validated
+ * independently … there is no cross-window non-overlap check today").
+ * Operators with overnight workloads should set
+ * `activeStartHour=0, activeEndHour=24` (covers the full day) rather
+ * than attempting wrap-around. If wrap-around becomes a real
+ * requirement, the fix is to either (a) reject `start > end` at
+ * config-write time, or (b) split the window into two non-wrap
+ * ranges in the same call site that consumes them.
+ */
 export declare function shouldCatchUpHourlyCheck(db: Database.Database, config: AgentConfig, now: Date): boolean;
 export declare function getProgressMinutesForHour(hour: number, dayBoundaryHour: number): number;
 export declare function hasFreshAgentDayTodayMd(todayMdPath: string, timezone: string | undefined, dayBoundaryHour: number, now?: Date): boolean;
+/**
+ * Did `routine.morning_routine` complete successfully within the current
+ * agent-day window? Used by the pre-routine gate that fronts hourly_check
+ * and the review routines (evening / weekly / monthly) so they refuse to
+ * run before the day has been properly opened.
+ *
+ * Authoritative signal: `agent_actions` rather than today.md, because
+ * today.md can be mutated by the user (manual rollover, DM-driven edits)
+ * and we hit exactly that failure mode on 2026-05-14 — the Mac slept
+ * through the 04:00 cron, the user manually rolled today.md to the new
+ * date, and `hasFreshAgentDayTodayMd` then falsely reported "morning
+ * routine done". `agent_actions.result='success'` never lies.
+ *
+ * Pure: takes db + agent-day config, returns boolean.
+ */
+export declare function morningRoutineRanToday(db: Database.Database, agentDayConfig: {
+    timezone?: string;
+    dayBoundaryHour: number;
+}, now?: Date): boolean;
+/**
+ * Default threshold for the morning-routine stall watchdog. A wake row
+ * older than this without a matching `agent_actions.result='success'`
+ * row triggers an owner DM. 120 min is generous enough to cover an
+ * unusually slow routine (multiple Sonnet turns + slow integrations)
+ * while still alerting before the entire agent-day is blocked.
+ *
+ * Operators with atypically slow morning routines can override via the
+ * `morning_routine.config` runtime_state row — see
+ * `readMorningRoutineStallThresholdMinutes`. A floor of 15 minutes is
+ * applied so an operator typo cannot flood the DM channel.
+ */
+export declare const MORNING_ROUTINE_STALL_THRESHOLD_MINUTES = 120;
+/**
+ * Resolve the effective stall-threshold minutes from runtime_state, with
+ * the default and the operator-side floor applied. Mirrors the
+ * `invokerTimeoutSeconds` override path in `delegated-sync-worker.ts` so
+ * the two operator-tunable thresholds share a shape:
+ *
+ *   runtime_state row "morning_routine.config" with
+ *     `{ "stallThresholdMinutes": <positive number> }`
+ *
+ * Missing row, corrupt JSON, or a non-positive value falls through to
+ * the built-in default. Sub-floor values clamp up to the floor.
+ *
+ * Pure read — never writes. Safe to call on every hourly tick.
+ */
+export declare const MORNING_ROUTINE_CONFIG_KEY = "morning_routine.config";
+export declare function readMorningRoutineStallThresholdMinutes(db: Database.Database): number;
+export interface StalledMorningRoutineWake {
+    /** agent_schedule.id of the offending row. */
+    id: number;
+    /** Sqlite timestamp the row was created at (UTC). */
+    createdAt: string;
+    /** Sqlite timestamp the row was scheduled for (UTC). */
+    scheduledFor: string;
+    /** Current row status (pending / running). */
+    status: string;
+    /** Minutes between `createdAt` and `now`, rounded. */
+    ageMinutes: number;
+}
+/**
+ * Detect when the morning-routine wake row has been queued for too long
+ * without producing a successful `agent_actions` row. Returns the
+ * offending row's metadata if stalled, null when the system is healthy.
+ *
+ * Pairs with `queueMorningRoutineWake` + the hourly-check pre-routine
+ * gate. The dedup that keeps `queueMorningRoutineWake` from re-inserting
+ * means a stuck wake row leaves the system in a silent freeze — the gate
+ * skips `routine.hourly_check`, `routine.evening_review`, etc. forever
+ * without surfacing to the user. This helper is the externally visible
+ * signal the watchdog uses to break the silence.
+ *
+ * Returns null in three cases:
+ *   1. The morning routine already wrote a `result='success'` row today.
+ *   2. No `task_type='wake'` row for `routine='morning_routine'` exists
+ *      in `pending`/`running` status.
+ *   3. The oldest such row is younger than `thresholdMinutes`.
+ *
+ * Pure: takes db + threshold + clock, returns row metadata.
+ */
+export declare function getStalledMorningRoutineWake(db: Database.Database, agentDayConfig: {
+    timezone?: string;
+    dayBoundaryHour: number;
+}, thresholdMinutes: number, now?: Date): StalledMorningRoutineWake | null;
 export declare function readSkillCurationCadence(db: Database.Database): "daily" | "weekly" | "monthly";
-//# sourceMappingURL=schedule-helpers.d.ts.map

package/dist/bootstrap/schedule-helpers.js

@@ -11,6 +11,18 @@
 import { existsSync, readFileSync } from "node:fs";
 import { formatSqliteDatetime, getAgentDayBoundsUtc, getAgentDayDateStr, getAgentDayProgressMinutes, nowInTimezone, parseSqliteUtcMs, } from "@aitne/shared";
 import { hasActionInWindow } from "../core/schedule-maintenance.js";
+/**
+ * Days of week on which the boot-time catchup will fire an unrun
+ * `routine.weekly_review`. Friday is the canonical slot; Saturday and
+ * Sunday extend the window so a Fri-evening daemon outage can still
+ * land the week's file before the new ISO week's morning_routines
+ * begin reading it via `<previous_week>`.
+ *
+ * Exported for tests and for any future cross-package introspection
+ * (e.g. dashboard "next catchup" surface). Reads only — mutating this
+ * set would silently change scheduling behaviour.
+ */
+export const WEEKLY_REVIEW_CATCHUP_DAYS_OF_WEEK = new Set([5, 6, 0]);
 export function getDueCatchupRoutines(db, config, agentDayStartUtc, agentDayEndUtc, now) {
     const tz = config.timezone || undefined;
     const progressMinutes = getAgentDayProgressMinutes(tz, config.dayBoundaryHour, now);
@@ -25,16 +37,70 @@ export function getDueCatchupRoutines(db, config, agentDayStartUtc, agentDayEndU
     if (!hasActionInWindow(db, "routine.evening_review", agentDayStartUtc, agentDayEndUtc)) {
         routines.push("evening_review");
     }
-    if (agentDayLocal.dayOfWeek === 5 &&
-        !hasActionInWindow(db, "routine.weekly_review", agentDayStartUtc, agentDayEndUtc)) {
-        routines.push("weekly_review");
+    // `docs/design/appendices/weekly-next-week-leverage.md` §6 — catchup
+    // window for weekly_review extends Friday through Sunday. The
+    // `<previous_week>` injection wired into every Mon–Sun morning_routine
+    // assumes `weekly/YYYY-W{prev}.md` exists, so a Fri-evening daemon
+    // outage that wedges the routine until the weekend must still produce
+    // the file before the new ISO week begins. Mon–Thu catchup is
+    // intentionally out of scope: by then the new week has its own daily
+    // files and a backfilled review would distort the morning-routine
+    // signal it feeds into.
+    //
+    // Suppression must look back to Friday's agent-day start — not the
+    // current agent-day — otherwise a successful Friday fire would not
+    // suppress the Saturday or Sunday catchup, causing a double-fire on
+    // the weekend after a healthy Friday run. Step back
+    // `(dayOfWeek - 5 + 7) % 7` days from the current agent-day boundary
+    // to land on the matching Friday boundary.
+    //
+    // dayOfWeek convention (from `nowInTimezone`): 0 = Sunday,
+    // 5 = Friday, 6 = Saturday.
+    if (WEEKLY_REVIEW_CATCHUP_DAYS_OF_WEEK.has(agentDayLocal.dayOfWeek)) {
+        const daysSinceFriday = (agentDayLocal.dayOfWeek - 5 + 7) % 7;
+        const fridayWindowStartMs = agentDayStartMs - daysSinceFriday * 24 * 60 * 60 * 1000;
+        const fridayWindowStartUtc = formatSqliteDatetime(new Date(fridayWindowStartMs));
+        if (!hasActionInWindow(db, "routine.weekly_review", fridayWindowStartUtc, agentDayEndUtc)) {
+            routines.push("weekly_review");
+        }
     }
-    if (tomorrowLocal.day === 1 &&
+    // Monthly catchup is gated by the same kill switch as the scheduler
+    // cron (see scheduler.ts comment block). Default OFF pre-release until
+    // the Mirror+Prune redesign; operators opt in via
+    // PA_MONTHLY_REVIEW_ENABLED or PATCH /api/config.
+    if (config.monthlyReviewEnabled &&
+        tomorrowLocal.day === 1 &&
         !hasActionInWindow(db, "routine.monthly_review", agentDayStartUtc, agentDayEndUtc)) {
         routines.push("monthly_review");
     }
     return routines;
 }
+/**
+ * Decide whether the boot sequence should immediately fire one
+ * catch-up `routine.hourly_check` (because the cron callback never ran
+ * for the current slot — typically because the host was asleep / the
+ * daemon was stopped during the slot window).
+ *
+ * Slot math mirrors `shouldFireHourlyTickAt` in `scheduler.ts` so the
+ * catch-up always lands on the same slot the cron would have fired at.
+ *
+ * **Wrap-around active hours are NOT supported.** The active-hours
+ * window is interpreted as the contiguous range
+ * `[activeStartHour, activeEndHour)`. A user-set configuration where
+ * `activeStartHour > activeEndHour` (e.g. start=22, end=4 — wanting
+ * "active overnight") would short-circuit on the
+ * `local.hours >= activeEndHour` branch for every hour after 04:00,
+ * silently disabling hourly catch-up. The runtime-settings validator
+ * does not currently cross-check the two values (CLAUDE.md notes the
+ * gap under "Active-hours and quiet-hours strings are validated
+ * independently … there is no cross-window non-overlap check today").
+ * Operators with overnight workloads should set
+ * `activeStartHour=0, activeEndHour=24` (covers the full day) rather
+ * than attempting wrap-around. If wrap-around becomes a real
+ * requirement, the fix is to either (a) reject `start > end` at
+ * config-write time, or (b) split the window into two non-wrap
+ * ranges in the same call site that consumes them.
+ */
 export function shouldCatchUpHourlyCheck(db, config, now) {
     if (!config.hourlyCheckEnabled) {
         return false;
@@ -72,10 +138,145 @@ export function hasFreshAgentDayTodayMd(todayMdPath, timezone, dayBoundaryHour,
     if (!existsSync(todayMdPath)) {
         return false;
     }
-    const firstLine = readFileSync(todayMdPath, "utf-8").split("\n")[0] ?? "";
+    // `String.split` always returns a non-empty array, so index 0 is
+    // defined for any contents — including the empty string. A `?? ""`
+    // fallback would be dead defensive code.
+    const firstLine = readFileSync(todayMdPath, "utf-8").split("\n")[0];
     const today = getAgentDayDateStr(timezone, dayBoundaryHour, now);
     return firstLine.includes(today);
 }
+/**
+ * Did `routine.morning_routine` complete successfully within the current
+ * agent-day window? Used by the pre-routine gate that fronts hourly_check
+ * and the review routines (evening / weekly / monthly) so they refuse to
+ * run before the day has been properly opened.
+ *
+ * Authoritative signal: `agent_actions` rather than today.md, because
+ * today.md can be mutated by the user (manual rollover, DM-driven edits)
+ * and we hit exactly that failure mode on 2026-05-14 — the Mac slept
+ * through the 04:00 cron, the user manually rolled today.md to the new
+ * date, and `hasFreshAgentDayTodayMd` then falsely reported "morning
+ * routine done". `agent_actions.result='success'` never lies.
+ *
+ * Pure: takes db + agent-day config, returns boolean.
+ */
+export function morningRoutineRanToday(db, agentDayConfig, now) {
+    const { start } = getAgentDayBoundsUtc(agentDayConfig.timezone, agentDayConfig.dayBoundaryHour, now);
+    const row = db
+        .prepare(`SELECT 1
+         FROM agent_actions
+        WHERE action_type = 'routine.morning_routine'
+          AND result = 'success'
+          AND started_at >= ?
+        LIMIT 1`)
+        .get(start);
+    return row !== undefined;
+}
+/**
+ * Default threshold for the morning-routine stall watchdog. A wake row
+ * older than this without a matching `agent_actions.result='success'`
+ * row triggers an owner DM. 120 min is generous enough to cover an
+ * unusually slow routine (multiple Sonnet turns + slow integrations)
+ * while still alerting before the entire agent-day is blocked.
+ *
+ * Operators with atypically slow morning routines can override via the
+ * `morning_routine.config` runtime_state row — see
+ * `readMorningRoutineStallThresholdMinutes`. A floor of 15 minutes is
+ * applied so an operator typo cannot flood the DM channel.
+ */
+export const MORNING_ROUTINE_STALL_THRESHOLD_MINUTES = 120;
+const MIN_MORNING_ROUTINE_STALL_THRESHOLD_MINUTES = 15;
+/**
+ * Resolve the effective stall-threshold minutes from runtime_state, with
+ * the default and the operator-side floor applied. Mirrors the
+ * `invokerTimeoutSeconds` override path in `delegated-sync-worker.ts` so
+ * the two operator-tunable thresholds share a shape:
+ *
+ *   runtime_state row "morning_routine.config" with
+ *     `{ "stallThresholdMinutes": <positive number> }`
+ *
+ * Missing row, corrupt JSON, or a non-positive value falls through to
+ * the built-in default. Sub-floor values clamp up to the floor.
+ *
+ * Pure read — never writes. Safe to call on every hourly tick.
+ */
+export const MORNING_ROUTINE_CONFIG_KEY = "morning_routine.config";
+export function readMorningRoutineStallThresholdMinutes(db) {
+    let raw;
+    try {
+        raw = db
+            .prepare(`SELECT value_json FROM runtime_state WHERE key = ?`)
+            .get(MORNING_ROUTINE_CONFIG_KEY);
+    }
+    catch {
+        return MORNING_ROUTINE_STALL_THRESHOLD_MINUTES;
+    }
+    if (!raw)
+        return MORNING_ROUTINE_STALL_THRESHOLD_MINUTES;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.value_json);
+    }
+    catch {
+        return MORNING_ROUTINE_STALL_THRESHOLD_MINUTES;
+    }
+    const value = parsed.stallThresholdMinutes;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return MORNING_ROUTINE_STALL_THRESHOLD_MINUTES;
+    }
+    return Math.max(value, MIN_MORNING_ROUTINE_STALL_THRESHOLD_MINUTES);
+}
+/**
+ * Detect when the morning-routine wake row has been queued for too long
+ * without producing a successful `agent_actions` row. Returns the
+ * offending row's metadata if stalled, null when the system is healthy.
+ *
+ * Pairs with `queueMorningRoutineWake` + the hourly-check pre-routine
+ * gate. The dedup that keeps `queueMorningRoutineWake` from re-inserting
+ * means a stuck wake row leaves the system in a silent freeze — the gate
+ * skips `routine.hourly_check`, `routine.evening_review`, etc. forever
+ * without surfacing to the user. This helper is the externally visible
+ * signal the watchdog uses to break the silence.
+ *
+ * Returns null in three cases:
+ *   1. The morning routine already wrote a `result='success'` row today.
+ *   2. No `task_type='wake'` row for `routine='morning_routine'` exists
+ *      in `pending`/`running` status.
+ *   3. The oldest such row is younger than `thresholdMinutes`.
+ *
+ * Pure: takes db + threshold + clock, returns row metadata.
+ */
+export function getStalledMorningRoutineWake(db, agentDayConfig, thresholdMinutes, now) {
+    const reference = now ?? new Date();
+    if (morningRoutineRanToday(db, agentDayConfig, reference)) {
+        return null;
+    }
+    const row = db
+        .prepare(`SELECT id,
+              created_at AS createdAt,
+              scheduled_for AS scheduledFor,
+              status
+         FROM agent_schedule
+        WHERE task_type = 'wake'
+          AND status IN ('pending', 'running')
+          AND json_extract(task_context, '$.routine') = 'morning_routine'
+        ORDER BY created_at ASC
+        LIMIT 1`)
+        .get();
+    if (!row)
+        return null;
+    const createdMs = parseSqliteUtcMs(row.createdAt);
+    const ageMinutes = Math.floor((reference.getTime() - createdMs) / 60_000);
+    if (ageMinutes < thresholdMinutes)
+        return null;
+    return {
+        id: row.id,
+        createdAt: row.createdAt,
+        scheduledFor: row.scheduledFor,
+        status: row.status,
+        ageMinutes,
+    };
+}
 // P22 — read the operator's chosen cadence for skill curation runs.
 // Mirrors the helper in `core/scheduler.ts` so the dispatcher hook here can
 // resolve cadence at runtime without crossing module boundaries.
@@ -93,4 +294,3 @@ export function readSkillCurationCadence(db) {
         return "weekly";
     }
 }
-//# sourceMappingURL=schedule-helpers.js.map

package/dist/bootstrap/services.d.ts

@@ -57,4 +57,3 @@ export interface ServiceReloaders {
     reloadGitHubService(): Promise<void>;
 }
 export declare function createServiceReloaders(deps: BootstrapServiceDeps): ServiceReloaders;
-//# sourceMappingURL=services.d.ts.map

package/dist/bootstrap/services.js

@@ -187,16 +187,7 @@ export function createServiceReloaders(deps) {
         if (!token) {
             return;
         }
-        const githubService = new GitHubService(token, webhookSecret);
-        try {
-            await githubService.init();
-            services.github = githubService;
-        }
-        catch (err) {
-            const msg = err.message;
-            logger.error({ error: msg }, "GitHub service init failed, continuing without it");
-            services.errors.github = msg;
-        }
+        services.github = new GitHubService(token, webhookSecret);
     }
     return {
         refreshGoogleSecretState,
@@ -206,4 +197,3 @@ export function createServiceReloaders(deps) {
         reloadGitHubService,
     };
 }
-//# sourceMappingURL=services.js.map

package/dist/config.d.ts

@@ -117,7 +117,7 @@ export declare function validateExternalObsidianVaultPath(rawPath: string, confi
  * vault must also contain at least one canonical context marker so the
  * daemon does not resume writes into an empty or wrong directory.
  *
- * Bootstrapping bypass: if `rules/management.md` doesn't exist yet, setup
+ * Bootstrapping bypass: if `policies/management.md` doesn't exist yet, setup
  * hasn't run; honoring a null primaryVaultPath would break the initial-DM
  * setup flow (which writes via `/api/context/*`, gated by the 503
  * middleware). Skip degraded-mode entirely until setup completes. This
@@ -133,4 +133,3 @@ export declare function getDbPath(config: Pick<BootstrapConfig, "dataDir">): str
 export declare function getLogsDir(config: Pick<BootstrapConfig, "dataDir">): string;
 export declare function getTmpDir(config: Pick<BootstrapConfig, "dataDir">): string;
 export {};
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -3,7 +3,7 @@ import { config as loadDotenv } from "dotenv";
 import { basename, dirname, isAbsolute, normalize, parse, resolve } from "node:path";
 import { homedir } from "node:os";
 import { accessSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
-import { DEFAULT_AGENT_DISPLAY_NAME, normalizeAgentDisplayName, } from "@aitne/shared";
+import { DEFAULT_AGENT_DISPLAY_NAME, DEFAULT_API_PORT, normalizeAgentDisplayName, } from "@aitne/shared";
 import { RUNTIME_SETTING_KEYS, runtimeSettingsSchema, } from "./settings/runtime-settings.js";
 import { clearDegradedMode, getDegradedMode, isDegraded, isSetupCompleted, markSetupCompleted, setDegradedMode, } from "./db/runtime-state.js";
 import { CONTEXT_RELATIVE_PATHS } from "./core/context-paths.js";
@@ -18,7 +18,7 @@ function envOrDefault(key, defaultValue) {
 const bootstrapConfigSchema = z.object({
     dataDir: z.string().default("~/.personal-agent"),
     workspaceDir: z.string().default("."),
-    apiPort: z.number().int().positive().default(8321),
+    apiPort: z.number().int().positive().default(DEFAULT_API_PORT),
 });
 function expandHome(p) {
     if (p.startsWith("~/") || p.startsWith("~\\")) {
@@ -84,7 +84,7 @@ export function loadBootstrapConfig() {
     const config = bootstrapConfigSchema.parse({
         dataDir: envOrDefault("DATA_DIR", "~/.personal-agent"),
         workspaceDir: envOrDefault("WORKSPACE_DIR", "."),
-        apiPort: parseNumberOrDefault(env("API_PORT"), 8321),
+        apiPort: parseNumberOrDefault(env("API_PORT"), DEFAULT_API_PORT),
     });
     return {
         ...config,
@@ -93,6 +93,15 @@ export function loadBootstrapConfig() {
     };
 }
 export function loadDefaultRuntimeSettings() {
+    // HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4 — the `gateMode` enum
+    // (`off`/`shadow`/`live`) collapsed into a single execution path.
+    // Warn-once when an operator still has the legacy env var set so
+    // they know the value is now a no-op instead of silently dropping
+    // their override. The runtime-settings Zod schema would otherwise
+    // ignore the unknown key without any signal.
+    if (env("HOURLY_CHECK_GATE_MODE") !== undefined) {
+        console.warn("[config] PA_HOURLY_CHECK_GATE_MODE is set but no longer honoured — the hourly_check gate now has a single execution path (see HOURLY_CHECK_GATE_REDESIGN_PLAN.md Phase 4). Remove the env var to silence this warning.");
+    }
     const parsed = runtimeSettingsSchema.parse({
         slackOwnerUserId: env("SLACK_OWNER_USER_ID") ?? null,
         telegramOwnerChatId: env("TELEGRAM_OWNER_CHAT_ID") ?? null,
@@ -127,16 +136,21 @@ export function loadDefaultRuntimeSettings() {
         character: envOrDefault("PA_CHARACTER", ""),
         timezone: envOrDefault("TIMEZONE", ""),
         dayBoundaryHour: parseNumberOrDefault(env("DAY_BOUNDARY_HOUR"), 4),
+        // See `runtime-settings.ts:monthlyReviewEnabled` for why this defaults
+        // off pre-release. Flip via PA_MONTHLY_REVIEW_ENABLED=true or PATCH
+        // /api/config; scheduler.ts reads `this.config.monthlyReviewEnabled`
+        // at fire time so the flag takes effect on the next month-end without
+        // restart.
+        monthlyReviewEnabled: parseBooleanOrDefault(env("MONTHLY_REVIEW_ENABLED"), false),
         hourlyCheckEnabled: parseBooleanOrDefault(env("HOURLY_CHECK_ENABLED"), true),
         hourlyCheckIntervalMinutes: parseNumberOrDefault(env("HOURLY_CHECK_INTERVAL_MINUTES"), 60),
         hourlyCheckActiveStartHour: parseNumberOrDefault(env("HOURLY_CHECK_ACTIVE_START_HOUR"), 4),
         hourlyCheckActiveEndHour: parseNumberOrDefault(env("HOURLY_CHECK_ACTIVE_END_HOUR"), 24),
         hourlyCheckMinObservations: parseNumberOrDefault(env("HOURLY_CHECK_MIN_OBSERVATIONS"), 1),
-        hourlyCheckGateMode: env("HOURLY_CHECK_GATE_MODE") ??
-            "shadow",
         hourlyCheckStage2Enabled: parseBooleanOrDefault(env("HOURLY_CHECK_STAGE2_ENABLED"), false),
         hourlyCheckHeartbeatHours: parseNumberOrDefault(env("HOURLY_CHECK_HEARTBEAT_HOURS"), 4),
         hourlyCheckLowSignalPendingCeiling: parseNumberOrDefault(env("HOURLY_CHECK_LOW_SIGNAL_PENDING_CEILING"), 0),
+        hourlyCheckPrePassFreshnessMinutes: parseNumberOrDefault(env("HOURLY_CHECK_PRE_PASS_FRESHNESS_MINUTES"), 30),
         authProbeDisabled: parseBooleanOrDefault(env("AUTH_PROBE_DISABLED"), false),
         authPreflightFreshnessMs: parseNumberOrDefault(env("AUTH_PREFLIGHT_FRESHNESS_MS"), 600000),
         schedulePollIntervalSeconds: parseNumberOrDefault(env("SCHEDULE_POLL_INTERVAL_SECONDS"), 5),
@@ -155,6 +169,9 @@ export function loadDefaultRuntimeSettings() {
         claudeExecutionPermissionMode: env("CLAUDE_EXECUTION_PERMISSION_MODE") ?? "strict",
         codexExecutionPermissionMode: env("CODEX_EXECUTION_PERMISSION_MODE") ?? "strict",
         geminiExecutionPermissionMode: env("GEMINI_EXECUTION_PERMISSION_MODE") ?? "strict",
+        opencodeExecutionPermissionMode: env("OPENCODE_EXECUTION_PERMISSION_MODE") ?? "strict",
+        opencodeBaseUrl: envOrDefault("OPENCODE_BASE_URL", "http://127.0.0.1:4096"),
+        opencodeServerUsername: envOrDefault("OPENCODE_SERVER_USERNAME", "opencode"),
         obsidianDebounceSeconds: parseNumberOrDefault(env("OBSIDIAN_DEBOUNCE_SECONDS"), 5.0),
         gitPollIntervalSeconds: parseNumberOrDefault(env("GIT_POLL_INTERVAL_SECONDS"), 3600),
         gitPushOverdueMinutes: parseNumberOrDefault(env("GIT_PUSH_OVERDUE_MINUTES"), 60),
@@ -183,7 +200,7 @@ export function loadDefaultRuntimeSettings() {
         prePassMaxAttemptsPerIntegration: parseNumberOrDefault(env("PRE_PASS_MAX_ATTEMPTS_PER_INTEGRATION"), 3),
         prePassBackoffMs: parseJsonOrDefault(env("PRE_PASS_BACKOFF_MS"), [1000, 2000, 4000]),
         prePassRetryEscalationTier: parseNullableStringEnv(env("PRE_PASS_RETRY_ESCALATION_TIER")),
-        // PRE_PASS_FAN_OUT_DESIGN.md §6 — null = unlimited concurrency. Fall back
+        // docs/design/appendices/pre-pass-fan-out.md §6 — null = unlimited concurrency. Fall back
         // to null (not 0) on an unparseable env value so a typo never kills boot
         // via the downstream Zod `min(1)` check; the Zod parser then validates
         // any genuine numeric override against the [1, 5] range and rejects
@@ -601,7 +618,7 @@ function hasPrimaryVaultSchemaMarkers(primaryVaultPath) {
  * vault must also contain at least one canonical context marker so the
  * daemon does not resume writes into an empty or wrong directory.
  *
- * Bootstrapping bypass: if `rules/management.md` doesn't exist yet, setup
+ * Bootstrapping bypass: if `policies/management.md` doesn't exist yet, setup
  * hasn't run; honoring a null primaryVaultPath would break the initial-DM
  * setup flow (which writes via `/api/context/*`, gated by the 503
  * middleware). Skip degraded-mode entirely until setup completes. This
@@ -626,7 +643,7 @@ export function runVaultHealthProbe(config, db) {
     // disable degraded mode when the user most needs the banner.
     //
     // Second priority: if setup has never been marked complete, probe the
-    // filesystem. Setup is considered complete once `rules/management.md`
+    // filesystem. Setup is considered complete once `policies/management.md`
     // lands anywhere the user could plausibly have pointed their vault at:
     //   - the fallback (`<dataDir>/context`): fresh-install setup with
     //     null primaryVaultPath writes here
@@ -636,9 +653,10 @@ export function runVaultHealthProbe(config, db) {
     // forcing degraded on them would 503 the DM-driven setup flow before
     // they can configure anything.
     if (!isSetupCompleted(db)) {
-        const fallbackRulesPath = resolve(config.dataDir, "context", "rules", "management.md");
+        // CONTEXT_VAULT_REDESIGN: management.md lives under policies/.
+        const fallbackRulesPath = resolve(config.dataDir, "context", "policies", "management.md");
         const primaryRulesPath = config.primaryVaultPath
-            ? resolve(config.primaryVaultPath, "rules", "management.md")
+            ? resolve(config.primaryVaultPath, "policies", "management.md")
             : null;
         const setupIncomplete = !existsSync(fallbackRulesPath) &&
             (primaryRulesPath === null || !existsSync(primaryRulesPath));
@@ -649,9 +667,9 @@ export function runVaultHealthProbe(config, db) {
             }
             return { action: "noop" };
         }
-        // rules/management.md exists now — latch the marker so subsequent
-        // probes skip the filesystem check and treat any unreachability as
-        // genuine degradation.
+        // policies/management.md exists now — latch the marker so
+        // subsequent probes skip the filesystem check and treat any
+        // unreachability as genuine degradation.
         markSetupCompleted(db);
     }
     const currentState = getDegradedMode(db);
@@ -703,7 +721,7 @@ export function runVaultHealthProbe(config, db) {
     return { action: "noop" };
 }
 export function isRoadmapStale(contextDir, maxAgeDays = 15) {
-    const roadmapPath = resolve(contextDir, "roadmap.md");
+    const roadmapPath = resolve(contextDir, "plans", "roadmap.md");
     if (!existsSync(roadmapPath))
         return true;
     const content = readFileSync(roadmapPath, "utf-8");
@@ -722,4 +740,3 @@ export function getLogsDir(config) {
 export function getTmpDir(config) {
     return resolve(config.dataDir, "tmp");
 }
-//# sourceMappingURL=config.js.map

package/dist/core/abort-utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Race a promise against an AbortSignal so the returned promise rejects
+ * when the signal fires, even if the underlying work doesn't natively
+ * honor the signal.
+ *
+ * Use this to wrap SDK calls (Notion, Google Calendar Node SDK, etc.)
+ * whose signal support is uncertain or missing. The underlying call
+ * leaks — it continues until it naturally completes or the transport
+ * times out — but the caller's promise resolves promptly when the
+ * signal fires, which is what `PollGuard` needs to reset `inFlight`
+ * and unblock the next tick.
+ */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;

package/dist/core/abort-utils.js

@@ -0,0 +1,35 @@
+/**
+ * Race a promise against an AbortSignal so the returned promise rejects
+ * when the signal fires, even if the underlying work doesn't natively
+ * honor the signal.
+ *
+ * Use this to wrap SDK calls (Notion, Google Calendar Node SDK, etc.)
+ * whose signal support is uncertain or missing. The underlying call
+ * leaks — it continues until it naturally completes or the transport
+ * times out — but the caller's promise resolves promptly when the
+ * signal fires, which is what `PollGuard` needs to reset `inFlight`
+ * and unblock the next tick.
+ */
+export function raceWithAbort(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(toAbortError(signal.reason));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(toAbortError(signal.reason));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (err) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(err);
+        });
+    });
+}
+function toAbortError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    return new Error(typeof reason === "string" && reason.length > 0 ? reason : "aborted");
+}