@aitne-sh/aitne 0.1.10 → 0.1.11

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

@@ -22,7 +22,7 @@ tags:
 status: stable
 ask_examples:
   - List all the ProcessKeys
-  - What is the default tier for hourly check?
+  - What is the default tier for activity scan?
   - Which ProcessKeys are configurable from the dashboard?
   - What is routine.fetch_window used for?
 locale: en-US
@@ -45,7 +45,7 @@ updated: 2026-06-07
 config_keys:
   - monthlyReviewEnabled
   - delegatedTaskHeavyEnabled
-  - hourlyCheckIntervalMinutes
+  - activityScanIntervalMinutes
   - dayBoundaryHour
 api_endpoints:
   - POST /api/browser-task
@@ -62,7 +62,7 @@ related:
 # ProcessKeys
 
 A **ProcessKey** identifies the kind of work being dispatched (an owner DM,
-the morning routine, an hourly check, …). The dispatcher passes a ProcessKey
+the morning routine, an activity scan, …). The dispatcher passes a ProcessKey
 to the `BackendRouter`, which resolves it to a `{ main, fallback }` backend
 plus an execution tier — the dispatcher never picks a model directly.
 
@@ -81,14 +81,14 @@ The **default tier** column maps to a model size, not a specific id:
 | `routine.today_refresh` | Calendar-drift-triggered (calendar change touching today's items; 5-min dedup, fires ~30s later) — drift-refresh of `state/today.md` | medium | yes |
 | `routine.evening_review` | Daily at 18:00 local (fixed) | medium | yes |
 | `routine.weekly_review` | Friday 19:00 local (fixed) | medium | yes |
-| `routine.monthly_review` | Monthly cadence (gated OFF by default — kill switch `monthlyReviewEnabled` in runtime settings). The routine itself is off by default, but its backend/tier binding is still configurable. | medium | yes |
-| `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | medium | yes |
-| `routine.hourly_check.triage` | Stage 2 triage gate of every hourly check | lite | yes |
+| `routine.monthly_review` | Monthly cadence (gated OFF by default — opt in by enabling the monthly-review agent at `/agents/monthly-review`; the legacy `monthlyReviewEnabled` config key is a deprecated fallback). The routine itself is off by default, but its backend/tier binding is still configurable. | medium | yes |
+| `routine.activity_scan` | Every N interval minutes (default 60) inside the active window — cadence set on `/agents/activity-scan`; legacy key `activityScanIntervalMinutes` is a deprecated fallback | medium | yes |
+| `routine.activity_scan.triage` | Stage 2 triage gate of every activity scan | lite | yes |
 | `routine.fetch_window` | Pre-pass fetcher spawned before each main routine | lite | yes |
 | `routine.user_profile_sweep` | Periodic agent-day profile summarization pass | medium | no |
 | `routine.roadmap_refresh` | Periodic roadmap re-derivation (NOT in `ROUTINE_WINDOWS` — no `routine.fetch_window` pre-pass; the synthesis session itself drives the native-mode MCP fan-out) | medium | yes |
 | `routine.skill_curation` | Background skill-curation / overlay refinement loop (cron cadence picked at `/settings/self-learning`) | medium | yes |
-| `routine.custom.<slug>` | Operator-defined recurrence (see [Custom Routines](../features/routines/custom-routines.md)) | configurable | yes |
+| `routine.custom.<slug>` | Retired — legacy custom routines no longer fire; they were converted to user Agents running under `agent.task` (see [Custom Routines (Retired)](../features/routines/custom-routines.md)). Seen only in historical Activity rows. | — | no |
 | `message.dm` | Owner DM | medium | yes |
 | `message.mention` | @-mention in a paired Slack channel where the agent is invited (DMs are `message.dm`; Telegram/WhatsApp groups are filtered out) | medium | yes |
 | `dashboard.chat` | `/chat` send | medium | yes |

package/agent-assets/docs/reference/skills.md

@@ -59,13 +59,16 @@ related:
 Aitne ships a fixed set of built-in skills the agent loads per session. Most
 are always available; a few are **conditional** — loaded only when a gating
 flag is set (`gmail-lifestyle`, `managed-tasks`) or only for a specific event
-type (`browser-task`, on owner DMs). The table below is the canonical roster.
+type (`browser-task` / `background-task` / `background-task-reply`, on owner
+DMs). The table below is the canonical roster.
 
 | Slug | Purpose |
 |---|---|
 | `agent-actions` | Self-report structured metadata (dayType, anomalies, inbox stats, files-touched) into the session's own `agent_actions` row so daemon-side consumers read structured data instead of parsing prose. Loaded near the end of morning-routine / dispatcher sessions. |
 | `agent-create` | Register a durable, named recurring Agent that fires on a cron cadence via `POST /api/agents`. For ongoing autonomous work (not one-time reminders → `schedule`, not background app-data fetches → `managed-tasks`). Conditional skill loaded on owner DMs / mentions when the message looks like a recurring-work request (gated by `agentCreateActiveForDm`). |
 | `attach` | Attach a generated or downloaded file to the agent's reply when the user expects a file artifact. |
+| `background-task` | Hand a long-running / open-ended task (deep research, a multi-repo CI audit, "monitor X over time", a bulk compile) to the detached background runner via `POST /api/background-task`. Composes a self-contained brief, sets the notification policy (`always` / `if_significant` / `silent`), POSTs, acks, and ends the turn; reads `GET /api/background-task/:id` for follow-up detail. Loaded on `message.received.dm` + `message.received.dm_first`. |
+| `background-task-reply` | Relay the owner's natural-language answer to a background task that parked on a clarifying question (`awaiting_user`) into a structured `POST /api/background-task/:id/clarify` call. No-op unless a task is parked and the conversation shows the question was asked. Loaded on `message.received.dm`. |
 | `browser-history` | Read normalised browser activity through `/api/browser-history/*`. Used by research-cluster journal updates, accept-path dispatches, owner pulls of shopping / reload traces, and the morning research summary. Never reads browser SQLite or profile dirs directly. |
 | `browser-history-respond` | Bridge the owner's natural-language reply to a research-offer DM ("dig deeper" / "summarise") into a structured `/api/browser-history/offers/<slug>/{accept,decline}` call. |
 | `browser-task` | Drive managed Chromium for open-ended browser tasks the user describes in DM. POSTs to `/api/browser-task` with a natural-language description; relays sub-agent clarifications back through DM. Loaded only on `message.received.dm`. |
@@ -84,7 +87,7 @@ type (`browser-task`, on owner DMs). The table below is the canonical roster.
 | `roadmap` | Read / write `plans/roadmap.md` (cross-request write lock). |
 | `schedule` | Schedule future agent wake-ups and DMs via the daemon (writes `agent_schedule` and `recurring_schedules` rows). |
 | `scheduled-managed-task` | Surface and act on Managed Tasks that are due now. |
-| `today` | Read or write `state/today.md` — morning routines, hourly checks, DMs that need a today snapshot. |
+| `today` | Read or write `state/today.md` — morning routines, activity scans, DMs that need a today snapshot. |
 | `user-interview` | Manage the profile-interview queue at `state/profile-questions.md`; ask one question at a time. |
 | `user-profile` | Record user facts — identity, people, work, expertise, habits, goals — into the `identity/*` slices (`profile.md`, `people.md`, `work.md`, …). |
 | `wiki-*` | Build and maintain the personal wiki workspace — `!ingest` / `!compile` / `!ask` / `!lint` / `!trace` / `!connect`. Split into per-process sub-skills under `agent-assets/skills/wiki/` (`wiki-vault-rules`, `wiki-ingest`, `wiki-compile`, `wiki-ask`, `wiki-lint`, `wiki-trace`, `wiki-connect`, `wiki-graduate`), each loaded for its matching `wiki.*` ProcessKey. |

package/agent-assets/docs/troubleshooting/morning-routine-didnt-run.md

@@ -13,7 +13,7 @@ summary: |
   Causes are ordered by frequency: daemon was stopped at the trigger
   time, both backends failed, quota exhausted, the routine threw and is
   mid-retry, or it is a day-boundary subtlety. Most cases self-heal via
-  boot-time catch-up or the retry/stall watchdog.
+  boot/wake catch-up, the missed-fire self-heal, or the retry chain.
 section: morning-routine-didnt-run
 tags:
   - troubleshooting
@@ -28,7 +28,7 @@ ask_examples:
   - How do I regenerate today.md by hand?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - morning routine didn't run
   - morning routine skipped
@@ -37,7 +37,7 @@ keywords:
   - regenerate today
 related:
   - features/routines/morning-routine
-  - features/routines/hourly-check
+  - features/routines/activity-scan
   - concepts/agent-day
   - troubleshooting/auth-failed
   - troubleshooting/quota-exhausted
@@ -52,7 +52,7 @@ config_keys:
 context_files:
   - state/today.md
 ui_anchors:
-  - /settings/routines
+  - /agents/morning-routine
   - /activity
 ---
 
@@ -66,26 +66,42 @@ ui_anchors:
 
 ## Before You Worry: It Often Self-Heals
 
-The morning routine has two recovery paths that usually fix this
+The morning routine has several recovery paths that usually fix this
 without any action from you:
 
 - **Boot-time catch-up.** If the daemon was stopped during the trigger
   window, it fires the unrun morning routine the next time it starts.
   So a missed routine often resolves itself on the next `aitne start`
   or `aitne restart`.
+- **Sleep wake catch-up.** If the machine was asleep at the trigger
+  minute (laptop lid closed at 04:00), the cron fire is silently lost —
+  cron never replays missed ticks. The daemon detects the wall-clock
+  gap when the machine wakes and queues the morning routine itself,
+  along with any missed evening/weekly reviews.
+- **Missed-fire self-heal.** A periodic check (every 10 minutes)
+  notices when the day is more than ~15 minutes old with no morning
+  attempt and nothing queued, and queues the routine. This covers
+  sleeps too short for the wake detector and any other lost trigger.
 - **Retry on failure.** If the routine runs but fails to produce a
   fresh `state/today.md`, the daemon retries up to 3 times with an
   exponential back-off (5, then 10, then 15 minutes). After 3 failed
-  attempts it sends you a DM asking you to regenerate manually. If the
-  wake row sits unfinished for ~2 hours (the stall watchdog threshold),
-  you also get an owner DM so the silence never goes unnoticed.
+  attempts it sends you a DM asking you to regenerate manually.
+- **Hung-run recovery.** If a run starts and then wedges (typically a
+  sleep mid-run that kills the backend connection), the self-heal
+  check re-queues it once the run has been silent past the stall
+  threshold (~2 hours by default) — at most twice per day, after which
+  it alerts instead of re-running. Either way you get an owner DM so
+  the silence never goes unnoticed.
 
 Give it a few minutes, or restart the daemon, before digging deeper.
 
 ## Most Likely Causes (in probability order)
 
-1. **Daemon was stopped at the trigger time.** Check `aitne status`.
-   Boot-time catch-up should cover this once the daemon is back up.
+1. **Daemon was stopped — or the machine was asleep — at the trigger
+   time.** Check `aitne status`. Boot-time catch-up covers the stopped
+   case once the daemon is back up; sleep wake catch-up and the
+   missed-fire self-heal cover the asleep case within minutes of the
+   machine waking.
 2. **Both backends failed.** The routine tried the main backend, fell
    back, and the fallback failed too. Check `/activity` for an error
    outcome and `aitne logs` for the failure.
@@ -99,9 +115,9 @@ Give it a few minutes, or restart the daemon, before digging deeper.
    the routine still "belongs to" yesterday — see
    [Agent Day](../concepts/agent-day.md).
 
-Note: the morning routine takes priority over the hourly check, not the
-other way around. The hourly check skips itself while the morning
-routine is active, so a running hourly check never blocks the morning
+Note: the morning routine takes priority over the activity scan, not the
+other way around. The activity scan skips itself while the morning
+routine is active, so a running activity scan never blocks the morning
 routine.
 
 ## Diagnostic Steps
@@ -109,8 +125,8 @@ routine.
 1. `aitne status` — is the daemon up?
 2. `/activity` — is there a row for `routine.morning_routine`? An error
    outcome points to a backend failure (cause 2 or 3).
-3. `/settings/routines` — the routine list shows the next scheduled
-   fire and recent runs.
+3. `/agents` — the morning-routine card shows its schedule, status,
+   and last run; open `/agents/morning-routine` for recent executions.
 4. `aitne logs` — search for `morning_routine` to see the trigger,
    any fallback, and retry scheduling.
 
@@ -136,5 +152,5 @@ synthesis immediately.
 ## Related
 
 - [Morning Routine](../features/routines/morning-routine.md)
-- [Hourly Check](../features/routines/hourly-check.md)
+- [Activity Scan](../features/routines/activity-scan.md)
 - [Agent Day](../concepts/agent-day.md)

package/agent-assets/docs/troubleshooting/observation-not-detected.md

@@ -7,47 +7,47 @@ aliases:
   - observation missing
   - no observations
   - polling broken
-  - hourly check empty
+  - activity scan empty
 category: troubleshooting
 summary: |
   An expected change (commit, note, calendar move) didn't surface in
-  the hourly check. Most often a polling delay, a vault/repo not
+  the activity scan. Most often a polling delay, a vault/repo not
   watched, or a change the agent authored itself (filtered out).
 section: troubleshooting
 tags:
   - troubleshooting
   - observations
   - polling
-  - hourly-check
+  - activity-scan
 status: stable
 ask_examples:
   - Why didn't the agent notice my new commit?
   - Why didn't a calendar change show up?
-  - Why is the hourly check empty?
+  - Why is the activity scan empty?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - observation
   - polling
   - observer
   - AgentWriteTracker
-  - hourly check
+  - activity scan
 related:
   - concepts/observations
-  - features/routines/hourly-check
+  - features/routines/activity-scan
   - features/integrations/git
   - features/integrations/obsidian
 config_keys:
-  - hourlyCheckMinObservations
-  - hourlyCheckEnabled
-  - hourlyCheckIntervalMinutes
+  - activityScanMinObservations
+  - activityScanEnabled
+  - activityScanIntervalMinutes
 process_keys:
-  - routine.hourly_check
+  - routine.activity_scan
 ui_anchors:
   - /connections/repositories
   - /connections/calendar
-  - /settings/schedule
+  - /agents/activity-scan
 context_files:
   - state/today.md
 ---
@@ -55,24 +55,24 @@ context_files:
 # Observation Not Detected
 
 You made a change by hand — a commit, an Obsidian note, a calendar move — and
-expected the agent to notice it on the next hourly check. It didn't.
+expected the agent to notice it on the next activity scan. It didn't.
 
 This is almost always one of four things: the poller hasn't run yet, the
 source isn't being watched, the agent itself made the change (so it was
-filtered out), or there weren't enough observations to clear the hourly-check
+filtered out), or there weren't enough observations to clear the activity-scan
 gate. Work through them in that order.
 
 ## How detection actually works
 
 Observers (Obsidian, Git, Notion, Calendar) do **not** fire an event per
 change. They poll on a cadence and call `recordObservation(...)`, which
-appends a row to the `observations` table. The hourly check later reads those
+appends a row to the `observations` table. The activity scan later reads those
 rows in a single batch. So a "missing" observation is usually a row that was
 never written, or one that was written but filtered.
 
 `AgentWriteTracker` tags every change as `actor='agent'` or `actor='user'`.
 Changes the agent itself wrote are tagged `actor='agent'` and skipped by the
-hourly check — this is the deliberate anti-loop filter that stops the agent
+activity scan — this is the deliberate anti-loop filter that stops the agent
 from observing its own output.
 
 ## Most likely causes
@@ -84,9 +84,10 @@ from observing its own output.
    was never connected, nothing polls it.
 3. **The change was tagged `actor='agent'`.** If the agent (not you) authored
    the commit or note, the anti-loop filter drops it.
-4. **It was below the gate threshold.** The hourly check only runs its full
-   pass when at least `hourlyCheckMinObservations` (default `1`) pending
-   observations exist. A single low-signal change can be held back.
+4. **It was below the gate threshold.** The activity scan only runs its full
+   pass when at least the activity-scan agent's **min observations**
+   threshold (default `1`; legacy key `activityScanMinObservations`) of
+   pending observations exists. A single low-signal change can be held back.
 
 ## Diagnostic steps
 
@@ -101,21 +102,22 @@ from observing its own output.
 3. **Rule out the agent-authored filter.** If the commit or note was written
    by the agent, that's expected — it's filtered by design. Look for a change
    *you* made by hand to test detection.
-4. **Lower the gate threshold to test.** Temporarily set
-   `hourlyCheckMinObservations` to `1` (its default) on `/settings/schedule`
+4. **Lower the gate threshold to test.** Temporarily set **Min
+   observations** to `1` (its default) on the activity-scan agent's page
+   (`/agents/activity-scan`, Definition tab → Cadence card)
    so even a single observation triggers the check, then make a manual change
-   and wait for the next hourly run.
+   and wait for the next activity-scan run.
 
 ## Confirming the fix
 
 After the next poll runs, a manual change you made should record an
-observation and surface in the next hourly check. You can cross-check recent
+observation and surface in the next activity scan. You can cross-check recent
 agent activity from the CLI with `aitne audit`, which reads the `agent_actions`
 log read-only.
 
 ## Related
 
 - [Observations](../concepts/observations.md) — what gets recorded and why
-- [Hourly Check](../features/routines/hourly-check.md) — the gate and its thresholds
+- [Activity Scan](../features/routines/activity-scan.md) — the gate and its thresholds
 - [Git integration](../features/integrations/git.md)
 - [Obsidian integration](../features/integrations/obsidian.md)

package/agent-assets/docs/troubleshooting/wiki-write-failed.md

@@ -25,7 +25,7 @@ ask_examples:
   - How do I retry the write-strategy probe?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-11
 keywords:
   - wiki write failed
   - wiki API failure
@@ -36,7 +36,7 @@ api_endpoints:
   - /api/wiki/:workspace/health
 ui_anchors:
   - /settings/wiki
-  - /connections/knowledge
+  - /connections/notes
 related:
   - features/wiki/overview
   - guides/use-an-existing-obsidian-vault
@@ -84,7 +84,7 @@ If any of these is missing, the daemon surfaces a structured error:
 
 | Error code | Meaning | Fix |
 |---|---|---|
-| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured (the `obsidian` binary is not resolvable on `PATH`). | Open **Connections → Knowledge** and connect Obsidian via the Obsidian card, then confirm Obsidian 1.12+ is installed with the CLI enabled. |
+| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured (the `obsidian` binary is not resolvable on `PATH`). | Open **Connections → Notes** and connect Obsidian via the Obsidian card, then confirm Obsidian 1.12+ is installed with the CLI enabled. |
 | `EWIKI_CLI_NOT_RUNNING` | The CLI is configured but the Obsidian app is not running, so it cannot reach the sandboxed vault. | Launch the Obsidian app and retry. |
 
 ## Force a Re-Probe

package/agent-assets/skills/agent-create/SKILL.md

@@ -90,6 +90,12 @@ Fields:
   fires. Only shapes that map are actually run: minute a single value; hour a
   single value or `*` / `*/N`. Pick one explicit, mappable cadence.
 - **`schedule.timezone`** — IANA zone; omit to inherit the daemon default.
+- **`schedule.defer_in_quiet_hours`** — boolean, default `false`. When `true`, a
+  firing that lands inside the user's quiet hours is pushed to the window's end
+  instead of running — the whole run moves, so the data is fresh at delivery
+  time. Mechanical rule: **set `true` whenever the Expected output includes
+  DMing the user**; leave it `false` for silent file-writing work deliberately
+  scheduled overnight.
 - **`backend`** — optional. `tier` is `lite`/`medium`/`high` (cost/capability knob;
   the standalone control that works). `process_key` defaults to `agent.task`;
   omit unless you know you need another. (Pinning a backend *engine* without a
@@ -137,6 +143,11 @@ Each morning, surface inbox items that need the user's decision today.
 **Bad prompt:** `"Triage my inbox."` — no requirements, no steps, no output
 contract; the Agent will improvise differently every day.
 
+The Expected-output decision feeds one schedule field: if the output contract
+includes DMing the user, also set `schedule.defer_in_quiet_hours: true` so a
+firing inside quiet hours waits for the window's end instead of producing a
+message that would be held anyway.
+
 ## Responses & errors
 
 - `201 { "status": "created", "slug": "…" }` — the Agent is live; its recurring

package/agent-assets/skills/background-task/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: background-task
+description: Hand a long-running or open-ended task (deep research, multi-repo CI audit, monitor X over time, bulk compile) to /api/background-task. Compose a self-contained brief, set the notification policy, POST, ack, end the turn. Read GET /:id for follow-up detail.
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Background Task — long-running work from DM
+
+A detached worker runs the task in its own session with its own budget.
+**The daemon delivers the result to the user directly — in your own voice —
+when it finishes or needs input. You are NOT in that delivery path.** Your
+job is the front bookend only: scope the task *now*, compose a
+self-contained **brief**, choose a notification policy, POST it,
+acknowledge in one line, and **end your turn**. The worker's run is
+invisible to you.
+
+This is the surface for *generic* long tasks. For an open-ended **browser**
+job (post a tweet, fill a form) use the `browser-task` skill. For a
+*recurring* cadence ("every morning…", "each hour check my PRs") use
+`agent-create` / `schedule` — a background task is a single detached run.
+
+## When to background it (triage)
+
+Background work that is **long-running or open-ended** so the user can keep
+chatting. No duration guess — decide on the signals:
+
+1. **Category** — deep research, a multi-repo / multi-file audit,
+   "monitor / watch X", a multi-step web dig, a bulk compile. Strongest
+   signal.
+2. **Owner signal** — explicit ("take your time", "report back later") or a
+   research-style bang command.
+3. **Scoping reveals size** — if resolving the request shows large or
+   genuinely open-ended work, delegate it.
+
+**Bias toward backgrounding category-1 work; keep plausibly-quick lookups
+inline** (delivery costs a turn's latency). One task per request: "research
+X AND audit Y" → two POSTs.
+
+## Compose the brief — this is the real work
+
+The worker sees ONLY your `brief` (it does not inherit the conversation,
+the user profile, or the management rules). An under-specified brief forces
+a clarification round-trip you can avoid by writing it well *this turn*.
+Resolve ambiguity with the user now, then encode all of:
+
+- **Objective** — the end state as an outcome ("find which repos have a red
+  main build", not "go look at repos").
+- **Scope & inputs** — the concrete inputs the worker can't infer: the repo
+  list, what "failing" means, which sites, the date range.
+- **Output language** — the user's language for `result`, `draft`, and any
+  clarification.
+- **Persona hints** — a line on the user's voice so the `draft` summary
+  reads right if it's sent directly.
+- **Notification policy + criteria** — see below; for `if_significant` the
+  criteria MUST be written into the brief in concrete terms.
+- **Expected output** — what a good `result` contains (a per-repo table, a
+  ranked list, a one-paragraph verdict).
+
+The worker can read owner memory itself to fill in preferences, so you need
+only supply the *task-specific* inputs above. **Promoting an inline task?**
+Also fold in the work you already did (findings, partial results) so the
+worker continues rather than restarting cold.
+
+## Notification policy — you author it
+
+`notificationPolicy` decides whether the worker's result reaches the user.
+The worker doesn't free-judge; it evaluates the policy you set:
+
+- **`always`** (default) — the user asked and wants the answer, even
+  "nothing found / 0 issues". The common case; always delivered.
+- **`if_significant`** — delivered **only if** the concrete criteria are
+  met. Prefer the structured **`significanceCriteria`** array (below) over
+  prose; vague criteria defeat the policy.
+- **`silent`** — never delivered; filed only.
+
+A filed (`silent` / unmet-`if_significant`) result is not lost — it surfaces
+in the daily digest and the user can pull it (see "Filed results" below).
+
+## Endpoints (localhost only)
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/api/background-task` | Create + dispatch, or schedule (`scheduleAt`). |
+| GET | `/api/background-task?state=...` | List (also `notify`, `sinceHours` for the filed pull). |
+| GET | `/api/background-task/:id` | The artifact — verbatim `report`, `draft`, `notify`, clarifications. |
+| POST | `/api/background-task/:id/cancel` | Force-stop. |
+
+Clarifications are answered with the **`background-task-reply`** skill.
+
+## Hard rules
+
+1. **Localhost only.** `http://127.0.0.1:8321/api/background-task/*`.
+2. **POST, ack, end the turn. NEVER poll for completion.** After a
+   successful POST, reply once and stop. Do NOT GET `/:id` in a loop or
+   "wait and check". Ending your turn has zero effect on the detached
+   worker — it keeps running and the daemon delivers the result as a DM in
+   your voice. The only allowed GET is a single on-demand read answering an
+   explicit user question (see "Follow-up detail").
+3. **Never invent `taskId` / `clarificationId`** — uuid v4 minted by the
+   daemon; read them from responses.
+4. **The worker has no messaging tool** — it cannot DM the user; it writes
+   its artifact and *you* (the daemon, in your voice) deliver.
+5. **One task per request.**
+
+## POST — composing a request
+
+`POST /api/background-task` with the self-contained brief:
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"brief":"Audit these repos for a red main-branch CI build: aitne/daemon, aitne/web. \"Failing\" = the latest default-branch run concluded failure. Summary in English. Only notify if at least one repo is red. Output: one line per failing repo with the job.","title":"CI audit","notificationPolicy":"if_significant"}' \
+  http://127.0.0.1:8321/api/background-task
+```
+
+Body:
+
+- `brief` (1..16384) — the self-contained worker prompt above.
+- `title` (1..200, optional) — short human label for status + the DM.
+- `notificationPolicy` — `always` (default) / `if_significant` / `silent`.
+- `significanceCriteria` (optional, `if_significant` only) — up to 12
+  atomic conditions (each ≤500 chars), e.g. `["any repo's main build is
+  red","spend > $100"]`. Worker notifies iff one is met. Omit otherwise.
+- `tier` (optional) — `lite` / `medium` / `high` budget envelope. Default
+  is fine; use `high` only for genuinely heavy research.
+- `maxBudgetUsd` (optional) — override the dollar cap (hard ceiling `15`;
+  a larger value is rejected `400`). Prefer `tier` over a raw dollar value.
+- `scheduleAt` (ISO 8601, optional) — defer the *run* to a fire time (the
+  worker starts then; it is compute, so it runs even during quiet hours).
+  The eventual *result delivery* is what respects quiet hours, not the run.
+  `202` with `{ taskId, status:"scheduled", scheduledFor, scheduleRowId }`.
+  A time more than 60s in the past is rejected `400`.
+
+Immediate response carries `taskId` and `status`. Then ack once and stop
+(Hard rule 2).
+
+## Acknowledgement
+
+One line, no ceremony, no internal mechanism names (`taskId`, "worker",
+"artifact"); your output language is already governed by your policy.
+Structural examples (English): *"Started the audit in the background — I'll
+report when it's done."* / *"On it. I'll dig into that and come back with
+what I find."* Do NOT promise a specific time; say "when it's done".
+
+## Follow-up detail — answer from the artifact, don't guess
+
+The delivered DM carries a *summary*. When the user later asks for precise
+detail it didn't include ("what exactly did it find on repo X?", "show me
+the numbers"), do a **single** read and answer from the verbatim `report`:
+
+```bash
+curl --silent --fail http://127.0.0.1:8321/api/background-task/<taskId>
+```
+
+`report` is the full, unparaphrased result. Quote from it; don't invent
+detail. If you lack the `taskId`, list `state=completed` and match by
+`title`.
+
+## Filed results — the "did that monitor ever run?" pull
+
+A `silent` / unmet-`if_significant` result is filed (`notify=false`), not
+pushed. When the user asks whether a backgrounded task ran:
+
+```bash
+curl --silent --fail "http://127.0.0.1:8321/api/background-task?state=completed&notify=false&sinceHours=168"
+```
+
+Each row carries `title`, `significance`, and `report`. Summarize
+naturally; offer to pull any in full.
+
+## Force-stop — "stop" / "cancel" / "abort"
+
+On a clear stop signal, find the task (by `taskId`, or list
+`state=running,awaiting_user,pending` and match the topic), then
+`POST /api/background-task/<taskId>/cancel` with optional
+`{"reason":"user_cancel"}`. `200` = accepted; `404 not_found` = stale id,
+re-read; `409 already_terminal` = too late, report `currentState`
+verbatim. "wait" is NOT a cancel.
+
+## Scheduling — `scheduleAt` ≠ the `schedule` skill
+
+For "do this research at <time>" use `scheduleAt` in this POST. The
+`schedule` skill is for listing / modifying / cancelling pending schedules;
+a recurring cadence is `agent-create`.