@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,196 @@
+---
+name: notify
+description: Load whenever composing user-facing text — DMs, notifications, briefings, replies, observer alerts. Owns awareness gate + /api/notify.
+when_to_use: Universal message discipline — awareness gate, no ceremony, no readback. Also covers the evening wrap-up contract and quiet-hours flushing.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Notification Decision Guide
+
+A bad notification (noisy, poorly timed, unclear) is worse than no notification.
+
+## Universal user-facing message discipline
+
+Every user-facing message — `/api/notify` call, `scheduled.dm`
+final-text DM (Morning briefing), `scheduled.task` final-text DM,
+message.received reply, observer alert — must clear the gates below.
+Specific contracts (Evening wrap-up, Morning briefing) layer
+additional rules on top; nothing they say overrides a universal rule.
+
+### Awareness gate
+
+The user already knows their own calendar, their own course syllabus,
+their own class times, and the events they themselves set up. Do NOT
+read those items back to them. Lead with what the agent learned from
+input the user could not passively see — new mail, new DM, calendar
+delta, observation, conflict the agent detected, missing prep for a
+known event.
+
+Profile-specific carve-outs (e.g. how this gate applies to interactive
+DM replies vs. daemon-initiated DMs) live in the matching persona
+file's pointer line — see `agent-profiles/<profile>.md ## Principles`.
+
+### No ceremony
+
+The first user-visible line must be a specific fact the agent learned
+or decided since the last message — not a greeting, label, routine
+name, time-of-day opener, or summary header. If a line can be deleted
+without losing information, delete it. **This rule is
+language-agnostic** — it applies whatever language the agent uses
+with the user.
+
+Anti-examples (non-exhaustive — the positive rule above is
+load-bearing, not this list): "Good morning!", "Evening check-in —",
+"Morning briefing —", "Summary:", "Done.", "Sent.", "OK.", "Here's
+your day:", "Heads-up —", "FYI:", "Quick update:". Near-synonyms of
+these in any language also fail the positive rule.
+
+### No internal mechanism names
+
+Never mention `today.md`, `user/profile.md`, `roadmap.md`, `## Agent
+Plan`, `## Agent Log`, `## Handoff`, `did-not-fire`, "Morning
+Routine", "Evening Review", "scheduled.task", "scheduled.dm",
+"dm_session", "sub_flow", or any other internal mechanism in
+user-visible text. Those go in Agent Log only.
+
+### No filler timing commentary
+
+Forbidden — "Just a heads-up", "Still about N hours to go", "About N
+hours left", "FYI". If timing matters, the deadline / event time
+itself carries it.
+
+### No table-of-contents readback
+
+Forbidden patterns: "Schedule: ...", "Tasks: ...", "Notes: ...",
+"Deadlines: ...". These enumerate the user's own data; they already
+have it. (`scheduled.dm` Morning briefing has a section-labelled
+output of its own — those labels are sanctioned by that contract; the
+rule above bars *introducing* such enumeration in any other surface.)
+
+### Language and style
+
+Respond in the user's preferred language. Follow `user/profile.md`
+Communication Style and the Character block in your system prompt.
+Keep technical terms in original form.
+
+### Compactness
+
+Default to the shortest form that conveys the substance — 1–5 short
+lines. No bullet list > 3 items unless the per-message contract
+explicitly allows it (Morning briefing has its own caps).
+
+## When to Notify
+
+Notify when **all three** are true: (1) **actionable** or requires awareness, (2) **time-sensitive**, (3) user **not already aware** via another channel. Common: meeting reminders (15 min before), deadline alerts, task completions, error alerts, conversational replies. (Recurring DM-tone messages — Morning briefing — are delivered as the final assistant turn via `scheduled.dm`'s Morning briefing contract and do NOT use this API.)
+
+## When NOT to Notify
+
+- **Already notified on the same item today** — do a pre-flight dedup
+  scan of `<today>` `## Agent Log` for `notify sent` / `DM sent` /
+  `[cal] ... — reminder sent` referencing the same item within the
+  last 4 hours. If the injected log is truncated (`[...N earlier
+  entries omitted ...]` marker) and you can't rule out a prior
+  notification, `GET /api/context/today` for the full log before
+  firing. Duplicate notifications are the #1 cause of noise.
+- **A pending Agent Plan row / scheduled DM is already set to fire
+  for this item within the next 2 hours** — let the planned channel
+  deliver; don't pre-empt it.
+- **Quiet hours (default 22:00-08:00, configurable)** unless `critical` — schedule for after instead
+- **Rate-limited (429)** — do NOT retry; log skip to Agent Log. If time-critical, upgrade priority at next opportunity
+- **Routine file changes** or **agent internal state** — use Agent Log instead
+- **When in doubt — prefer silence**
+
+Rate-limit defaults: 3/hour, 12/day. The agent CANNOT query
+`notification_log` directly (Approve-tier); use `<today>` `## Agent
+Log` as the authoritative dedup source.
+
+## Priority
+
+| Priority | Use for | Quiet-hours |
+|---|---|---|
+| `critical` | Security alerts, data-loss risk, system errors | Bypasses |
+| `high` | Hard deadlines, urgent messages, meeting starting now | Bypasses |
+| `normal` | Regular reminders, summaries, evening wrap-up | Respects (dropped) |
+| `low` | Background updates, informational FYI | Respects (dropped) |
+
+**Default to `normal`.** Reserve `high` for 8h-delay-matters. Reserve `critical` for 3am-matters.
+
+## Style
+
+One notification per task, under 5 bullets, lead with the action, follow the Character block. Actionable > informational: "3 emails from boss — 1 asks for Q2 plan by EOD" beats "3 emails from boss".
+
+## Evening wrap-up contract
+
+Used by `routine.evening_review`. The prompt owns go/no-go (silence is
+the default; see Step 4a's awareness gate). This section owns format
+rules for the rare evening where the gate plus a positive trigger
+clears the bar.
+
+### Content (in user's preferred language)
+
+1. **The agent-discovered thing the user needs to know** — the
+   specific item that cleared the awareness gate. Lead with substance.
+2. **What's still open** — at most 2 carry-overs with brief reason.
+   Omit if nothing.
+3. **What's next** — only if the agent learned something new today
+   that affects tomorrow. Omit if it's just the user's own calendar
+   reading back to them.
+
+Optional 4th line: brief acknowledgement if today was emotionally
+significant.
+
+### Format — hard limits
+
+- **Maximum 4 short lines.** No markdown headers. No bullet list > 2 items.
+- **No ceremony.** Open with substance, not "Evening Review complete",
+  "Summary:", or "Evening check-in —". Any opener that announces the
+  routine itself rather than the content is forbidden.
+- **No internal names.** Never mention `today.md`, `user/profile.md`, `roadmap.md`, `## Handoff`, `## Agent Plan`, `## Agent Log`, `did-not-fire`, or "Evening Review".
+- **Don't enumerate agent actions.** Surface only what the user would
+  forget by morning AND only things the user couldn't already know
+  from their own calendar / syllabus / scheduled events.
+- **No filler timing commentary** ("Still about 6 hours to go", "Just
+  a heads-up", etc.) — if the timing matters, the deadline itself
+  carries it.
+- **Priority `high`.** The awareness gate raises the bar high enough
+  that anything reaching the user tonight genuinely deserves to. One
+  notification per evening.
+
+### Examples
+
+**Good** (agent surfaced something from new mail today that the user
+hasn't seen yet):
+```
+Sarah's reply on the API spec landed at 6pm — she's blocking on your call on the auth contract before tomorrow's standup.
+```
+
+**Bad — ceremony + internal-state recap:**
+```
+Evening Review complete. Summary:
+today.md updates: Agent Plan rows closed as did-not-fire, Handoff carried over.
+user/profile.md: Raw Signals cleared.
+```
+
+**Bad — agent reading the user's own calendar back to them** (the
+exact shape the user has flagged as unwanted; every element fails the
+awareness gate or the no-ceremony rule):
+```
+Evening check-in — [408019] Week 3 deadline tonight at 11:59pm PT:
+Procurement Plan, RACI Chart, Resource Plan. Still about 6 hours to go.
+Tomorrow: Agile class 6–9pm @ UCLA Extension Gayley.
+```
+The course assignment deadline is on the user's own syllabus and the
+class is on their own calendar — both fail the awareness gate. The
+correct response is silence + one line in ## Agent Log.
+
+## API Reference — POST /api/notify
+
+```bash
+curl -s -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Design review starts in 15 minutes.", "priority": "normal"}'
+```
+Fields: `message` (required, markdown), `priority` (optional: critical/high/normal/low), `platform` (optional, override target).
+Response: `{ "status": "sent", "notificationId": "..." }`. Risk tier: `Autonomous` — the agent decides when to notify; recorded in `notification_log` for the on-demand retrospective.

package/agent-assets/skills/notion/SKILL.delegated.claude.md

@@ -0,0 +1,254 @@
+---
+name: notion
+description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Claude Code; `delegatedBackend` is non-Claude). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Notion (delegated, cross-backend)
+
+Your DM session runs on Claude Code. Notion access has been delegated
+to a *different* backend (Codex or Gemini) whose Notion connector is
+signed in. **You describe Notion intent in natural language; the
+daemon picks the tool.** Tool name divergence between Codex
+(`search`, `notion_create_pages`), Gemini (`notion-search`,
+`notion-create-pages`) and any custom Notion MCP server the user
+installs is invisible to you.
+
+To check which backend currently owns Notion, read
+`~/.personal-agent/integrations.md`. The `/exec` body below is
+backend-agnostic.
+
+## 1. Label resolution (still direct)
+
+Database UUIDs are unstable; the user's labels (e.g. `"projects"`,
+`"meeting-notes"`) map to UUIDs through the daemon's settings store.
+This route is NOT proxied — it returns the configured map even in
+delegated mode:
+
+```bash
+curl -s http://localhost:8321/api/notion/databases
+# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+```
+
+Resolve label → UUID here BEFORE the `/exec` call so your `task`
+prose carries a concrete data-source URL or UUID.
+
+## 2. The single call shape
+
+Every Notion operation in this mode is one POST:
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{"task": "<natural-language intent>", "outputSchema": { ... }, "cacheable": true}'
+```
+
+The daemon:
+
+1. Verifies Notion is in `mode="delegated"`. If not, you get
+   `409 mode_mismatch` — re-read `integrations.md` and stop.
+2. Spawns the delegatedBackend in a tempdir, lets it pick the right
+   tool against the per-task allowed-tools envelope, validates the
+   final JSON against your `outputSchema`, returns it.
+
+`outputSchema` is **required** (4 KB cap). Defaults: `maxToolCalls=7`,
+`maxBudgetUsd=0.05`, `timeoutMs=60000`. Bump up to 15 / 0.50 / 300000
+for genuinely larger intents.
+
+## 3. Worked examples
+
+### Search + structured listing (read)
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "List the top-level pages in the Tasks database (data source <UUID>). For each page return the title, status (if a Status property exists), and last-edited timestamp. Sort by last-edited descending.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pages"],
+      "properties": {
+        "pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "lastEditedAt"],
+            "properties": {
+              "id":           {"type": "string"},
+              "title":        {"type": "string"},
+              "status":       {"type": "string"},
+              "lastEditedAt": {"type": "string", "format": "date-time"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 5,
+    "cacheable": true
+  }'
+```
+
+### Read a page tree (composition)
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Fetch Notion page <UUID> and recursively walk its child pages and toggle blocks. Return id, title, depth, and a flat array of text content per page.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["nodes"],
+      "properties": {
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "depth", "content"],
+            "properties": {
+              "id":      {"type": "string"},
+              "title":   {"type": "string"},
+              "depth":   {"type": "integer"},
+              "content": {"type": "string"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 8,
+    "cacheable": true
+  }'
+```
+
+### Create a page (destructive — confirmation required)
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Create a new page under the Projects database (data source <UUID>) titled \"Migration plan — May\". Body: <BODY>. Properties: Status=\"Active\", Owner=<USER_ID>.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pageId", "url"],
+      "properties": {
+        "pageId": {"type": "string"},
+        "url":    {"type": "string"}
+      }
+    },
+    "allowDestructive": true
+  }'
+```
+
+## 4. Destructive-confirm two-step (`allowDestructive`)
+
+Default is `false`. The subprocess will not run create / update /
+delete / move / duplicate / comment — instead it returns:
+
+```jsonc
+{
+  "needsConfirmation": true,
+  "confirmationPlan": "I will create a new page titled \"Migration plan — May\" under the Projects database with status \"Active\"."
+}
+```
+
+Surface `confirmationPlan` to the user verbatim. On their explicit OK,
+re-issue the **same `task` verbatim** with `allowDestructive: true`.
+Never set `cacheable: true` on the second call.
+
+## 5. `cacheable: true` for read-only Notion lookups
+
+Page reads, database queries, and search results are good cache
+candidates — Notion's content rarely changes minute-to-minute and
+follow-up reads are common. 60s TTL. Skip caching when the user
+explicitly asked about a recent edit, and never set on writes or the
+destructive-confirm second call.
+
+## 6. Decision rules
+
+### Page archive — workaround only
+
+Neither hosted connector exposes a page-archive tool. Pre-existing
+direct-mode trash via `DELETE /api/notion/pages/:id` is unavailable
+here. Phrase the intent as one of:
+
+1. **Property workaround** (preferred when the page lives in a
+   database with a Status property): "Set Status = Archived on page
+   <UUID>." The page stays addressable but drops out of default
+   views.
+2. **Move to a "Trash" page**: "Move page <UUID> under the top-level
+   Trash page (creating Trash if it doesn't exist)." Reversible
+   without admin intervention.
+
+Tell the user when neither option fits — never silently leave a page
+visible the user asked to remove.
+
+### Schema admin — Approve-tier intent
+
+Database / view / data-source mutations change workspace structure.
+Surface what you'd do before invoking, and ask the user. Do not
+auto-confirm "this looks right".
+
+### Mass-update — ask first
+
+The connectors accept up to 100 pages per create call. If the user
+asks for a batch operation that would touch more than ~10 pages,
+summarize the plan and ask before executing.
+
+### Structured database filtering
+
+When the user asks "what tasks are in status X" or anything that maps
+to `WHERE <property> = ...`, phrase the intent as the WHERE clause
+and let the subprocess pick the right primitive
+(`notion_query_data_sources` SQL on Codex, filtered `notion-search`
+on Gemini, etc.).
+
+## 7. Error envelope
+
+`/exec` extends the direct-mode envelope with delegated-mode fields.
+Discriminator: `body.mode === "delegated"`.
+
+| HTTP | `error` | retry? | What to do |
+|---|---|---|---|
+| 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
+| 409 | `mode_mismatch` | no | Notion isn't delegated. Re-read `integrations.md` and stop. |
+| 409 | `precondition` | no | Mode/backend flipped during the queue wait. Re-check state. |
+| 429 | `task_quota_exhausted` | no | Daily cap reached. Wait or surface. |
+| 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Simplify schema. |
+| 502 | `tool_unavailable` | no | No connector tool fits. Surface the gap. |
+| 502 | `tool_failed` | maybe | Connector tool returned an error. Surface verbatim. |
+| 502 | `auth_error` | no | Connector signed out. Re-authenticate. |
+| 502 | `policy_violation` | no | Subprocess attempted an out-of-allowlist tool (anti-injection). |
+| 502 | `loop_aborted` | no | `maxToolCalls` exceeded. Bump or simplify. |
+| 502 | `budget_exhausted` | no | `maxBudgetUsd` exceeded. Caller can raise the cap. |
+| 502 | `post_write_format_failure` | no | Write succeeded; formatting failed. Surface with partial trace. |
+| 503 | `delegated_proxy_busy` | yes | Queue saturated. Backoff and retry once. |
+| 503 | `task_mode_disabled` | no | Operator killed it. Stop. |
+| 504 | `timeout` | yes (1×) | Wall-clock fired. Retry once. |
+| 500 | `subprocess_crashed` | no | Daemon-side defect. Surface and stop. |
+
+Always preserve `body.message` verbatim when reporting to the user.
+
+## 8. Owner notification (opt-in)
+
+The daemon does not auto-DM the owner. When you take an action you
+judge the user wants to know about *now* — archiving a stack of pages,
+moving content out of a long-lived database, posting a public comment
+— call:
+
+```bash
+curl -s -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Archived 7 stale pages under the <db> database."}'
+```
+
+Do not call `/api/notify` for routine reads or single-page edits.
+
+## 9. Cost attribution
+
+Every `/exec` writes one row to `agent_actions` with
+`action_type='delegated_task.exec'`, full token + USD breakdown, and
+the parent `event_id` / `processKey` (the daemon attaches both via
+session env vars). Retrospective calls
+(`GET /api/agent/actions?kind=delegated_task.exec`) surface exactly
+what was spent.

package/agent-assets/skills/notion/SKILL.delegated.codex.md

@@ -0,0 +1,195 @@
+---
+name: notion
+description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Codex CLI; `delegatedBackend` is non-Codex). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+---
+
+# Notion (delegated, cross-backend)
+
+Your DM session runs on Codex CLI. Notion access has been delegated
+to a *different* backend (Claude or Gemini) whose Notion connector is
+signed in. **You describe Notion intent in natural language; the
+daemon picks the tool.** Tool name divergence between Claude
+(`notion-search`, `notion-create-pages`), Gemini (same hyphenated
+form via the user's installed Notion MCP server) and any custom
+Notion MCP server is invisible to you.
+
+To check which backend currently owns Notion, read
+`~/.personal-agent/integrations.md`. The `/exec` body below is
+backend-agnostic.
+
+## 1. Label resolution (still direct)
+
+Database UUIDs are unstable; the user's labels (e.g. `"projects"`,
+`"meeting-notes"`) map to UUIDs through the daemon's settings store.
+This route is NOT proxied — it returns the configured map even in
+delegated mode:
+
+```bash
+curl -sS http://localhost:8321/api/notion/databases
+# → { databases: { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+```
+
+Resolve label → UUID here BEFORE the `/exec` call so your `task`
+prose carries a concrete data-source URL or UUID.
+
+## 2. The single call shape
+
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{"task": "<natural-language intent>", "outputSchema": { ... }, "cacheable": true}'
+```
+
+The daemon:
+
+1. Verifies Notion is in `mode="delegated"`. If not, you get
+   `409 mode_mismatch` — re-read `integrations.md` and stop.
+2. Spawns the delegatedBackend in a tempdir, lets it pick the right
+   tool against the per-task allowed-tools envelope, validates the
+   final JSON against your `outputSchema`, returns it.
+
+`outputSchema` is **required** (4 KB cap). Defaults: `maxToolCalls=7`,
+`maxBudgetUsd=0.05`, `timeoutMs=60000`. Bump up to 15 / 0.50 / 300000
+for genuinely larger intents.
+
+## 3. Worked examples
+
+### Search + structured listing (read)
+
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "List the top-level pages in the Tasks database (data source <UUID>). For each page return the title, status (if a Status property exists), and last-edited timestamp. Sort by last-edited descending.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pages"],
+      "properties": {
+        "pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "lastEditedAt"],
+            "properties": {
+              "id":           {"type": "string"},
+              "title":        {"type": "string"},
+              "status":       {"type": "string"},
+              "lastEditedAt": {"type": "string", "format": "date-time"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 5,
+    "cacheable": true
+  }'
+```
+
+### Create a page (destructive — confirmation required)
+
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/notion/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Create a new page under the Projects database (data source <UUID>) titled \"Migration plan — May\". Body: <BODY>. Properties: Status=\"Active\", Owner=<USER_ID>.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["pageId", "url"],
+      "properties": {
+        "pageId": {"type": "string"},
+        "url":    {"type": "string"}
+      }
+    },
+    "allowDestructive": true
+  }'
+```
+
+## 4. Destructive-confirm two-step (`allowDestructive`)
+
+Default is `false`. The subprocess will not run create / update /
+delete / move / duplicate / comment — instead it returns:
+
+```jsonc
+{
+  "needsConfirmation": true,
+  "confirmationPlan": "I will create a new page titled \"Migration plan — May\" under the Projects database with status \"Active\"."
+}
+```
+
+Surface the plan to the user verbatim. On their explicit OK, re-issue
+the **same `task` verbatim** with `allowDestructive: true`. Never set
+`cacheable: true` on the second call.
+
+## 5. `cacheable: true` for read-only Notion lookups
+
+60s TTL — well-suited to follow-up reads on the same page tree. Skip
+caching when the user explicitly asked about a recent edit, and never
+on writes or the destructive-confirm second call.
+
+## 6. Decision rules
+
+### Page archive — workaround only
+
+Neither hosted connector exposes a page-archive tool. Phrase the
+intent as one of:
+
+1. **Property workaround**: "Set Status = Archived on page <UUID>."
+   Page stays addressable but drops out of default views.
+2. **Move to a Trash page**: "Move page <UUID> under the top-level
+   Trash page (creating Trash if it doesn't exist)." Reversible.
+
+### Schema admin — Approve-tier intent
+
+Database / view / data-source mutations change workspace structure.
+Surface what you'd do before invoking, and ask the user.
+
+### Mass-update — ask first
+
+If the intent would touch more than ~10 pages, summarize the plan and
+ask before executing.
+
+### Structured database filtering
+
+Phrase property-equality intents as the WHERE clause; the subprocess
+picks the right primitive whichever connector is active.
+
+## 7. Error envelope
+
+| HTTP | `error` | retry? | What to do |
+|---|---|---|---|
+| 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
+| 409 | `mode_mismatch` | no | Notion isn't delegated. Re-read `integrations.md` and stop. |
+| 409 | `precondition` | no | Mode/backend flipped during the queue wait. Re-check state. |
+| 429 | `task_quota_exhausted` | no | Daily cap reached. Wait or surface. |
+| 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Simplify schema. |
+| 502 | `tool_unavailable` | no | No connector tool fits. Surface the gap. |
+| 502 | `tool_failed` | maybe | Connector tool returned an error. Surface verbatim. |
+| 502 | `auth_error` | no | Connector signed out. Re-authenticate. |
+| 502 | `policy_violation` | no | Subprocess attempted an out-of-allowlist tool (anti-injection). |
+| 502 | `loop_aborted` | no | `maxToolCalls` exceeded. Bump or simplify. |
+| 502 | `budget_exhausted` | no | `maxBudgetUsd` exceeded. Caller can raise the cap. |
+| 502 | `post_write_format_failure` | no | Write succeeded; formatting failed. Surface with partial trace. |
+| 503 | `delegated_proxy_busy` | yes | Queue saturated. Backoff and retry once. |
+| 503 | `task_mode_disabled` | no | Operator killed it. Stop. |
+| 504 | `timeout` | yes (1×) | Wall-clock fired. Retry once. |
+| 500 | `subprocess_crashed` | no | Daemon-side defect. Surface and stop. |
+
+Always preserve `body.message` verbatim when reporting to the user.
+
+## 8. Owner notification (opt-in)
+
+```bash
+curl -sS -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Archived 7 stale pages under the <db> database."}'
+```
+
+Do not call `/api/notify` for routine reads or single-page edits.
+
+## 9. Cost attribution
+
+Every `/exec` writes one row to `agent_actions` with
+`action_type='delegated_task.exec'`, full token + USD breakdown, and
+the parent `event_id` / `processKey`. Retrospective calls
+(`GET /api/agent/actions?kind=delegated_task.exec`) surface exactly
+what was spent.