@aitne-sh/aitne 0.1.10 → 0.1.11

package/agent-assets/docs/features/operations/browser-tasks.md

@@ -0,0 +1,184 @@
+---
+schema_version: 1
+slug: features/operations/browser-tasks
+title: Browser Tasks
+id: browser-tasks
+aliases:
+  - browser tasks
+  - browser task
+  - web task
+  - browser automation tasks
+  - sandboxed browser
+category: features
+summary: |
+  Open-ended browser actions the agent runs for you in a sandboxed,
+  one-tab-per-task sub-agent — "send a contact form on Amazon", "check
+  the price of X". You kick a task off in DM (or schedule one); the
+  agent DMs you back for clarification or a final confirm when it needs
+  your input. The Browser Tasks page is where every run shows up, with
+  live state, a screenshot trace, and a cancel button.
+section: operations
+tags:
+  - operations
+  - browser-automation
+  - safety
+status: beta
+ask_examples:
+  - What is the Browser Tasks page?
+  - How do I start a browser task?
+  - Why is my browser task waiting for me?
+  - What do the browser-task states mean?
+  - How do I cancel a running browser task?
+  - Where do I see the screenshots from a browser task?
+locale: en-US
+created: 2026-06-16
+updated: 2026-06-16
+keywords:
+  - browser tasks
+  - browser-task
+  - sandboxed sub-agent
+  - awaiting_user
+  - final_confirm
+  - screenshot trace
+  - allowlist
+  - payment-path block
+  - cancel task
+related:
+  - features/operations/managed-chromium
+  - features/integrations/browser-history
+  - concepts/safety-and-execution
+  - concepts/safety-model
+ui_anchors:
+  - /browser-tasks
+  - /browser
+process_keys:
+  - browser_task
+config_keys:
+  - browserTaskMaxConcurrent
+  - browserTaskPendingQueueTimeoutMinutes
+  - browserTaskRespectQuietHours
+  - browserTaskHostnameDenylist
+api_endpoints:
+  - POST /api/browser-task
+  - GET /api/browser-task
+  - GET /api/browser-task/:id
+  - GET /api/browser-task/:id/events
+  - GET /api/browser-task/:id/screenshots/:file
+  - POST /api/browser-task/:id/clarify
+  - POST /api/browser-task/:id/cancel
+---
+
+# Browser Tasks
+
+A **browser task** is an open-ended action you ask the agent to carry
+out on the web — "send a contact form on Amazon's contact-us page",
+"check the price of X", "fill in this signup". Each task runs in a
+sandboxed sub-agent with **one browser tab to itself**, under allowlist
+enforcement, a payment-path block, and a screenshot trace. The
+**Browser Tasks** page (`/browser-tasks`) is the operational surface
+where every run shows up — what is queued, running, waiting on you, or
+finished.
+
+This is different from two neighbouring surfaces:
+
+- **[Browser History](browser-history)** reads your *existing* Chrome
+  passively (research clusters, revisit nudges). It never drives a
+  browser.
+- **[Managed Chromium / B-4](managed-chromium)** is the heavily-gated,
+  default-off *purchase-confirmation* flow. Browser tasks are the
+  general-purpose, non-purchasing actions; a final purchase confirm is
+  the one thing they hand off to the B-4 token primitive.
+
+## Starting a Task
+
+You don't start a task from this page — you ask in **DM** or `/chat`:
+
+> "Send a contact form on Amazon's contact-us page saying my order
+> #123 never arrived."
+
+The agent creates the task (`POST /api/browser-task`), opens a tab, and
+works the goal step by step. You can also **schedule** one to run later
+(it appears here when it fires). The page itself is a read + monitor
+surface: filter, search, open a run, or cancel it.
+
+## Reading the Page
+
+- **Tasks awaiting you** — a strip pinned to the top that only appears
+  when one or more tasks are blocked on your input. It links straight
+  to the run that needs you. The same signal drives the nav red-dot and
+  the persistent shell banner, so they stay in lock-step.
+- **Filter chips** — narrow by state (`All`, `Active`, or a specific
+  state) and by **site**. `Active` means any non-terminal task.
+- **Search** — free-text match over the task description.
+- **Table** — one row per task: state, description (click to open the
+  run), site, originating channel, created time, and duration. Active
+  rows expose a **Cancel** button.
+
+Click any row to open the **run detail** (`/browser-tasks/:id`): the
+step-by-step event log and the **screenshot trace** the sub-agent
+captured along the way.
+
+## Task States
+
+A task moves through a small state machine. Non-terminal states are
+still in flight; terminal states are done.
+
+| State | Meaning |
+| --- | --- |
+| `pending` | Queued, not started yet. The duration cell shows queue wait and, when known, the site / global queue position. |
+| `running` | The sub-agent is actively driving the tab. |
+| `awaiting_user` | Paused — the agent DMed you a **clarifying question** and is waiting for your answer (`POST /api/browser-task/:id/clarify`). |
+| `final_confirm` | Paused at a **final confirmation** gate (e.g. a submit/checkout step) waiting for your explicit go-ahead. |
+| `completed` | Finished successfully. |
+| `failed` | Stopped on an error; the row shows a short outcome detail. |
+| `cancelled` | You (or the agent) cancelled it. |
+| `timeout` | Exceeded its time budget. |
+| `abandoned` | A pending task expired in the queue before it could start (see `browserTaskPendingQueueTimeoutMinutes`). |
+
+When a task is `awaiting_user` or `final_confirm`, **answer in the DM
+the agent sent you** — that is the loop that unblocks it. The dashboard
+strip and banner are just where you notice it.
+
+## Cancelling
+
+Active tasks have a **Cancel** button (and `POST
+/api/browser-task/:id/cancel`). Cancelling releases the browser context
+immediately and DMs you a confirmation. Terminal tasks can't be
+cancelled — there is nothing left to stop.
+
+## Safety Model (why it's safe to let it drive)
+
+Browser tasks inherit the project's structural browser defences — there
+is **no hardcoded category/brand denylist**:
+
+1. **One sandboxed tab per task.** Tasks don't share a browser context,
+   so one task can't read another's session.
+2. **Allowlist enforcement + hostname denylist.** Navigation is
+   constrained; you manage blocked hostnames via
+   `browserTaskHostnameDenylist`.
+3. **IP egress layer (not configurable).** Navigations that resolve to
+   private, loopback, link-local, or cloud-metadata addresses are
+   denied at the egress chokepoint — defence-in-depth against SSRF.
+4. **Payment-path block.** A URL-pattern matcher trips at form-submit
+   time on payment-handoff paths, so a task can't silently push a
+   transaction through. An actual purchase requires the separate,
+   default-off [B-4 token flow](managed-chromium).
+5. **Human-in-the-loop gates.** Anything ambiguous or consequential
+   surfaces as `awaiting_user` / `final_confirm` and waits for your DM.
+
+See **[Safety and Execution](../../concepts/safety-and-execution)** and
+the **[Safety Model](../../concepts/safety-model)** for the full
+picture.
+
+## Configuration
+
+These keys live in the editable config (Settings → Infrastructure):
+
+- `browserTaskMaxConcurrent` — how many tasks may run at once; the rest
+  queue (`pending`).
+- `browserTaskPendingQueueTimeoutMinutes` — how long a `pending` task
+  waits before it is `abandoned`.
+- `browserTaskRespectQuietHours` — when on, tasks defer during your
+  quiet hours rather than running overnight.
+- `browserTaskHostnameDenylist` — hostnames a task may never navigate
+  to (user-managed; there is no shipped default brand/category list).

package/agent-assets/docs/features/operations/cost-tracking.md

@@ -79,6 +79,16 @@ Open **Analytics**. It has two tabs:
 - **Cost** — per-run USD spend. A period selector switches between
   **Daily**, **Weekly**, and **Monthly** windows, with summary cards for
   **Today**, **Last 7 Days**, and **Last 30 Days**. Inside Cost:
+  - **Today's Spend Drivers** — answers "what is costing money *right
+    now*". **Most Expensive Runs Today** lists the day's costliest runs
+    (top 15, most expensive first); click a row for the full per-run
+    detail, including the actually-billed model and cache token breakdown.
+    Next to it, **By Process Today** shows each process's share of today's
+    total, and **Today at a Glance** tracks the day's efficiency: cache
+    hit rate, autonomous spend share, failed-run spend (money paid for
+    runs that produced no result), average cost per run, and total token
+    volume. Everything here uses the agent-day boundary, so the numbers
+    reconcile with the **Today** summary card.
   - **Overview** — a cost-trend chart over the selected period plus a
     **By Event Type** breakdown (which process keys cost the most).
   - **By Backend** — totals and a trend chart split by the backend that
@@ -105,7 +115,7 @@ reactive work such as DMs and mentions always runs.
 - **`autonomousDailyCostCapUsd`** (Autonomous Daily Cost Cap) — when
   today's autonomous spend reaches the cap, the dispatcher skips
   lower-priority routines first, using priority-based degradation:
-  - `hourly_check` — skipped at 100% of the cap
+  - `activity_scan` — skipped at 100% of the cap
   - `roadmap_refresh` — skipped at 120%
   - `evening_review` — skipped at 150%
   - `morning_routine` — last to be cut, only at 200%

package/agent-assets/docs/features/operations/managed-chromium.md

@@ -48,6 +48,7 @@ related:
   - concepts/safety-and-execution
   - reference/disallowed-tools
 ui_anchors:
+  - /browser
   - /settings/integrations/browser-history-managed
   - /settings/integrations/browser-history-managed/b4
 process_keys:

package/agent-assets/docs/features/operations/notifications.md

@@ -23,7 +23,7 @@ ask_examples:
   - How do I limit how often it notifies me?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - notification
   - notify
@@ -74,6 +74,14 @@ by quiet hours and rate limits.
 4. It is sent to the operator over `primaryPlatform` (or, when set, the
    exact channels in `defaultNotificationPlatforms`).
 
+Explicit agent notifications (`POST /api/notify`) ride the same gates
+with one difference: inside quiet hours they are **deferred, not
+dropped** — the full message is queued as a scheduled DM that fires
+when the window ends (visible under Schedule), and repeat sends from
+the same agent overnight coalesce into one combined DM. Outside quiet
+hours the per-hour / per-day caps apply; a capped call is rejected
+(`rate_limited`) rather than silently queued, so the agent can adapt.
+
 ### Safety categories always get through
 
 Notifications tagged `security`, `deadline`, `error`, or `critical`
@@ -104,6 +112,8 @@ The agent can also emit a one-off notification via `POST /api/notify`
 - **A notification you expected never arrived:** check the rate-limit
   counters (`maxNotificationsPerHour` / `maxNotificationsPerDay`) and the
   quiet-hours window — a non-safety alert can be suppressed by either.
+  Explicit `/api/notify` messages caught by quiet hours are not lost —
+  look for a pending scheduled DM under Schedule.
   Safety-category alerts (`error`/`critical`/`security`/`deadline`) are
   never suppressed, so a missing one points at delivery/pairing instead.
 - **Too many notifications:** lower the per-hour / per-day caps or widen

package/agent-assets/docs/features/operations/quiet-hours.md

@@ -25,7 +25,7 @@ ask_examples:
   - Will routines still run during quiet hours?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-06-10
 keywords:
   - quiet hours
   - dnd
@@ -39,7 +39,7 @@ related:
   - features/routines/morning-routine
   - concepts/agent-day
 ui_anchors:
-  - /settings/schedule
+  - /settings/hours
 config_keys:
   - quietHoursStart
   - quietHoursEnd
@@ -65,6 +65,16 @@ the window:
   notification path, sees that it is quiet hours, and is logged as
   `suppressed` — it is **dropped, not held**. You will not receive it
   later.
+- **An explicit agent notification (`POST /api/notify`) is deferred,
+  not dropped.** When an agent session calls the notify endpoint inside
+  the window, the full message is queued as a scheduled DM that fires
+  the moment the window ends (visible under Schedule). Repeat calls
+  from the same agent overnight coalesce into one combined DM at the
+  edge instead of a morning pile-up. `critical` priority bypasses the
+  gate and sends immediately. If you change the quiet-hours window
+  while deferred DMs are pending, they are retimed to the new window
+  end (or released immediately when the new window no longer covers
+  the current time).
 - **A notification already in a batch queue is deferred, not dropped.**
   Aitne batches repeat notifications of the same event type within
   `batchIntervalMinutes`. When a batch is pending and quiet hours are
@@ -82,6 +92,20 @@ the window:
   defaults — boundary `04`, quiet hours `22:00`→`08:00` — that 04:00 run
   lands inside quiet hours, so it runs normally but its proactive output
   is held back or suppressed like any other notification.
+- **A custom Agent can opt its whole run out of the window.** A user
+  Agent created with `schedule.defer_in_quiet_hours: true` (the
+  "Respect quiet hours" toggle in the New Agent form) does not run
+  inside the window at all — the firing itself is pushed to the moment
+  quiet hours end, so a DM-producing Agent delivers fresh results right
+  at the edge instead of burning a 3 AM session whose message would be
+  held anyway. Each deferral is recorded in the action log
+  (`agent.task.deferred_for_quiet_hours`). The default is off, so a
+  silent file-writing Agent deliberately scheduled overnight stays put.
+  Built-in routines never defer. Scheduled browser tasks get the same
+  treatment via `browserTaskRespectQuietHours` (default on). Like
+  deferred DMs, already-deferred runs are retimed when you change the
+  quiet-hours window — shrinking or disabling it releases them at the
+  new edge instead of holding them until the old one.
 
 ## When It Runs / How It Is Triggered
 
@@ -93,12 +117,15 @@ timezone) before sending. The window may wrap midnight — the default
 
 ## Where in the Dashboard
 
-**Settings → Schedule** holds `quietHoursStart` and `quietHoursEnd`,
-shown as a red arc on the same 24-hour ring (dial) as the hourly-check
-active window — drag the handles to adjust either band. There is **no
-overlap validation** — quiet hours and the
-active window are allowed to overlap, and the morning routine fires
-regardless of where the bands sit.
+**Settings → Hours & Notifications** (`/settings/hours`) holds
+`quietHoursStart` and `quietHoursEnd`, shown as a red arc on the same
+24-hour ring (dial) as the activity-scan active window — drag the red
+handles to adjust quiet hours. The active-window band is read-only on
+this page; the activity scan owns its hours, edited from **Agents →
+Activity Scan** (`/agents/activity-scan`). There is **no overlap
+validation** — quiet hours and the active window are allowed to
+overlap, and the morning routine fires regardless of where the bands
+sit.
 
 ## Configuration
 
@@ -112,10 +139,12 @@ regardless of where the bands sit.
 
 - **You expected an important alert to wake you but nothing came.**
   Only the safety categories (`security`, `deadline`, `error`,
-  `critical`) bypass quiet hours. A regular proactive notification that
-  isn't already batched is dropped, not delayed. If you need real-time
-  night alerts for, say, a critical mail label, either ensure that path
-  emits a safety-category notification or disable quiet hours.
+  `critical`) bypass quiet hours. A regular routine-output notification
+  that isn't already batched is dropped, not delayed (explicit
+  `/api/notify` messages are deferred to the window end instead). If
+  you need real-time night alerts for, say, a critical mail label,
+  either ensure that path emits a safety-category notification or
+  disable quiet hours.
 - **A notification fired after the window ended but feels stale.**
   Check `batchIntervalMinutes` — a long interval means a deferred batch
   flush can lag the window end by several minutes. The deferral targets

package/agent-assets/docs/features/operations/schedule-approaching.md

@@ -72,7 +72,7 @@ integration mode:
 - **`native` mode** — the daemon does not poll, so it reads
   `observations` rows instead. These are posted by the agent's
   native-mode `routine.fetch_window` pre-pass. Because that pre-pass
-  refreshes on the hourly-check tick (~60-minute cadence), events
+  refreshes on the activity-scan tick (~60-minute cadence), events
   scheduled with less than ~60 minutes of lead time may miss their
   reminder. Direct mode (5-minute poll) does not have this limit.
 
@@ -94,7 +94,7 @@ If a reminder you expected never arrived:
 - Check the integration mode. Reminders fire in `direct`, `delegated`,
   and `native` modes; only `disabled` mode suppresses them entirely.
 - In `native` mode, short-notice events (< ~60 min lead time) can be
-  missed because observations refresh on the hourly-check cadence.
+  missed because observations refresh on the activity-scan cadence.
 
 ## Related
 

package/agent-assets/docs/features/routines/activity-scan.md

@@ -0,0 +1,220 @@
+---
+schema_version: 1
+slug: features/routines/activity-scan
+title: Activity Scan
+id: activity-scan
+aliases:
+  - hourly
+  - observation consumer
+  - activity scan gate
+category: features
+summary: |
+  A medium-tier routine that fires every interval (default: every 2
+  hours) during active hours,
+  drains the pending observations queue, and decides whether the
+  accumulated change pattern warrants surfacing. Runs through a
+  four-layer gate that keeps quiet days quiet.
+section: routines
+tags:
+  - routines
+  - autonomous
+  - observations
+  - polling
+  - activity-scan
+status: stable
+ui_anchors:
+  - /agents/activity-scan
+  - /settings/hours
+  - /activity?tab=system
+ask_examples:
+  - What does the activity scan do?
+  - When does it run?
+  - How does the activity scan decide whether to escalate?
+  - What is the harvest pre-pass?
+  - How do I tune the gate's freshness window?
+locale: en-US
+created: 2026-04-25
+updated: 2026-06-10
+keywords:
+  - hourly
+  - observations
+  - polling
+  - activity scan
+  - gate
+  - layer 1
+  - layer 2
+  - layer 3
+  - harvestForGate
+  - decideStage
+  - pre-pass
+related:
+  - concepts/observations
+  - concepts/routines
+  - concepts/delegated-mode
+  - features/integrations/browser-history
+process_keys:
+  - routine.activity_scan
+  - routine.activity_scan.triage
+  - routine.fetch_window
+config_keys:
+  - activityScanEnabled
+  - activityScanIntervalMinutes
+  - activityScanActiveStartHour
+  - activityScanActiveEndHour
+  - activityScanMinObservations
+  - activityScanStage2Enabled
+  - activityScanHeartbeatHours
+  - activityScanLowSignalPendingCeiling
+  - activityScanPrePassFreshnessMinutes
+---
+
+# Activity Scan
+
+A medium-tier routine that drains the observations queue every interval
+during active hours and decides whether the accumulated change
+pattern warrants notifying you or appending to `state/today.md`. The
+"decide" step is a four-layer gate designed to keep quiet days quiet
+without missing the moment when something piles up.
+
+## When It Runs
+
+Every **interval minutes** (default 120 — every 2 hours), inside the configured active
+window. Cadence, window, and the enable switch live on the
+activity-scan **agent** — edit them at `/agents/activity-scan`
+(Definition tab → Cadence card; Enable/Disable toggles the routine).
+The legacy `activityScan*` config keys are deprecated fallbacks (see
+[Configuration](#configuration)). The trigger:
+
+- **Skips** when the morning routine has not yet run today
+  (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
+  self-recovery and the activity scan resumes after the morning
+  routine succeeds).
+- **Skips** when another activity scan is in flight (atomic flag).
+- **Skips** when accumulated signal is below the agent's **min
+  observations** threshold and the heartbeat window
+  (`activityScanHeartbeatHours`) hasn't elapsed.
+
+Every tick writes one `agent_actions` row with
+`action_type = 'activity_scan.gate'` so the gate's decisions are
+auditable from `aitne audit` and the dashboard activity feed.
+
+## The Four-Layer Gate
+
+The gate replaced the pre-Phase-9 "30-minute rate-limit" gate. It
+runs on every cron tick; only Layer 4 actually spawns a medium-tier
+agent session.
+
+### Layer 1 — Harvest pre-pass
+
+`ActivityScanCoordinator.harvestForGate` spawns a lite-tier
+`routine.fetch_window` session for each delegated / native
+integration whose `runtime_state.pre_pass_last_run:<key>` is older
+than `activityScanPrePassFreshnessMinutes`. The pre-pass fetches the
+integration's scan window (mail / calendar / Notion) and POSTs the
+results to `/api/observations`, so the rest of the gate sees a
+populated queue instead of stale data.
+
+Telemetry: `agent_actions.detail.harvest_ran` /
+`harvest_integrations` / `harvest_failed_integrations`.
+
+### Layer 2 — Signal compute
+
+`computeActivityScanSignals` reads the observation table mode-blind —
+it filters by source-prefix sets derived from
+`INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
+include unread-mail / event-change / repo-change / browser-history
+clusters; each category produces a (count, last-seen, summary)
+tuple. The pre-pass freshness gate from Layer 1 is what guarantees
+those counts reflect "now", not "an hour ago".
+
+### Layer 3 — Decide stage
+
+`decideStage` is a pure function over the signal snapshot plus the
+per-tick config (heartbeat status, `activityScanStage2Enabled`,
+`activityScanLowSignalPendingCeiling`). It returns one of three stages
+— `stage0_silent`, `stage2`, or `stage3`:
+
+| Stage | What happens |
+|---|---|
+| `stage0_silent` | No agent session. Consume the pending observations and append a single best-effort line to `state/today.md`'s `## Agent Log`. This is the verdict for both "no signals" and "low signal under the ceiling". |
+| `stage2` | Only reachable when `activityScanStage2Enabled = true` (default `false`, so low-signal ticks fall through to `stage3`). Runs a lite-tier `routine.activity_scan.triage` call whose strict JSON output decides `log_only` (→ silent path) vs. `escalate` (→ `stage3`). |
+| `stage3` | Spawn the full medium-tier `routine.activity_scan` session — the visible agent run. Reached directly on high-novelty signals (VIP mail, calendar conflict, overdue agent plan, approaching schedule) or as the cautious default when Stage 2 is off. |
+
+When a Layer 1 pre-pass fails (`harvest.failed`), the gate
+short-circuits to a cautious `stage3` with reason
+`cautious_escalate_prepass_failure` and tags the audit row
+`agent_actions.detail.cautious_escalate = true` — a failed fetch
+should never silently swallow a tick's worth of signals.
+
+### Layer 4 — Dispatch
+
+When Layer 3 returns `stage0_silent` (or Stage 2 returns
+`log_only`), the daemon runs `runSilentActivityScanPath` — a
+daemon-direct write, no agent. When it returns `stage3` (or Stage 2
+returns `escalate`), `enqueueStage3ActivityScan` puts a
+`routine.activity_scan` event on the bus, which becomes the visible
+agent session.
+
+## What It Outputs
+
+- A best-effort line in `state/today.md`'s `## Agent Log` — even the
+  silent path appends one (skipped only if `today.md` is missing or
+  the write lock is held; the observations are still consumed either
+  way).
+- Notifications when warranted (only on a `stage3` agent session).
+- An audit row on every tick:
+  `agent_actions.action_type = 'activity_scan.gate'`, carrying the
+  harvest + signal + stage detail.
+
+## Configuration
+
+The cadence, active window, min-observations threshold, and on/off
+switch are owned by the activity-scan agent: edit them at
+`/agents/activity-scan` (Definition tab → Cadence card;
+Enable/Disable for the switch). The matching `activityScan*` config
+keys below are **deprecated fallbacks** — still accepted by
+`PATCH /api/config` but no longer surfaced in the dashboard; values
+resolve agent override → legacy config key → built-in default.
+
+| Setting | Default | Layer | Notes |
+|---|---|---|---|
+| Enable/Disable (`/agents/activity-scan`) | enabled | trigger | Master switch — the agent's `enabled` flag. Legacy key `activityScanEnabled` (deprecated fallback). |
+| Interval minutes | `120` | trigger | Cron cadence. Cadence card. Legacy key `activityScanIntervalMinutes` (deprecated fallback). |
+| Active start hour | `4` | trigger | Active window start. Cadence card. Legacy key `activityScanActiveStartHour` (deprecated fallback). |
+| Active end hour | `24` | trigger | End-exclusive; `24` ≡ midnight. Cadence card. Legacy key `activityScanActiveEndHour` (deprecated fallback). |
+| Min observations | `1` | trigger | Minimum pending observations before a non-silent stage dispatches; below this the tick records a `below_threshold` skip. Cadence card. Legacy key `activityScanMinObservations` (deprecated fallback). |
+| `activityScanPrePassFreshnessMinutes` | `30` | Layer 1 | Range `0`–`480`. Skip a per-integration fetch if its pre-pass ran more recently; `0` fetches every tick, `480` is cost-minimal. |
+| `activityScanStage2Enabled` | `false` | Layer 3 | Adds the lite-tier triage call; while `false`, low-signal ticks route straight to `stage3`. |
+| `activityScanHeartbeatHours` | `4` | Layer 3 | Range `1`–`48`. Force a non-silent stage at least this often, even on a quiet day. |
+| `activityScanLowSignalPendingCeiling` | `0` | Layer 3 | Range `0`–`20`. At or below this pending count, a low-signal tick stays silent. `0` keeps the cautious default (any pending observation escalates). |
+
+(The agent was named "Hourly Check" until v0.1.11 — old `hourlyCheck*`
+config keys and the `/api/agents/hourly-check` URL are still accepted
+for one deprecation window. `hourlyCheckGateMode` was removed in
+HOURLY_CHECK_GATE_REDESIGN_PLAN
+Phase 4 — the gate has a single execution path now.)
+
+## When Something Goes Wrong
+
+- **Skipped because the morning routine hasn't run.** The
+  dispatcher's `morningRoutineRanToday` gate keys on
+  `agent_actions.result = 'success'`. The skip reason is
+  `morning_routine_pending_for_today` and triggers a
+  `queueMorningRoutineWake` self-recovery. See
+  [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
+- **Stage 3 never fires on a quiet day.** Expected.
+  `activityScanHeartbeatHours` forces a tick occasionally so silence
+  doesn't last indefinitely.
+- **Pre-pass keeps failing for one integration.** Read
+  `agent_actions.detail.harvest_failed_integrations`; the failing
+  integration name is recorded. Usually an auth issue — check
+  `/health.integrationModes` and the integration's settings page.
+
+## Related
+
+- [Observations](../../concepts/observations.md) — what populates the
+  queue Layer 2 reads.
+- [Delegated Mode](../../concepts/delegated-mode.md) — the
+  delegated / native integrations that participate in Layer 1's
+  harvest.
+- [Routines](../../concepts/routines.md)