@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/concepts/observations.md

@@ -7,6 +7,8 @@ aliases:
   - observation
   - polling
   - hourly check
+  - observation queue
+  - phase 9
 category: concepts
 summary: |
   Observations are change records the polling integrations write into
@@ -17,22 +19,52 @@ tags:
   - core
   - observations
   - polling
+  - integrations
+  - routines
 status: stable
 ask_examples:
   - What is an observation?
   - Why doesn't the agent message me on every git commit?
   - How does the hourly check use observations?
+  - Where does the routine pre-pass write observations?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - observation
+  - observations
   - polling
   - hourly check
   - phase 9
+  - routine.fetch_window
+  - pre-pass
+  - AgentWriteTracker
+  - contentHash
+  - recordObservation
+  - observation queue
+  - dedupe
 related:
   - features/routines/hourly-check
+  - features/routines/morning-routine
   - concepts/process-keys
+  - concepts/routines
+  - features/integrations/git
+  - features/integrations/obsidian
+ui_anchors:
+  - /activity
+process_keys:
+  - routine.hourly_check
+  - routine.fetch_window
+config_keys:
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckPrePassFreshnessMinutes
+api_endpoints:
+  - POST /api/observations
+  - GET /api/observations
+  - POST /api/observations/consume
+context_files:
+  - packages/daemon/src/core/routine-windows.ts
+  - packages/daemon/src/api/routes/observations.ts
 ---
 
 # Observations
@@ -45,13 +77,15 @@ SQLite. A single `routine.hourly_check` consumes the queue and decides
 what is worth surfacing.
 
 Since 2026-05, observations have a **second writer**: every main
-routine (morning, today_refresh, hourly_check, evening, weekly) is
-preceded by a lite-tier `routine.fetch_window` pre-pass that fetches
-mail / calendar / Notion windows and POSTs them to
-`/api/observations`. The main routine then reads them via the same
-`pending=true` queue that the polling path feeds. Observation rows
-look identical regardless of which writer produced them — the
-distinction is invisible to downstream consumers.
+routine (`routine.morning_routine`, `routine.today_refresh`,
+`routine.hourly_check`, `routine.evening_review`,
+`routine.weekly_review`) is preceded by a lite-tier
+`routine.fetch_window` pre-pass that fetches mail / calendar / Notion
+windows and POSTs them to `/api/observations`.
+(`routine.monthly_review` has no pre-pass window.) The main routine
+then reads them via the same `pending=true` queue that the polling
+path feeds. Observation rows look identical regardless of which writer
+produced them — the distinction is invisible to downstream consumers.
 
 ## Why This Concept Exists
 
@@ -63,6 +97,18 @@ up to something the operator should hear about.
 
 ## Definitions
 
+**Two writer paths feed one queue.** Observations enter the
+`observations` table from two places, and downstream consumers cannot
+tell them apart:
+
+1. **Background pollers** (Obsidian, Git, GitHub, Notion, Calendar,
+   Mail) call `recordObservation` when they detect a change.
+2. **The pre-pass** — the lite-tier `routine.fetch_window` session
+   spawned ahead of each main routine — POSTs mail / calendar / Notion
+   windows to `/api/observations`.
+
+Both write rows of the same shape; the consumer reads the merged queue.
+
 - **Observation**: one row in the `observations` table.
 - **Actor**: who caused the change. `actor='agent'` rows are filtered
   out by the consumer (anti-loop).
@@ -76,9 +122,10 @@ up to something the operator should hear about.
   session spawned by each main routine's dispatcher. Fetches a
   per-routine window (`ROUTINE_WINDOWS` in
   `packages/daemon/src/core/routine-windows.ts`) for each enabled
-  mail / calendar / Notion integration and POSTs observations. The
-  server computes `contentHash` from `(source, payload)`, so an
-  unchanged item written twice in the same cadence dedupes to a 409.
+  mail / calendar / Notion integration and POSTs the results to
+  `/api/observations`. The server computes `contentHash` from
+  `(source, payload)`, so an unchanged item written twice in the same
+  cadence dedupes to a 409.
 
 ## Concrete Examples
 
@@ -94,5 +141,8 @@ up to something the operator should hear about.
 ## Related
 
 - [Hourly Check](../features/routines/hourly-check.md)
+- [Morning Routine](../features/routines/morning-routine.md)
+- [Process Keys](./process-keys.md)
+- [Routines](./routines.md)
 - [Git](../features/integrations/git.md)
 - [Obsidian](../features/integrations/obsidian.md)

package/agent-assets/docs/concepts/process-keys.md

@@ -16,22 +16,54 @@ section: process-keys
 tags:
   - core
   - dispatch
+  - backends
+  - routing
 status: stable
 ask_examples:
   - What is a ProcessKey?
   - Where can I see all the ProcessKeys?
   - How do I change which model handles a ProcessKey?
+  - What is the difference between configurable and fixed ProcessKeys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - process key
+  - ProcessKey
   - dispatch
   - routing
+  - tier
+  - CONFIGURABLE_PROCESS_KEYS
+  - DEFAULT_PROCESS_TIERS
+  - REACTIVE_PROCESS_KEYS
+  - TIER_LOCKED_PROCESS_KEYS
+  - PROCESS_TO_EVENT_TYPE
+  - routine.morning_routine
+  - message.dm
+  - dashboard.chat
 related:
   - concepts/backends-and-tiers
   - concepts/skills
   - reference/process-keys
+  - features/operations/backend-routing
+process_keys:
+  - routine.morning_routine
+  - routine.morning_routine_today
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.hourly_check
+  - routine.fetch_window
+  - routine.hourly_check.triage
+  - message.dm
+  - message.mention
+  - dashboard.chat
+  - dashboard.docs_qa
+  - agent.task
+  - agent.dm_task
+  - delegated_task
+  - delegated_task_heavy
+ui_anchors:
+  - /settings/models
 ---
 
 # ProcessKeys
@@ -54,32 +86,49 @@ those subsystems.
 ## Definitions
 
 - **CONFIGURABLE_PROCESS_KEYS**: the set the operator can override per
-  backend on `/settings/models`.
-- **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events (DMs,
-  dashboard chat, docs QA).
-- **DEFAULT_PROCESS_TIERS**: the per-key default (heavy or light).
+  backend on `/settings/models`. The rest (`delegated_task`, `setup`,
+  `schedule.approaching`, …) use fixed defaults and are not surfaced
+  there.
+- **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events
+  (`message.dm`, `message.mention`, `dashboard.chat`,
+  `dashboard.docs_qa`, `setup`, `knowledge.import`). Everything else is
+  autonomous.
+- **DEFAULT_PROCESS_TIERS**: the per-key default model size — `lite`
+  (Haiku-class), `medium` (Sonnet-class), or `high` (Opus-class).
+  Unknown keys (including `routine.custom.<slug>`) default to `medium`.
+- **TIER_LOCKED_PROCESS_KEYS**: keys whose tier is hard-locked and
+  cannot be overridden by an operator pin. Today this is just
+  `dashboard.docs_qa`, locked to `medium`.
 - **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to the skill manifest
-  key.
+  key, so the skills compiler can pick the right tool set.
 
 ## Concrete Examples
 
-- Routines: `routine.morning_routine`, `routine.morning_routine_initial`,
+- **Routines:** `routine.morning_routine` is the parent envelope read by
+  the pre-routine gate; the actual work runs as two parallel split keys
+  — `routine.morning_routine_today` (Stage A, today.md, medium) and
+  `routine.morning_routine_journal` (Stage B, daily journal, lite). Also
   `routine.evening_review`, `routine.weekly_review`,
-  `routine.monthly_review`, `routine.hourly_check`,
-  `routine.roadmap_refresh`, `routine.today_refresh`,
-  `routine.user_profile_sweep`
-- Routine sub-jobs (lite tier, dispatcher-spawned, not user-facing):
+  `routine.hourly_check`, `routine.roadmap_refresh`,
+  `routine.today_refresh`, `routine.user_profile_sweep`.
+  `routine.morning_routine_initial` was retired (2026-05-16) — the
+  first-run branch now routes through `routine.morning_routine`.
+- **Routine sub-jobs** (lite tier, dispatcher-spawned, not user-facing):
   `routine.fetch_window` (pre-pass mail/calendar/Notion fetcher that
   runs before each main routine and POSTs observations) and
   `routine.hourly_check.triage` (Stage 2 escalate-vs-log-only gate
   inside the hourly check).
-- Custom routines: `routine.custom.<slug>` (kebab-case slug)
-- Messaging: `message.dm`, `message.mention`
-- Dashboard: `dashboard.chat`, `dashboard.docs_qa`
-- Scheduled / external: `agent.task` (recurring schedules),
+- **Custom routines:** `routine.custom.<slug>` (kebab-case slug;
+  defaults to medium tier).
+- **Messaging:** `message.dm`, `message.mention`
+- **Dashboard:** `dashboard.chat`, `dashboard.docs_qa`
+- **Scheduled / external:** `agent.task` (recurring schedules),
   `agent.dm_task` (DM-tone scheduled briefings),
-  `schedule.approaching`, `calendar.change`, `gmail_classify`,
-  `setup`
+  `schedule.approaching`, `calendar.change`, `gmail_classify`, `setup`
+- **Delegated work:** `delegated_task` (lite) and `delegated_task_heavy`
+  — the only high-tier key, opt-in via the `delegatedTaskHeavyEnabled`
+  config flag. No install-time surface defaults to `high`; operators
+  pin high per-row on `/settings/models`.
 
 ## Where You See It in the Dashboard
 

package/agent-assets/docs/concepts/routines.md

@@ -7,29 +7,40 @@ aliases:
   - autonomous routines
   - cron
   - scheduled work
+  - routine pre-pass
+  - morning routine
+  - evening review
 category: concepts
 summary: |
   Routines are the autonomous, scheduled tasks Aitne runs on
-  its own — morning routine, evening review, hourly check, weekly and
-  monthly retros, plus any custom routines you define.
+  its own — morning routine, evening review, hourly check, weekly
+  retro, plus any custom routines you define.
 section: routines
 tags:
   - core
-  - routine
+  - routines
   - autonomous
+  - scheduler
 status: stable
 ask_examples:
   - What routines does the agent run automatically?
   - How do I disable a routine?
   - Can I add my own routine?
+  - What is the routine pre-pass fetcher?
+  - Which routine uses the high tier by default?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - routine
+  - routines
   - cron
   - autonomous
   - scheduler
+  - routine.fetch_window
+  - pre-pass
+  - dayBoundaryHour
+  - hourly check
 related:
   - features/routines/morning-routine
   - features/routines/evening-review
@@ -37,9 +48,29 @@ related:
   - features/routines/hourly-check
   - features/routines/custom-routines
   - concepts/process-keys
+  - concepts/observations
 ui_anchors:
   - /connections/routines
   - /settings/routines
+process_keys:
+  - routine.morning_routine
+  - routine.morning_routine_today
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.weekly_review
+  - routine.monthly_review
+  - routine.hourly_check
+  - routine.today_refresh
+  - routine.fetch_window
+  - routine.hourly_check.triage
+config_keys:
+  - dayBoundaryHour
+  - hourlyCheckEnabled
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckActiveStartHour
+  - hourlyCheckActiveEndHour
+  - hourlyCheckPrePassFreshnessMinutes
+  - monthlyReviewEnabled
 ---
 
 # Routines
@@ -48,9 +79,10 @@ ui_anchors:
 
 A routine is a unit of agent work that runs on a schedule, not in
 response to a message. The morning routine fires once per agent day at
-`dayBoundaryHour`; evening / weekly / monthly retros fire on fixed
-schedules in code; the hourly check coalesces accumulated observations
-on a configurable cadence.
+`dayBoundaryHour`; the evening review (18:00 daily), weekly review
+(Friday 19:00), and optional monthly review fire on fixed schedules in
+code; the hourly check coalesces accumulated observations on a
+configurable cadence.
 
 ## Why This Concept Exists
 
@@ -70,45 +102,58 @@ DM is who fired the event.
   a ProcessKey starting with `routine.`.
 - **Agent day**: the 24-hour window starting at `dayBoundaryHour`
   (default 04:00) — see [Agent Day](agent-day.md).
-- **Catch-up**: if the daemon was offline at the trigger time, the
-  scheduler re-fires the routine on next launch when it is still in
-  the same agent day.
-- **Tier policy**: only the one-shot `routine.morning_routine_initial`
-  runs heavy by default (Opus on Claude, GPT-5.5 on Codex, Gemini 3
-  Pro on Gemini). Every other recurring routine — morning, evening,
-  weekly, monthly, hourly check — defaults to **medium** (Sonnet on
-  Claude). The lite (Haiku) tier is reserved for mechanical
-  sub-jobs: the hourly-check triage gate and the new pre-pass
-  fetcher. See [Backends and Tiers](backends-and-tiers.md).
+- **Catch-up**: if the daemon was offline at the trigger time, a
+  boot-time check re-fires any routine whose window has already
+  opened but never ran (morning routine within the agent day; evening
+  review once it is past 18:00; weekly review across Fri–Sun). It never
+  double-fires a routine that already succeeded.
+- **Tier policy**: **no routine runs the high tier by default.** Every
+  recurring routine — morning, evening, weekly, hourly check —
+  defaults to **medium** (Sonnet on Claude). The **lite** (Haiku) tier
+  is reserved for the morning routine's Stage B and for mechanical
+  sub-jobs (the hourly-check triage gate and the pre-pass fetcher). The
+  only high-tier ProcessKey in the whole system is `delegated_task_heavy`,
+  which is opt-in and not a routine. See
+  [Backends and Tiers](backends-and-tiers.md).
+- **Two-stage morning routine**: the morning routine runs as a parent
+  envelope `routine.morning_routine` (medium) that fans out two stages
+  in parallel — Stage A `routine.morning_routine_today` (medium, builds
+  `state/today.md`) and Stage B `routine.morning_routine_journal` (lite,
+  authors the previous day's journal). The legacy heavy-tier
+  `routine.morning_routine_initial` first-run branch was retired in
+  Phase 7 (2026-05-16); a first run is now detected inline from a
+  missing `state/yesterday.md` and handled by the same medium-tier
+  parent with a daemon-prepared `<roadmap_skeleton>` block.
 - **Pre-pass fetcher**: each main routine that needs fresh mail /
   calendar / Notion data is preceded by a lite-tier
   `routine.fetch_window` session that fetches the relevant window and
-  POSTs observations. The main routine consumes the resulting
-  `<fetch_report>` block plus pending observations instead of
-  fetching upstream APIs itself. This is the cost-savings split
-  introduced in 2026-05.
+  POSTs observations. The main routine then consumes the resulting
+  `<fetch_report>` block plus pending observations instead of hitting
+  upstream APIs itself — a cost-savings split introduced in 2026-05.
 
 ## Concrete Examples
 
 | ProcessKey | When | Tier |
 |---|---|---|
-| `routine.morning_routine_initial` | First setup day, one-shot | heavy |
-| `routine.morning_routine` | `dayBoundaryHour` daily | medium |
-| `routine.today_refresh` | Every 4h inside the active window | medium |
+| `routine.morning_routine` | `dayBoundaryHour` daily (parent envelope; first-run branch detected inline from missing `state/yesterday.md`) | medium |
+| `routine.morning_routine_today` | Stage A of every morning routine (today.md synthesis + roadmap maintenance + schedule fan-out) | medium |
+| `routine.morning_routine_journal` | Stage B of every morning routine (`journal/daily/<yesterday>.md` authoring) | lite |
 | `routine.evening_review` | 18:00 daily (fixed) | medium |
+| `routine.weekly_review` | Friday 19:00 (fixed, one hour after evening review) | medium |
+| `routine.monthly_review` | Last day of month at 18:00, **default off** (`monthlyReviewEnabled`) | medium |
 | `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | medium |
-| `routine.weekly_review` | Friday 18:00 (fixed) | medium |
-| `routine.monthly_review` | Last day of month, 18:00 (fixed) | medium |
-| `routine.fetch_window` | Spawned before each routine above (except monthly) | lite |
+| `routine.today_refresh` | On calendar drift or a dashboard "refresh today" request (not a fixed cron) | medium |
+| `routine.fetch_window` | Spawned before each routine above that needs fresh upstream data | lite |
 | `routine.hourly_check.triage` | Stage 2 gate of every hourly check | lite |
-| `routine.custom.<slug>` | Operator-defined recurrence | configurable |
+| `routine.custom.<slug>` | Operator-defined recurrence | medium (override per routine via `backend_tier`) |
 
 ## Where You See It in the Dashboard
 
-- **Settings → Routines** is where the hourly check active window, the
-  hourly check cadence, and any custom routines live. Morning, evening,
-  weekly, and monthly fire times are fixed in code and not surfaced
-  here.
+- **Settings → Routines** is where the hourly check active window
+  (`hourlyCheckActiveStartHour` / `hourlyCheckActiveEndHour`), the
+  hourly check cadence (`hourlyCheckIntervalMinutes`), and any custom
+  routines live. Morning, evening, weekly, and monthly fire times are
+  fixed in code and not surfaced here.
 - **Connections → Routines** is the unified view of next-fire times.
 - **Activity** logs each routine run with its outcome.
 

package/agent-assets/docs/concepts/safety-and-execution.md

@@ -19,7 +19,8 @@ section: safety
 tags:
   - core
   - safety
-  - cost
+  - operations
+  - backends
 status: stable
 ask_examples:
   - What is the difference between Safe and Allow mode?
@@ -27,7 +28,7 @@ ask_examples:
   - How do I see what tools the agent is allowed to use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - safety
   - safe mode
@@ -35,18 +36,23 @@ keywords:
   - absolute block
   - disallowed tools
   - approval
+  - execution mode
+  - risk tier
 related:
+  - concepts/safety-model
   - concepts/skills
   - features/operations/approvals
   - reference/disallowed-tools
 ui_anchors:
   - /settings/advanced
+  - /settings/models
 config_keys:
   - disallowedTools
   - allowedToolsOverride
   - claudeExecutionPermissionMode
   - codexExecutionPermissionMode
   - geminiExecutionPermissionMode
+  - opencodeExecutionPermissionMode
 ---
 
 # Safety and Execution Modes
@@ -57,10 +63,13 @@ Three layers gate what the agent can do:
 
 1. **Skill `allowed-tools`** — the visible toolset for that session.
 2. **Execution mode** — Safe (strict permission checks, sandboxes)
-   or Allow (SDK bypass, sandbox off). Per-backend.
-3. **Always-disallowed** — a hard floor. Recursive deletes, sudo,
+   or Allow (SDK bypass, sandbox off). Set per-backend.
+3. **Always-disallowed** — a hard floor. Recursive deletes, `sudo`,
    secret-file reads / writes are denied unconditionally regardless
-   of mode.
+   of mode, and neither a skill nor Allow mode can widen past it.
+
+A fourth idea — the **risk tier** — sits on top of the daemon API and
+decides whether a *write* runs on its own or waits for your approval.
 
 ## Why This Concept Exists
 
@@ -72,37 +81,57 @@ disallowed-tools floor.
 
 ## Definitions
 
-- **Safe mode**: the default. Strict permission checks, Claude curl/jq
-  hooks, Codex workspace-write sandbox, Gemini whitelist TOML.
+- **Safe mode**: the default. Strict permission checks, plus a
+  backend-specific enforcement layer — Claude curl/jq hooks, the Codex
+  workspace-write sandbox, the Gemini whitelist TOML, and the OpenCode
+  permission block.
 - **Allow mode**: the looser posture. SDK bypass, sandbox off, minimal
-  TOML. The absolute-block layer still holds.
+  TOML. The absolute-block layer still holds in Allow mode, so the
+  destructive-ops floor never opens. Set independently per backend, so
+  one backend can run Allow while the others stay Safe.
 - **Absolute block**: the unconditional layer. `ALWAYS_DISALLOWED_TOOLS`
   in `src/safety/always-disallowed.ts`. Cannot be widened by skills,
   by config, or by allow-mode.
-- **Risk tier**: `read`, `notify`, `approve`. Read = autonomous. Notify
-  = the agent proceeds after DMing the operator. Approve = blocked
-  until the operator clicks approve in the dashboard.
+- **Risk tier**: every daemon-API operation carries one of three tiers —
+  `autonomous`, `read_sensitive`, or `approve`. *Autonomous* runs without a
+  prompt. *Read-sensitive* reads (email, calendar, notes, context files) are
+  the same blast radius as autonomous but are gated by a read token when
+  `enforceReadToken` is on. *Approve* is blocked until you confirm with a
+  bearer token (the dashboard does this when you click Approve). There is no
+  separate "notify" tier — that behaviour now lives in the skill prompts: for
+  potentially destructive actions the agent DMs you first, then proceeds. See
+  [Safety model](safety-model.md) for the full taxonomy.
 
 ## Concrete Examples
 
-| Action | Risk tier |
+The daemon API is the agent's only write path, so most of its own writes are
+`autonomous` (the memory chokepoint validates and snapshots them). The
+absolute-block layer and Approve tier are where the agent is actually stopped.
+
+| Action | What gates it |
 |---|---|
-| Read `today.md` | read |
-| Append to `agent/journal.md` | notify |
-| Send a DM | notify |
-| Update `roadmap.md` | approve |
-| Recursive delete | absolute-block (refused) |
-| `chmod` on a daemon-owned file | absolute-block |
+| Read `state/today.md` | `read_sensitive` (read token if `enforceReadToken`) |
+| Append to `journal/agent.md` | `autonomous` — daemon API write |
+| Update `plans/roadmap.md` | `autonomous`, plus a roadmap write-lock |
+| Send a DM | `autonomous`; destructive follow-ups DM you first |
+| Configure an automation trigger | `approve` — needs a bearer token |
+| `chmod` on a daemon-owned file | Safe-mode disallowed (allowed in Allow mode) |
+| Recursive delete (`rm -rf`), `sudo`, secret-file read | absolute-block (refused in both modes) |
 
 ## Where You See It in the Dashboard
 
-- **Settings → Advanced** holds `disallowedTools`, `allowedToolsOverride`,
-  and the per-backend execution mode switch.
-- **Activity** logs every blocked tool call as `action_type='blocked_absolute'`.
+- **Settings → Advanced** holds the `disallowedTools` and
+  `allowedToolsOverride` tool-policy lists.
+- **Settings → Models & Cost** holds the per-backend Safe / Allow
+  **Execution Mode** switch (you can also set it in the setup wizard).
+- **Activity** logs every absolute-blocked tool call as
+  `action_type='blocked_absolute'`.
 - **Approvals** is where Approve-tier actions queue when they fire.
 
 ## Related
 
+- [Safety model](safety-model.md) — the full risk-tier taxonomy and where
+  each API endpoint is classified.
 - [Skills](skills.md) — where each session's per-task `allowed-tools` lives.
 - [Approvals](../features/operations/approvals.md) — the operator-side
   surface for Approve-tier actions.