@aitne-sh/aitne 0.1.9 → 0.1.10

package/agent-assets/docs/troubleshooting/auth-failed.md

@@ -23,7 +23,7 @@ ask_examples:
   - The auth-health pill went red, what now?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - auth failed
   - auth error
@@ -60,8 +60,8 @@ api_endpoints:
    on a healthy install. Re-paste the key on `/settings/models`.
 2. **Subscription-fallback login expired** when no API key was
    registered (the daemon was running on the CLI's local login —
-   `claude`, `codex login`, `gemini auth` — and that session timed
-   out). The recommended fix is to register an API key.
+   `claude auth login`, `codex login`, `gemini` — and that session
+   timed out). The recommended fix is to register an API key.
 3. **Account-level scope change** at the provider (key disabled,
    project deleted, billing suspended). For cloud-provider auth
    (Bedrock / Vertex / Foundry for Claude, Vertex AI for Gemini),
@@ -87,13 +87,14 @@ re-probes immediately — no restart needed.
 **If the backend is on the subscription fallback:** the recommended
 fix is to register an API key on `/settings/models`. The same picker
 also exposes cloud-provider auth — Bedrock / Vertex / Foundry for
-Claude, Vertex AI for Gemini. (Codex Azure OpenAI is not offered here;
-it needs a `~/.codex/config.toml` the env-mirroring path cannot write,
-so Codex stays direct-key only.)
+Claude, Vertex AI for Gemini, and Azure OpenAI for Codex. (Codex Azure
+OpenAI needs a `config.toml` in addition to env vars; the daemon writes
+a managed one under `<dataDir>/codex-home/` and points `CODEX_HOME`
+there, leaving your `~/.codex/` untouched.)
 
 If you cannot or do not want to register a key, re-run the
-corresponding CLI login (`claude`, `codex login`, `gemini auth`) and
-the daemon picks up the new credentials on the next probe. Some
+corresponding CLI login (`claude auth login`, `codex login`, `gemini`)
+and the daemon picks up the new credentials on the next probe. Some
 backends also expose an in-dashboard device-code recovery flow
 (`recovery/start` → `recovery/code`) reachable from the pill's
 recovery hint. Note that subscription auth is not provider-supported

package/agent-assets/docs/troubleshooting/dashboard-shows-degraded.md

@@ -13,9 +13,8 @@ category: troubleshooting
 summary: |
   A red "Daemon degraded" banner appears above every page when the daemon
   enters degraded mode. This almost always means your Obsidian-style primary
-  vault is unreachable (path moved, drive unplugged, or not yet seeded), or a
-  context migration is in progress. While degraded, every context write is
-  refused with HTTP 503.
+  vault is unreachable (path moved, drive unplugged, or not yet seeded). While
+  degraded, every context read AND write is refused with HTTP 503.
 section: troubleshooting
 status: stable
 tags:
@@ -29,7 +28,7 @@ ask_examples:
   - Why are context writes being refused with 503?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - degraded
   - degraded banner
@@ -62,8 +61,10 @@ related:
   followed by the offending path.
 - An **Open Management Mode** button on the right of the banner (links to
   Settings → Management Mode).
-- Any routine or skill that writes a context file fails: the context API
-  returns **HTTP 503** for every `POST`/`PUT`/`PATCH`/`DELETE` while degraded.
+- Any routine or skill that touches a context file fails: while degraded the
+  context API returns **HTTP 503** for every request — reads (`GET`) as well as
+  writes (`POST`/`PUT`/`PATCH`/`DELETE`) — so the agent never reads or writes a
+  stale fallback location.
 
 ## What "Degraded" Actually Means
 
@@ -83,15 +84,21 @@ The `reason` in the banner is one of:
 | `primary_vault_unreachable`    | The configured vault path doesn't exist, isn't a directory, or isn't writable (e.g. an external drive was unplugged). |
 | `primary_vault_not_configured` | Vault mode is Obsidian but no `primaryVaultPath` is set. |
 | `primary_vault_missing_content`| The path is reachable but doesn't carry the expected vault markers (it was never seeded / restructured). |
-| `migration_in_progress`        | A context-vault migration (`/api/setup/migrate-context`) is running. Writes are gated until it finishes; reads still work. This one clears itself. |
+
+A context-vault migration (`POST /api/setup/migrate-context`) is a **separate**
+state, not a degraded reason — it does **not** raise this banner. During a
+migration the daemon engages a context-write gate (`migration_in_progress`):
+writes return HTTP 503 while reads still work, `/api/health` stays
+`"status":"ok"`, and the gate clears itself when the migration finishes.
 
 ## Diagnostic Steps
 
 1. **Read the banner.** The `reason` and `path` tell you most of the story.
 2. `aitne logs` — look for `Vault health probe entered degraded mode`; the
    logged `reason` matches the banner.
-3. If the reason is `migration_in_progress`, **wait** — the migration releases
-   the write gate when it completes; do not restart mid-migration.
+3. If a context-vault migration is running (write-gate `migration_in_progress`
+   rather than the banner), **wait** — the migration releases the write gate
+   when it completes; do not restart mid-migration.
 4. Otherwise the issue is your vault path. Confirm it exists and is writable:
    - `ls -ld "<path-from-banner>"` — the directory must exist.
    - `df -h "<path-from-banner>"` — confirm the volume is mounted with free

package/agent-assets/docs/troubleshooting/messaging-not-pairing.md

@@ -22,7 +22,7 @@ tags:
 status: stable
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - magic phrase
   - owner channel
@@ -85,7 +85,7 @@ All secrets are single-use and expire after **5 minutes**.
 
 ## Diagnostic steps
 
-1. On `/connections/messaging`, click **Regenerate phrase** (Slack /
+1. On `/connections/messaging`, click **Generate pairing phrase** (Slack /
    Discord) or re-open the QR / deep link (Telegram / WhatsApp) so you
    start a fresh 5-minute window.
 2. For Slack / Discord, send **only** the four words — no surrounding

package/agent-assets/docs/troubleshooting/quota-exhausted.md

@@ -26,7 +26,7 @@ ask_examples:
   - Why did an autonomous run get skipped for the cost cap?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - quota
   - BackendQuotaError
@@ -54,8 +54,9 @@ related:
 - Fallback ran the next routine instead of main.
 - Or: an autonomous run was skipped with reason
   `autonomous_cost_cap_exceeded` — this is a *separate* safety net
-  (`autonomousDailyCostCapUsd` / `autonomousMonthlyCostCapUsd`,
-  default off) that skips only autonomous work, never reactive DMs.
+  (`autonomousDailyCostCapUsd`, default off) that skips only autonomous
+  work, never reactive DMs. (`autonomousMonthlyCostCapUsd`, also default
+  off, is notifications-only — it never skips a run, just alerts.)
   It is not a provider quota error; raise the cap on `/settings/models`
   or wait for the next agent day.
 
@@ -92,9 +93,9 @@ related:
    account's spending / rate-limit settings. For cloud providers,
    open the matching console (AWS / GCP / Azure) and check the
    per-region / per-model quota.
-4. If on the subscription fallback, the backend card shows the
-   "next reset" timestamp for the rolling window. Consider
-   registering an API key — see
+4. If on the subscription fallback, the `BackendQuotaError` message in
+   Activity carries the "next reset" timestamp for the rolling window
+   (when the provider reports one). Consider registering an API key — see
    [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Confirming the Fix

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

@@ -1,6 +1,6 @@
 ---
 name: agent-actions
-description: Load when the running session needs to write structured metadata into its own `agent_actions` row so daemon-side consumers (morning-routine AgentJournalAppender, anomaly surfacing, audit log) read structured data instead of parsing prose.
+description: Load near the end of a morning-routine / dispatcher session to record dayType, anomalies, inbox stats, and files-touched into your own `agent_actions` row, so daemon-side consumers (morning-routine journal appender, audit log) read structured data instead of parsing prose.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -41,7 +41,8 @@ header attachment for you — you do not type them. The endpoint returns
 if no in-flight row matches your session — typically because the row
 has already settled to a terminal `result`, or because the dispatcher
 spawned the session without the pre-insert step that the morning
-routine's pipeline orchestrator owns. Surface as anomaly and continue.
+routine's pipeline orchestrator owns. Record it in this endpoint's
+`anomalies` field (when accessible) or DM the operator, then continue.
 
 ## Metadata shape
 
@@ -51,12 +52,12 @@ The morning-routine Stage A is the primary caller. Its expected shape:
 
 | Field | Type | Purpose |
 |---|---|---|
-| `dayType` | `"weekday" \| "weekend" \| "focus" \| "off"` | The day-type Stage A derived. ⑥ AgentJournalAppender writes this into agent/journal.md's header line. |
-| `anomalies` | `string[]` | Free-form anomalies you encountered (e.g. "AgentPlan cardinality mismatch: today.md has 6 rows, batch had 5"). ⑥ surfaces these in agent/journal.md and `pnpm audit` filters on them. |
-| `filesTouched` | `string[]` | Paths your turn wrote to (e.g. `context/today.md`, `context/roadmap.md`). |
+| `dayType` | `"weekday" \| "weekend" \| "focus" \| "off"` | The day-type Stage A derived. ⑥ AgentJournalAppender writes this into journal/agent.md's header line. |
+| `anomalies` | `string[]` | Free-form anomalies you encountered (e.g. "AgentPlan cardinality mismatch: today.md has 6 rows, batch had 5"). ⑥ surfaces these in journal/agent.md. |
+| `filesTouched` | `string[]` | Paths your turn wrote to (e.g. `state/today.md`, `plans/roadmap.md`). |
 | `inboxStats` | `{triaged, movedToScratch, dmConfirmsSent, secretsSkipped}` | Inbox triage counts from Step 4. All keys integers >= 0. `secretsSkipped` is collected but NOT rendered by ⑥; surface secret-skip events through `anomalies` as well so they reach the audit trail. |
 | `morningChecks` | `string[]` | Short labels for every Step 8 `policies/routines/morning.md` extension check executed (e.g. `"water bottle filled"`). ⑥ joins these with `, ` into the `Checks from routines/morning.md:` bullet. Empty array → renders as `(none)`. |
-| `scheduleBatchSize` | `number` | Cardinality you observed when posting to `/api/schedule/batch`. Mirrors what was POSTed so ⑥ can detect cardinality mismatches against today.md. |
+| `scheduleBatchSize` | `number` | Cardinality you observed when posting to `/api/schedule/batch`. Informational metadata mirroring what was POSTed. |
 
 The endpoint accepts any well-formed JSON object — these are the keys
 the morning-routine pipeline consumes. Skills can extend the shape
@@ -71,7 +72,7 @@ curl -s -X PATCH http://localhost:8321/api/agent-actions/self \
     "metadata": {
       "dayType": "weekday",
       "anomalies": [],
-      "filesTouched": ["context/today.md", "context/roadmap.md"],
+      "filesTouched": ["state/today.md", "plans/roadmap.md"],
       "inboxStats": { "triaged": 4, "movedToScratch": 4, "dmConfirmsSent": 1, "secretsSkipped": 0 },
       "morningChecks": ["water bottle filled", "calendar synced"],
       "scheduleBatchSize": 5
@@ -86,37 +87,20 @@ Success (200):
 
 ## Errors
 
-Every error response uses the **agent-consumable envelope**:
-
-```jsonc
-{
-  "ok": false,
-  "summary": "Request rejected: agent_actions.session_identity_missing on headers.x-pa-event-correlation-id.",
-  "errors": [
-    {
-      "rowIndex": null,
-      "code": "agent_actions.session_identity_missing",
-      "field": "headers.x-pa-event-correlation-id",
-      "received": "<missing>",
-      "expected": "x-pa-event-correlation-id and x-process-key headers identifying the running session",
-      "hint": "The pa-api shim auto-injects these from PA_EVENT_CORRELATION_ID and PA_PROCESS_KEY when running inside a dispatcher-spawned session.",
-      "skillAnchor": "agent-actions#self-write-auth",
-      "severity": "error"
-    }
-  ],
-  "retryable": false
-}
-```
+Failures return an agent-consumable envelope (`ok:false`) carrying a
+`code`, a `hint`, and a `skillAnchor` back into this skill. The two
+session-state codes below are `retryable:false` — do NOT re-fire; record
+the failure in this endpoint's `anomalies` field (when accessible) or DM
+the operator, then continue. A malformed-body code is retryable — fix the
+body and resend.
 
-### Codes the endpoint can emit
+Two codes reflect session state you must reason about:
 
-| Code | When | Fix |
-|---|---|---|
-| `agent_actions.session_identity_missing` | `x-pa-event-correlation-id` or `x-process-key` header is absent / empty. | Running inside a dispatcher-spawned session the pa-api shim attaches both headers from env. If you see this, the session is misconfigured — surface it as an anomaly via `<safety_violation>` and stop. Not retryable in the same turn. |
-| `agent_actions.session_row_not_found` | No in-flight `agent_actions` row matches `(event_id, action_type)`. | Either the row has already settled to a terminal result (success/failed/partial) and your PATCH arrived late, or the dispatcher spawned this session without the orchestrator-side pre-insert that the morning-routine pipeline relies on. Either way, the PATCH cannot land — surface as anomaly and continue. Not retryable. |
-| `agent_actions.body_not_object` | Request body is not a JSON object. | POST `{"metadata":{…}}`. |
-| `agent_actions.metadata_field_invalid` | `metadata` slot is missing, not an object, an array, or carries non-JSON-serialisable values (functions, Symbols, BigInts). | Pass a plain JSON object literal. Arrays go inside named keys (e.g. `anomalies:[…]`). |
-
-`retryable:false` means the agent should NOT retry the same call; it
-should surface the failure as a structured anomaly (via this endpoint's
-`anomalies` field when accessible) or DM the operator.
+| Code | When |
+|---|---|
+| `agent_actions.session_identity_missing` | `x-pa-event-correlation-id` or `x-process-key` header is absent / empty — the session is misconfigured. The shim normally attaches both from env. |
+| `agent_actions.session_row_not_found` | No in-flight row matches `(event_id, action_type)` — either the row already settled to a terminal result and your PATCH arrived late, or the dispatcher spawned the session without the orchestrator-side pre-insert. |
+
+A malformed body fails with `agent_actions.body_not_object` (send
+PATCH `{"metadata":{…}}`) or `agent_actions.metadata_field_invalid`
+(pass a plain JSON object; arrays go inside named keys).

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

@@ -28,7 +28,10 @@ recurring DM with no autonomous work, use `dm_session` (above), not an Agent.
 ## Before creating — dedup (mandatory)
 
 1. `GET /api/agents` — does an enabled Agent already do this on this cadence? If
-   so, do not create a duplicate (edit it via the dashboard / `PATCH /api/agents/:slug`).
+   so, do not create a duplicate. To edit one: `PATCH /api/agents/:slug` only
+   toggles `enabled` (field edits return `400 user_agent_edit_via_file`); to
+   change a user Agent's prompt/schedule/backend, edit its `agent.md`
+   (`PATCH /api/context/policies/agents/<slug>/agent.md`) or the dashboard editor.
 2. `GET /api/recurring-schedules?enabled=true` — confirm no existing recurring
    row already covers the cadence.
 
@@ -54,8 +57,12 @@ curl -s -X POST http://localhost:8321/api/agents \
 ```
 
 Fields:
-- **`slug`** — kebab-case, unique, immutable after creation (the `/agents/<slug>` URL).
-- **`name`**, **`description`** — human labels shown in the dashboard.
+- **`slug`** — kebab-case, must start with a lowercase letter (`^[a-z][a-z0-9-]*`),
+  unique, immutable after creation (the `/agents/<slug>` URL). A leading digit or
+  hyphen is rejected as `invalid_definition` on field `slug`.
+- **`name`**, **`description`** — required human labels shown in the dashboard; an
+  empty/omitted `description` is rejected as `invalid_definition` on field
+  `description`.
 - **`schedule.kind`** — `"recurring"` (structured, preferred) or `"cron"` (raw
   expression). A `one_shot`/`event` schedule is rejected with
   `one_shot_not_supported` (use `/schedule` for one-time work). Note:
@@ -77,9 +84,11 @@ Fields:
   in the resolved timezone (`min hour day-of-month month day-of-week`). Examples:
   `0 9 * * *` (daily 09:00), `0 8 * * 1` (Mondays 08:00), `0 * * * *` (hourly at
   :00), `0 */2 * * *` (every 2 hours), `0 18 1 * *` (1st of each month 18:00).
-  Only cron shapes that map to a recurrence are accepted: minute a single value;
-  hour a single value or `*` / `*/N`. Sub-hourly steps (`*/30`) and hour
-  ranges/lists are NOT representable — pick one explicit cadence.
+  A syntactically-valid cron is accepted at create (`201`, valid row) even if it
+  cannot be mapped to a recurrence — but a non-mappable shape (sub-hourly steps
+  like `*/30`, hour ranges/lists like `9-17`) is never paired and silently never
+  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.
 - **`backend`** — optional. `tier` is `lite`/`medium`/`high` (cost/capability knob;
   the standalone control that works). `process_key` defaults to `agent.task`;

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

@@ -27,21 +27,7 @@ Only the following tools are available inside this skill. Everything else is den
 | `Write` | Create the file to upload (text, markdown, CSV, JSON, YAML). |
 | `Bash(curl *)` | Issue exactly one POST to the daemon per file. |
 
-### Commands that WILL be denied — do not attempt
-
-The Claude Code permission classifier blocks these patterns under `dontAsk`. Attempting them wastes a turn and confuses the user.
-
-- **Any shell expansion of an environment variable**: `$PA_TURN_TOKEN`, `$HOME`, `$(date +%Y)`, `` `whoami` `` — all auto-denied. This is why the turn token is injected by the daemon's curl wrapper instead of being passed inline (see below).
-- `ls /tmp/...` / `ls <absolute-path>` — absolute-path listings are auto-denied.
-- `cat <file>`, `head`, `tail`, `stat`, `file`, `test -f`, `echo <anything>` — none are on the allowlist.
-- Chained commands via `&&`, `||`, `;`, `|` — each segment is evaluated separately; any segment outside the allowlist fails the whole line.
-- `python3 ...`, `pandoc`, `node <script>`, `sh -c`, etc. — not on the allowlist. Binary/PDF/chart generation is out of scope for Phase 1; stick to text formats you can `Write`.
-
-If you *think* you need one of the above, the answer is to pre-compute the value in your reasoning, write it as a literal, and invoke curl once with no substitutions.
-
-## Per-turn capability token
-
-The daemon issues a per-turn token and makes the session's curl wrapper (`.pa/bin/curl`) attach it automatically to requests to `/api/chat/outbound-attachments`. **Do not pass `X-Turn-Token` yourself** — inline `$PA_TURN_TOKEN` expansion is blocked by the permission classifier, and the wrapper already handles this for you.
+- **curl with literal strings only.** No `$VAR` / `$(...)` / backticks / pipes / chained commands (`&&`, `||`, `;`, `|`) — the `dontAsk` classifier silently denies them. Pre-compute any value in your reasoning and write it as a literal. The session's curl wrapper (`.pa/bin/curl`) injects `X-Turn-Token` from `PA_TURN_TOKEN` for you — never pass it yourself, and binary/PDF/chart generation (`python3`, `pandoc`, `node`) is out of scope for Phase 1; stick to text formats you can `Write`.
 
 If the turn has already ended (or no token was issued), the daemon returns HTTP 403 `missing_turn_token`. Treat that as a terminal signal, not something to retry.
 
@@ -56,21 +42,19 @@ curl -s -X POST http://localhost:8321/api/chat/outbound-attachments \
   -H "X-Filename: weekly-summary.md" \
   -H "X-Caption: Weekly summary" \
   -F "file=@/tmp/weekly-summary.md"
-# → {"id":"<uuid>"}                      on success
-# → {"error":"missing_turn_token"}       HTTP 403
-# → {"error":"invalid_turn_token"}       HTTP 403
-# → {"error":"too_large"}                HTTP 400
-# → {"error":"disallowed_mime"}          HTTP 400
-# → {"error":"too_many_uploads"}         HTTP 429
+# → {"id":"<uuid>"}                      HTTP 200 — success
+# → 403 — turn token missing/invalid; do not retry (see Errors table)
 ```
 
+Errors return the standard agent-error envelope `{ok:false,summary,errors:[{code,field,hint}],retryable,error:<code>}`. Branch on the flat `error` field (a legacy alias for the single issue code); the codes in the Errors table are accurate.
+
 | Header / field | Purpose |
 |---|---|
 | `file` (form field, binary) | The bytes to deliver. Stream from a file you just created with `Write`. |
 | `X-Filename` | Optional. Overrides the filename shown to the user. Literal string — no substitutions. Default: the multipart `filename` parameter. |
 | `X-Caption` | Optional. ≤ 1024 chars. Literal string — no `$(...)` / backticks. |
 
-> The wrapper silently adds `X-Turn-Token` from `PA_TURN_TOKEN`. Do not add it yourself. If you *do* pass `X-Turn-Token` explicitly (e.g. during local debugging), the wrapper will respect your value and not overwrite it.
+> If you *do* pass `X-Turn-Token` explicitly (e.g. during local debugging), the wrapper respects your value and does not overwrite it.
 
 ### Size and type limits (Phase 1)
 
@@ -84,12 +68,9 @@ Per-turn total across all attachments is capped at **100 MB**; the endpoint retu
 ## Workflow
 
 1. Decide the filename and caption up front (literal strings — no shell interpolation).
-2. Generate the content and write it with the `Write` tool. Use `/tmp/<name>` as the path only — every other path (`~/`, session workdir, context dir, `/var/`, `/Users/...`) is denied by the absolute-block layer (`packages/daemon/src/safety/always-disallowed.ts`). Never write into the session workdir or the context dir.
+2. Generate the content and write it with the `Write` tool. Write scratch files under `/tmp/<name>` — the session workdir is re-materialized between turns and the context dir is daemon-owned, so `/tmp` avoids collisions.
 3. Issue the single curl POST shown above. One file per call.
-4. Branch on the response:
-   - Success (`{"id": "..."}`) — mention the attachment in your reply, e.g. `"Attached: weekly-summary.md"`. You may discard the id; the daemon links it to your message automatically.
-   - HTTP 403 (`missing_turn_token` / `invalid_turn_token`) — the turn has already been released or the skill was invoked outside a turn. Do not retry. Fall back to inline paste and tell the user the attachment could not be sent.
-   - Other errors — follow the table below.
+4. On success (`{"id": "..."}`) mention the attachment in your reply, e.g. `"Attached: weekly-summary.md"` — you may discard the id; the daemon links it automatically. On any error, follow the Errors table below.
 
 Never base-64 embed files into your reply body. Always go through this endpoint.
 

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"}' \
@@ -178,13 +189,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,14 +24,12 @@ 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,
@@ -73,26 +71,27 @@ 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`) for `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,20 +115,16 @@ 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`, …).
+  carries the reason (e.g. `queue_timeout`, `budget_exceeded`,
+  `tool_loop_detected`) — quote it verbatim.
 
 ## Force-stop — "stop" / "cancel" / "abort" / "止めて"