@aitne-sh/aitne 0.1.9 → 0.1.11

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`.

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

@@ -0,0 +1,100 @@
+---
+name: background-task-reply
+description: |
+  When a background task is parked on a clarifying question and the
+  owner's DM answers it, relay the answer via
+  POST /api/background-task/<taskId>/clarify. Use ONLY when a task is in
+  awaiting_user AND the conversation shows the question was just asked.
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Background Task — clarification relay
+
+A detached background task can pause to ask the owner one question
+(`awaiting_user`). The daemon already DMed that question to the owner, in
+your voice — you did NOT author it and you do not poll for it. You act only
+when the owner comes back with an answer, translating their natural-language
+reply into the structured `/clarify` call that un-parks the worker.
+
+This skill does NOT spawn tasks (that's `background-task`) and does NOT
+deliver results (the daemon does that directly).
+
+## Hard rule — never cold-call
+
+This skill is a no-op unless BOTH hold:
+
+1. `GET /api/background-task?state=awaiting_user` returns a non-empty list
+   (call this FIRST). Empty → do nothing; the owner's message is not a
+   clarification answer.
+2. The conversation shows the agent recently asked that task's question —
+   a pending `task_clarification` in your catchup context, or a recent
+   assistant DM that posed it. No recent question → the reply is about
+   something else; leave the parked task alone (its deadline scanner
+   handles a genuine no-answer).
+
+Relaying when the owner didn't answer the question is a worse failure than
+missing an ambiguous reply. When unsure whether the message answers the
+question, ask ONE short clarifier rather than guessing.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/background-task?state=awaiting_user` | List parked tasks. Call FIRST. |
+| GET | `/api/background-task/:id` | Read the open `clarifications` row (`resolved:false`) for its `id` + `question`. |
+| POST | `/api/background-task/:id/clarify` | Relay the answer. |
+
+## Resolving which task
+
+1. `GET /api/background-task?state=awaiting_user`. Usually exactly one
+   parked task; if several, match the owner's reply to the right one by
+   topic / `title`, or ask which.
+2. `GET /api/background-task/<taskId>` — read the open `clarifications`
+   entry (`resolved:false`) and re-read the `question` so you can confirm
+   the owner's message actually answers it. The GET response exposes each
+   clarification row's identifier as `id`; to answer, POST `/clarify` with
+   that value in the request-body field `clarificationId`.
+
+If your catchup context already carries the `clarificationId` in metadata,
+you may use it — but **never surface a `clarificationId` or `taskId` in
+user-visible text** (token hygiene). The GET is the authoritative source.
+
+## Relay the answer
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"clarificationId":"<uuid>","answer":"api first"}' \
+  http://127.0.0.1:8321/api/background-task/<taskId>/clarify
+```
+
+- `answer` (1..8192) — the owner's reply, verbatim and faithful. Do not
+  re-decide the task on their behalf; pass what they said.
+- `clarificationId` is optional — if you omit it the daemon resolves the
+  single open clarification — but prefer passing the explicit id when more
+  than one task is parked.
+
+Then ack briefly ("Got it, picking that back up.") and end the turn — the
+worker resumes on its own and the daemon delivers the eventual result.
+
+Status codes — handle each, don't retry blindly:
+
+- `200` — recorded; the worker resumes. Brief ack.
+- `400 validation_error` — `clarificationId` not a uuid, or `answer` empty
+  / > 8192 chars. Re-read with GET and re-send.
+- `409 not_awaiting_user` (carries `currentState`) — the task already moved
+  on (finished, cancelled, or the window closed). Tell the owner the state
+  plainly; do not re-send.
+- `409 no_open_clarification` — nothing to answer; your state was stale.
+  Re-read with GET first.
+- `409 already_resolved` — the question was already answered (a racing
+  reply landed first). The worker has resumed; do not re-send. A brief ack
+  is enough.
+- `410 expired` — the clarification deadline passed; the worker will time
+  out. Apologise briefly and offer to re-run if relevant.
+- `404 not_found` — stale `taskId`; re-read with GET.
+
+## Localhost only
+
+`http://127.0.0.1:8321/api/background-task/*`. JSON body in single quotes
+(project convention) so the daemon hooks classify the payload as data.

package/agent-assets/skills/browser-history/SKILL.md

@@ -33,23 +33,18 @@ their own destination policy — see the cluster-update flow below.
    topic / domain labels, not raw URLs. There is no path that exposes a
    full URL string; do not try to reconstruct one and feed it to
    WebFetch / Read.
-5. **`context/research/*` writes currently 403.** The cluster-journal /
+5. **`context/research/*` is writable.** The cluster-journal /
    assistance / wiki destinations below (`PUT`/`PATCH
    /api/context/research/<slug>.md`, `…-assistance-<date>.md`,
-   `…-wiki.md`) are the design-intended canonical paths, but `research/`
-   is **not** in the six-class vault write whitelist
-   (`CONTEXT_WRITE_PERMISSIONS`), so those writes return **HTTP 403
-   `context.write_forbidden`** today. `GET /api/context/research/<slug>.md`
-   reads are unaffected. Until the whitelist gains a `research/*` entry,
-   prefer the Obsidian / Notion destination for the wiki flow when
-   configured, and surface the 403 to the owner rather than reporting a
-   successful local-context write.
+   `…-wiki.md`) accept `PUT` and `PATCH` today (`DELETE` is intentionally
+   omitted — concluding a cluster preserves its journal).
 
 ## Endpoint reference
 
 All endpoints respond with JSON validated against
-`packages/shared/src/browser-history-schemas.ts`. The 13 routes below
-are the entire agent-facing surface.
+`packages/shared/src/browser-history-schemas.ts`. 12 of the 13 routes
+below are agent-facing; `GET /status` is operator/dashboard-only (Approve
+tier — see the note after the table).
 
 | Method | Path | Purpose |
 |---|---|---|
@@ -67,19 +62,35 @@ are the entire agent-facing surface.
 | POST | `/api/browser-history/offers/<slug>/mute` | Permanently silence the cluster |
 | POST | `/api/browser-history/research-clusters/<slug>/wiki-written` | Stamp `wikiSummaryWrittenAt`. Call this from `routine.research_wiki_summary` AFTER a successful destination write — never on acceptance. |
 
+**`GET /status` is operator/dashboard-only (Approve tier, Bearer
+required).** An autonomous agent curl from a session workdir carries no
+`Authorization: Bearer` header and is rejected with **401** before the
+handler runs — so `/status` is NOT part of the agent-facing surface. Do
+not call it; treat detector capabilities/lifecycle as out of scope for
+the agent. (The `/offers/<slug>/accept` POST is ReadSensitive, not
+Approve — call it as plain curl; the shim auto-injects `x-read-token`,
+so do NOT add an auth header to it.)
+
 ### Common curl shape
 
 ```bash
-curl --silent --fail \
+curl --silent --show-error \
   http://127.0.0.1:8321/api/browser-history/research-clusters
 ```
 
+Use `--silent --show-error` (not `--fail`): the agent's `curl` runs
+through a session shim that rejects `--fail` / `-f` as an unsupported
+flag — the command hard-errors before any request (it does not merely
+suppress the body). `--show-error` still surfaces the routes' structured
+`{error: …}` JSON on a 4xx, so you can branch on 404 (`not_found`) vs
+400 (`invalid_slug` / `invalid_body`).
+
 For POSTs, pass a single-quoted JSON body so the daemon's hooks do not
 misclassify the payload as a shell command (the project convention from
 `_safety.md`):
 
 ```bash
-curl --silent --fail \
+curl --silent --show-error \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{"kind":"research_assist"}' \
@@ -88,20 +99,36 @@ curl --silent --fail \
 
 ## Flow: routine.research_cluster_update
 
-Runs nightly at the day boundary for every cluster with new activity.
-
-1. List active clusters via `GET /research-clusters`. Filter to
-   `status="active"` and `lastActivityAt` within the last 24h. For each
-   match continue.
-2. Fetch `GET /research-clusters/<slug>/delta` (capped at 31 days; the
-   route returns the most recent buckets first).
+Runs nightly at the day boundary. The daemon already selected exactly
+one cluster and passed it as `event.data.slug` — the fan-out enqueues
+one event per cluster, so operate on **that slug only**. Do **not** call
+`GET /research-clusters` or iterate clusters here; that contradicts the
+single-slug contract.
+
+1. (Optional) Fetch `GET /research-clusters/<slug>` for `displayName`,
+   `topDomains`, and `agentSummaryRevision` (frontmatter for the
+   initial-file case).
+2. Fetch `GET /research-clusters/<slug>/delta`. `days[]` is capped to the
+   most recent 31 days and ordered **oldest-first**. Each entry carries
+   `complete` — `false` only on the still-accumulating current agent
+   day.
 3. Read the existing cluster journal at
    `context/research/<slug>.md` via
-   `GET /api/context/research/<slug>.md`. The first run will return
-   404 — create the file from the template below.
-4. Append today's day entry. **Do not** rewrite earlier days; this is
-   an append-only ledger. Use `PATCH /api/context/research/<slug>.md`
-   with a multi-line `append:` body.
+   `GET /api/context/research/<slug>.md`, and note which
+   `### <YYYY-MM-DD>` headings already exist under `## Day log`. The
+   first run will return 404 — create the file from the template below.
+4. Append a block for **every** `complete: true` day in `days[]` not
+   already present under `## Day log`, **oldest first** (iterate `days[]`
+   in order). Never append a `complete: false` day — its counts are
+   still growing, and a premature block freezes an undercounted day in
+   this append-only ledger (it arrives complete on a later run). This
+   backfills nights that were skipped or failed — a failed run waits a
+   full agent-day before retrying, so missed days accumulate until the
+   next successful run (bounded by the 31-day delta window). **Do not**
+   rewrite earlier days; this is an append-only ledger. Use
+   `PATCH /api/context/research/<slug>.md` with body
+   `{"mode":"append","section":"## Day log","content":"<block>"}`
+   (use `PUT` only for the initial-file case).
 
 Initial-file template (use only when the GET in step 3 returned 404):
 
@@ -125,13 +152,15 @@ Do not invent a thesis the data does not support.)
 
 ## Day log
 
+<!-- one block per missing `complete: true` day in `days[]`, oldest first -->
 ### <YYYY-MM-DD>
 - visits: <meaningfulVisits> (<meaningfulForegroundSec / 60>m foreground)
 - new domains: <newDomains.join(", ")>
 - agent observation: <one neutral sentence about the day's shape>
 ```
 
-Per-day append shape:
+Per-day append shape (one block per missing `complete: true` day,
+**oldest first**):
 
 ```markdown
 ### <YYYY-MM-DD>
@@ -178,13 +207,15 @@ write and enqueued this event.
    - Sources read (domain labels only, never URLs)
    - Open questions
    - Status (active / paused / concluded based on cluster status)
-4. Write the note to:
+4. Write the note to the best available destination, in priority order
+   (each is a fully working target — the local path is a real write, not
+   a 403-doomed fallback):
    - **Obsidian** if `/api/obsidian/*` is configured: PUT to
      `<vault>/inbox/<slug>-wiki-<YYYY-MM-DD>.md`.
    - **Notion** if `/api/notion/*` is configured: create a page under
      the configured "Aitne Inbox" parent.
-   - **Local context** otherwise:
-     `PUT /api/context/research/<slug>-wiki.md`.
+   - **Local context** (`PUT /api/context/research/<slug>-wiki.md`) as the
+     fallback when neither knowledge destination is configured.
 5. After a successful write — and only then — POST
    `/api/browser-history/research-clusters/<slug>/wiki-written` so the
    daemon advances `wikiSummaryWrittenAt`. This is what guards the next

package/agent-assets/skills/browser-history-respond/SKILL.md

@@ -32,7 +32,7 @@ than missing an ambiguous reply.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/browser-history/offers/pending` | List open offers (slug, displayName, kind, offered_at, expires_at). Call FIRST. |
+| GET | `/api/browser-history/offers/pending` | List open offers (slug, displayName, kind, offeredAt, expiresAt). Call FIRST. |
 | POST | `/api/browser-history/offers/<slug>/accept` | Body `{kind: "research_assist" \| "wiki_summary"}` — dispatch the routine. |
 | POST | `/api/browser-history/offers/<slug>/decline` | Silence both options for this cluster for 14 days. |
 
@@ -67,6 +67,11 @@ referenced, or ask:
 
 ## Acknowledgement
 
+For accept, only send the success ack if the response has
+`enqueued:true`. If `enqueued:false` the dispatch did not fire (EventBus
+unwired during the boot window) — tell the owner to retry in a moment
+instead of claiming a result is coming.
+
 Send a one-line ack in the owner's `primaryLanguage` (examples English):
 
 - research_assist accepted: "On it — I'll DM the parallel research

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

@@ -24,22 +24,25 @@ B-4 purchase tokens, or workflow approvals — those live under
 1. **Localhost only.** `http://127.0.0.1:8321/api/browser-task/*`.
 2. **POST, ack, end the turn. NEVER poll for completion.** After a
    successful POST, reply once ("Started — I'll report back when it's
-   done.") and stop. Do not GET `/:id` in a loop waiting for `completed`,
-   do not "wait and check", do not re-issue. Ending your turn has zero
-   effect on the detached task — it keeps running and the daemon DMs the
-   user the result (`✅ Browser task — report`) or, on any
-   failure/cancel/timeout, `🟦 Browser task <id> ended: <state>`. A
-   status GET is allowed ONLY as a single read answering an explicit user
-   question (see "On-demand status"). Polling re-processes the whole DM
-   history every loop and burns your per-turn budget for nothing.
+   done.") and stop. Do not GET `/:id` in a loop, "wait and check", or
+   re-issue. Ending your turn has zero effect on the detached task — it
+   keeps running and the daemon DMs the user the result (`✅ Browser task
+   — report`) or, on any failure/cancel/timeout, `🟦 Browser task <id>
+   ended: <state>`. The only allowed GET is a single on-demand status read
+   answering an explicit user question (see "On-demand status").
 3. **Never echo the `!~xxxxxxxx` final-confirm token.** The daemon DMs it
    directly when the sub-agent trips the final-confirm gate. The user
    types it back themselves; the runner consumes the reply. Do not read,
    log, paraphrase, or relay the token. If the user asks "what was that
    code?", point them at the original DM with the screenshot — that DM is
    the only authoritative source.
-4. **Never invent `clarificationId` / `taskId`.** Both are uuid v4 minted
-   by the daemon; read from GET responses.
+4. **Never invent the clarification id or the task id.** Both are uuid v4
+   minted by the daemon; read them from the daemon's responses, never make
+   them up. The POST-create response carries the task uuid as a top-level
+   `taskId`; on GET (`/:id` and the list) that same task uuid is the row's
+   `id`. The clarification identifier is the clarifications row's `id` on
+   the GET response — to answer you send it back as the request-body field
+   `clarificationId` on POST `/clarify`.
 5. **Do not pre-decline based on the URL or site.** Open navigation is
    the default — the sub-agent decides where to go and the daemon enforces
    a user-curated hostname denylist plus the payment-path block at
@@ -73,26 +76,29 @@ Body:
   dropped both on 2026-05-27 (open navigation). Legacy callers passing
   them are silently ignored, not rejected.
 - `scheduleAt` (ISO 8601) — defer to later; respects quiet hours.
-  Response is `{ status:"scheduled", scheduledFor, scheduleRowId }`.
+  Response is `202` with `{ taskId, status:"scheduled", scheduledFor,
+  scheduleRowId }` (`scheduledFor` is epoch-ms; `taskId` is the same
+  pre-generated id you use for status GETs).
 - `requireFinalConfirm` (default `true`) — keep `true` unless the user
   explicitly asks to skip the gate for a reversible flow.
 
-Immediate response carries `taskId`, `status`, and `queueState`. **Then
-acknowledge once and end the turn.** If `queueState.waitingForSlot ===
-true`, the global cap is full — say so once ("queued behind N task(s);
-I'll start it when a slot opens") and still end the turn. The daemon DMs
-the user when it promotes, and again when it finishes.
+Immediate response carries `taskId`, `status`, and `queueState`; then ack
+once and stop (Hard rule 2). If `queueState.waitingForSlot === true`, the
+global cap is full — say so once ("queued behind N task(s); I'll start it
+when a slot opens"). The daemon DMs the user on promote and on finish.
 
 ## Relaying a clarification — `awaiting_user`
 
-The sub-agent may DM the user a question + screenshot via the originating
-channel. **The daemon authors that DM; you do not, and you do not poll for
-it to appear.** You act only when the user comes back with an answer:
+The daemon DMs the user a question + screenshot via the originating
+channel (you do not author it, and per Hard rule 2 you do not poll for it
+to appear). You act only when the user comes back with an answer:
 
 1. `GET /api/browser-task?state=awaiting_user` — find the parked task.
    Usually one; if several, match topic or ask which.
 2. `GET /api/browser-task/<taskId>` — read the open `clarifications` row
-   (`resolved:0`) for `clarificationId`.
+   (`resolved:false`). The GET response exposes each clarification row's
+   identifier as `id`; to answer, POST `/clarify` with that value in the
+   request-body field `clarificationId`.
 3. `POST /api/browser-task/<taskId>/clarify` with `{clarificationId,
    answer}` (user reply verbatim), then ack briefly and end the turn —
    the runner resumes on its own.
@@ -116,22 +122,18 @@ If (and only if) the user explicitly asks how a task is going, do a
 user names), then `GET /api/browser-task/<taskId>` and report `state`, the
 last `actionLog` entry, and `queueState` if pending. States:
 
-- `pending` — queued (see `queueState`); `running` — sub-agent acting.
-- `awaiting_user` — relay via the `/clarify` round-trip above.
-- `final_confirm` — gated on a `!~xxxxxxxx` token. The daemon DMs the
-  screenshot + token and consumes the user's reply **before you see it**.
-  Do nothing; if the user pings you, point them at that DM.
+- `pending` — queued; read `queueState` for position. `running` — acting.
+- `awaiting_user` / `final_confirm` — relay rules are Hard rule 3 + the
+  clarify section; here just report the state.
 - `completed` — the daemon already DMed the full `✅ Browser task —
   report`. Don't re-post; if asked "what did it find?", quote the
   `report` field verbatim (don't paraphrase).
 - `failed` / `timeout` / `cancelled` / `abandoned` — terminal; the daemon
-  already DMed `🟦 Browser task <id> ended: <state>`. `outcome_detail`
-  carries the reason (`queue_timeout`, `daemon_restarted`,
-  `backend_unavailable`, `tool_loop_detected`, `ask_user_without_yield`,
-  `blocked_request_spike`, `budget_exceeded`, `max_turns_exceeded`,
-  `runner_unavailable`, …).
+  already DMed `🟦 Browser task <id> ended: <state>`. `outcomeDetail`
+  carries the reason (e.g. `queue_timeout`, `budget_exceeded`,
+  `tool_loop_detected`) — quote it verbatim.
 
-## Force-stop — "stop" / "cancel" / "abort" / "止めて"
+## Force-stop — "stop" / "cancel" / "abort"
 
 When the user signals stop, find the task (same identification path as
 status), then `POST /api/browser-task/<taskId>/cancel` with optional