@awebai/oats 0.39.4 → 0.40.1

package/docs/desktop-cli-api.md

@@ -33,13 +33,13 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
  "harnesses":["pi","claude","codex"],"sessionBackends":["tmux"],"launchOptions":["yolo"],
  "remote":["spawn","retire","status","session","session-start","session-restart","launch-config","roster","harvest","schedule","session-upload","operations",
            "readiness","instance-events","instance-git","lifecycle-plans"],
- "features":["retire-home","session-start","session-restart","launch-config","schedule","session-upload","operations","instance-git",
+ "features":["retire-home","session-start","session-restart","launch-config","schedule","schedule-host-caps","session-upload","operations","instance-git",
              "instance-git-remote","souls-declarations","lifecycle-plans","retire-retention","readiness","spawn-preview","instance-events",
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
              "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
              "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show","capture-file","workspace-identity",
-             "server-connect","capability-route","servers-per-workspace","operator-default-soul"],
+             "server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
  "capabilityShowApi":1}
@@ -68,6 +68,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `session-start`, `session-restart` | `oats session start/restart --home` | |
 | `launch-config` | `oats launch-config …`; the selection flags on start and restart | |
 | `schedule` | `oats schedule …` | `scheduleApi: 2` |
+| `schedule-host-caps` | both host-install cap options, their `default` / `none` reset semantics, and cap status reporting; no promise about a particular stored cap value | |
 | `session-upload` | `oats session upload` (and the host's `session receive`) | |
 | `operations` | `oats operation run`; `operations[]` in inspect | `operationsApi: 2` |
 | `instance-git`, `instance-git-remote` | `oats instance git/diff`; the observation's `remote` | `instanceGitApi: 1` |
@@ -106,6 +107,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `server-connect` | `oats server connect`; `oats onboard --check`; `workspaceReadable` on `oats server check --json`, OATS 0.39.0 ([`oats server connect`](#oats-server-connect)) | |
 | `capability-route` | `oats <namespace> <command> … --server <id>` runs the capability command on the server, OATS 0.39.0 ([Capability commands on a server](#capability-commands-on-a-server)) | |
 | `operator-default-soul` | a capability command from a deployment without `--soul` runs as the first soul that provides its namespace (named on stderr); none is `E_BAD_ARGS`, OATS 0.39.0 ([capabilities.md](capabilities.md)) | |
+| `waiting-on-you` | the `waiting` event kind and the session boundary rule; `oats instance waiting` and `oats instance attention`; `waitingOnYou` (with `message`) on `oats status --json` instance rows, on `oats session inspect --json` and in the events read, OATS 0.40.0 ([Waiting on you](#waiting-on-you)) | `eventsApi: 2` |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -148,7 +150,9 @@ stdout (progress goes to stderr):
 A kernel command reads `--flag=value` exactly as `--flag value` (the value is
 everything after the first `=`). `E_BAD_ARGS` for an empty `--flag=`, a value
 on a switch (`--yolo=false` never turns yolo on) and a value that is itself an
-option (`--model=--yolo`). A capability command's own flags are forwarded as
+option (`--model=--yolo`). The one exception is the free-text `--message`
+(`oats instance waiting`, `oats instance attention`): `--message=--text` is
+accepted, and its value is only ever the message. A capability command's own flags are forwarded as
 typed; the kernel reads only its dispatch flag (`--soul`). There is no feature
 string for this: to support older kernels, use the spaced form.
 
@@ -1787,6 +1791,16 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
   in the row),
   `identity` when a provider recorded one, `rollbackIncomplete` and
   `retirePending` when present, and the Desktop facts below.
+- **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
+  message}` when the row is `running: true` and a producer holds a live claim
+  that the instance needs input from a human, else `null` (unknown, not "not
+  waiting"). Its rules are the events read's ([Waiting on you](#waiting-on-you)):
+  one bounded read of the home's log per running row. A remote roster row
+  carries what the remote kernel reports; an older kernel omits the field.
+  `running` is the window's presence, which a crashed harness's fallback
+  shell or a retained dead pane keeps, so a row with a claim is checked
+  against its session (as `oats session inspect` observes it) and reads
+  `null` unless a harness runs there.
 - **`modules`** becomes drift rows `{name, from, commit, current, status,
   reason?}` when the workspace was read. `status` is `current`, `moved` or
   `missing` (`reason`: `capability-absent`, `package-absent`, or the member's
@@ -2153,27 +2167,134 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   `retire-planned`, `retired`, `worktree-retained`, `worktree-removed`,
   `branch-deleted`, `child-spawn-refused`, `launch-warning` (0.30: a
   `launch` hook's warning at session start/restart, `data: {message}`),
-  `recomposed` (from earlier kernels). `producer` is `kernel` or a capability id. Older rows may carry
-  `eventsApi: 1`.
+  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
+  [Waiting on you](#waiting-on-you)). `producer` is `kernel`, a capability id,
+  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
+  `launched` is written by spawn and, since 0.40, once per session start or
+  restart, as soon as the session exists (`data: {harness, backend,
+  launchConfig, phase, startId}`; spawn's row has neither `phase` nor
+  `startId`). `phase` is `start` or `restart`, or `recovered` when a later
+  start adopted an interrupted start's receipt that had no boundary; that row
+  is dated at the receipt's launch time. The boundary is complete per log: a
+  log that missed it gets a copy of the same row (same time and data), never
+  a second one.
 - **Incarnation.** Each row carries the writing home's `createdAt` (or
   `null` for old rows); the top-level `incarnation` is the current home's (or
   `null`). Earlier incarnations are returned as this address's history.
 - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`).
   Rows for another address are dropped and counted in
   `integrity.foreignRows`; torn or invalid lines are counted in
-  `integrity.unreadableRows`. Duplicates are removed.
+  `integrity.unreadableRows`. A row present in both logs is returned once;
+  identical rows repeated within one log (a set, a clear and the same set in
+  one millisecond) are all returned, as many as the log holding the most
+  copies has.
 - **Window.** `count` is the rows after `--since`; `returned` the window
   (`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
   source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
   the last returned row, or `null`.
-- **Waiting.** `waitingClaims[]` is `{producer, waiting, since, reason}` per
-  producer with a claim in the current incarnation (cleared ones included).
-  A producer's latest row with `data.waitingOnYou` decides. `waitingOnYou` is
-  `{since, producer, reason}` of the newest positive claim, or `null`
-  (unknown, not "not waiting"). No kernel path claims waiting today.
+- **Waiting.** `waitingClaims[]` is `{producer, waiting, since, reason,
+  message}` per producer with a live claim in the current incarnation
+  (cleared ones included). A producer's latest row with `data.waitingOnYou`
+  decides. `waitingOnYou` is `{since, producer, reason, message}` of the
+  newest positive claim, or `null` (unknown, not "not waiting"). See
+  [Waiting on you](#waiting-on-you) for the producers and the rules.
 - Errors: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
   `E_BAD_ARGS`, `E_EVENTS_FAILED`.
 
+### Waiting on you
+
+Feature `waiting-on-you` (OATS 0.40.0): an instance blocked on a human (a
+permission prompt, a question, an agent asking for an answer) says so through
+a producer's claim. **Claims are display-only:** nothing in the kernel acts
+on `waitingOnYou`. In particular `oats session input` behaves exactly as
+before whether or not a claim is set.
+
+```text
+oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] --json
+oats instance attention [--message <text>] [--clear] --json
+```
+
+```json
+{"eventsApi":2,"instance":"dev-1","home":"/w/agents/dev/instances/dev-1","producer":"oats.core","changed":true,
+ "waitingOnYou":{"since":"2026-10-03T12:00:00.000Z","producer":"oats.core","reason":"permission","message":null}}
+```
+
+- **The row.** A claim is a `waiting` event, `data: {waitingOnYou: true,
+  reason, message?}` or `{waitingOnYou: false}`, appended to both logs, with
+  `producer` the caller's `--producer`.
+- **`waiting`.** `--producer` matches `^[a-z0-9][a-z0-9._/-]{0,63}$` and is
+  not `kernel`. `set` needs `--reason`, one of `permission`, `question`,
+  `attention` (closed). `clear` refuses `--reason` and `--message`. The home
+  is `--home`, else `$OATS_INSTANCE_HOME`, else the instance home enclosing
+  the working directory; it must be a home of its own name under the scope
+  (`--dir`, else the agents root the home sits in).
+- **`attention`** is the agent's own claim, run by the instance from its
+  home: sugar for `waiting set --producer agent --reason attention
+  [--message]`, and `--clear` for `waiting clear --producer agent`. Its home
+  comes only from `$OATS_INSTANCE_HOME`: it has no `--home` or `--dir` and
+  never targets another instance. Unset, or not an instance home (no readable
+  `instance.json`), is `E_USAGE`. `--clear` with `--message` is `E_BAD_ARGS`.
+- **`--message`**: one line of 1 to 200 characters (code points). Refused,
+  as `E_BAD_ARGS` naming `--message`: control characters (`\p{Cc}`: C0, DEL,
+  C1; so no newline, tab or ESC), the line and paragraph separators U+2028
+  and U+2029, the bidi embeddings, overrides and isolates U+202A–202E and
+  U+2066–2069, the invisible U+200B (zero width space), U+2060 (word
+  joiner) and U+FEFF (BOM), and the tag characters U+E0000–E007F. Everything
+  else is allowed, including ZWJ and ZWNJ (U+200C, U+200D: emoji sequences
+  such as 👩‍💻, Persian and Indic text), the marks LRM, RLM and ALM (U+200E,
+  U+200F, U+061C) and the soft hyphen. A message that
+  starts with `--` goes inline, `--message=--deploy failed`: that value is
+  only ever the message, never a flag (`--message=--clear` sets the message
+  "--clear"). The spaced form `--message --deploy` reads `--deploy` as a
+  flag and is `E_BAD_ARGS`. It is stored as given, only on a
+  positive claim. The reader applies the same rule again: an invalid stored
+  message (a hand-edited log) reads as `null`, and the claim still counts.
+  A stored `reason` outside `permission`, `question`, `attention` reads as
+  `null` too, and a row whose `producer` is neither `kernel` nor a valid
+  producer id is no claim at all.
+- **Idempotent.** The verb reads the producer's live claim first and appends
+  only on a change: a `set` whose reason or message differs from the live
+  positive claim appends (`changed: true`), an identical one does not; a
+  `clear` appends only over a live positive claim. The answer is
+  `{eventsApi, instance, home, producer, changed, waitingOnYou}`, where
+  `waitingOnYou` is that producer's resulting claim (`null` when it holds
+  none). Concurrent writers append whole lines; the latest row decides.
+  Each log is judged on its own, and success means both took the row: a
+  write either log refused is `E_EVENTS_FAILED` naming it, and the next call
+  (a retry) appends again to repair it.
+- **Session boundary.** A claim written before the incarnation's latest
+  kernel `launched`, `restarted` or `stopped` row (in time order; rows of the
+  same millisecond in append order) is not live: it belongs to an ended
+  session and is not listed in `waitingClaims`. A crash
+  while waiting reads `null` on the roster (not running), and the next start
+  writes `launched`, which voids the claim.
+- **Producers.**
+  - `oats.core`: the Claude Code emitter oats.core installs in a Claude
+    instance's `<home>/.claude/settings.json` (`permission` on a permission
+    prompt, `question` on AskUserQuestion or an MCP elicitation, cleared when
+    the session moves on). See [capabilities.md](capabilities.md), "oats.core:
+    needs input".
+  - `agent`: the instance itself, through `oats instance attention`, and
+    only through it: `oats instance waiting --producer agent` is
+    `E_BAD_ARGS`. **Agent claims are cleared only by the agent (`--clear`)
+    or a session boundary**; no hook clears them (a wake broker's paste is
+    also a prompt submit).
+- **Where it shows.** `waitingOnYou` on the events read, on `oats status
+  --json` instance rows (running rows only) and on `oats session inspect
+  --json` (beside `state`, whose enum is unchanged; `null` unless the harness
+  is running). Plain `oats status` prints `! needs input (<reason>):
+  <message>` under a running instance's row while it holds a claim.
+- **Cost.** To compute the field, `oats status` reads the home log of each
+  running row (the workspace log only when the home log is absent), with
+  the same bounded read as the events read: at most the last 4 MiB, so a
+  claim older than the last 4 MiB of a very busy log is not seen. Stopped
+  rows read nothing.
+- **Local only.** Neither verb routes with `--server`: producers run on the
+  instance's own host.
+- Errors: `E_BAD_ARGS`, `E_USAGE` (attention), `E_SESSION_UNKNOWN` (no
+  readable `instance.json`), `E_HOME_MISMATCH`, `E_EVENTS_FAILED` (the write
+  failed; nothing else is affected).
+
 ## Lifecycle: stop and retire
 
 Feature `lifecycle-plans` (and `retire-retention`), `lifecycleApi: 1`. A
@@ -2359,6 +2480,11 @@ selection flags. See [the start workflow](desktop-instance-start.md).
   instance's events as a `launch-warning` row, `data: {message}`. They are
   advisory: the start went ahead. Earlier kernels omit the field; read a
   missing `warnings` as `[]`.
+- A start or restart appends a `launched` event as soon as its session
+  exists (0.40, `phase: "start"` or `"restart"`, `startId`), the session
+  boundary that voids earlier waiting claims ([Waiting on you](#waiting-on-you)).
+  A start whose metadata write failed has it already, so its adoption adds
+  none to a log that holds it and copies it into a log that does not.
 - Restart is one command: the kernel validates the new selection before
   stopping, and owns the stop, lock, launch recovery and metadata. Never
   restart by retiring and spawning.
@@ -2498,6 +2624,25 @@ oats schedule show <id> --json
   [shared row fields](#automations-shared-rows).
   `executionStatus` is `{kind: "legacy" | "invalid", capture: "unknown",
   migrationRequired: true, reason?, intent?}`; only `legacy` runs.
+- **`attempt`** (present while a launch has no recorded result; reconcile
+  resolves it): `{scheduledFor, startedAt, wallClock, error?, exited?,
+  exitStatus?, exitSignal?}`. `error` (0.40.0) is the first run's cause. A
+  `command` or `operation` attempt with `exited: true` (0.40.0) holds no host
+  slot (`running: false`) but still blocks its own job; show it as needing
+  `oats schedule reconcile <id>` (or `--clear`) either way.
+- **Schedule IDs**: local and workspace schedule definition names permit 1–100
+  lowercase letters, digits and dashes; trigger names retain their 40-character
+  limit. Desktop accepts these schedule names for creation, editing and row
+  actions (enable, disable, test, run and reconcile), including qualified IDs.
+  A spawn's derived instance name still has a 64-character limit.
+- **`description`** (0.40.0): the shared row field is the local definition's
+  `description` when it has one, else `null` (a workspace schedule's comes
+  from its file header). It is one line of at most 200 characters with no
+  control characters; show it in place of the argv when present. Like `task`,
+  it is untrusted text: render it as text. Desktop preserves it unchanged
+  through edits to timing and other fields. A kernel before 0.40.0 sends
+  `null` for every local schedule, and drops a `description` given to `oats
+  schedule add` without refusing it.
 - **An unreadable row** (`list` only): `{id, scope, scheduleApi,
   scheduleHistoryApi, unreadable: {code, message}, history: {status:
   "corrupt", stored: null, truncated: false}, recentRuns: []}`. One bad job
@@ -2604,8 +2749,9 @@ Details: [schedules.md](schedules.md#workspace-triggers-and-schedules).
 null}}` (this machine's `host.name` and its `gh` logins, compared with a
 row's `owner`), `snapshot: {takenAt, problems (a count)} | null` (the last
 `oats sync` snapshot), and `scheduler: {installed, active, registered,
-lastTick, maxConcurrent, …}` (nothing runs unless installed, active and
-registered).
+lastTick, maxConcurrent, triggersMaxConcurrent, …}` (nothing runs unless installed, active and
+registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
+`triggersMaxConcurrent` is the separate trigger cap, or `null` for no host cap.
 
 **Every row** carries:
 - `id` (a local schedule keeps its bare id; a workspace item is

package/docs/execution-targets.md

@@ -139,6 +139,10 @@ oats session attach --home /abs/home
   harness, `shell` for a fallback shell,
   `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
   backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
+  Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
+  live claim that the instance needs input from a human, `{since, producer,
+  reason, message}`, or `null`; it is non-null only for a running harness
+  (docs/desktop-cli-api.md, "Waiting on you").
 - **input** submits UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
   NUL) followed by Enter, as a bracketed paste. The text is never run by a
   shell. A fallback shell, a stopped session or a split

package/docs/implementation.md

@@ -16,6 +16,8 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
 - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup` and
   `oats.knowledge-theory` capabilities and the `knowledge-theory-expert` soul,
   released as a package under its own `oats-framework/v<version>` tags.
+  `oats.core` is the one with executables: its spawn and launch hook and the
+  Claude Code waiting emitter (`capabilities/oats-core/bin/`).
 
 The OATS Desktop (`packages/desktop/`) is an Electron app with a bundled,
 dependency-free localhost server; it is released with the kernel but not
@@ -54,6 +56,7 @@ published to npm. Its developer docs are in
 | `instruction-composition.mjs` | the generated `AGENTS.md` |
 | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
 | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
+| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
 | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
 | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
 | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
@@ -61,6 +64,13 @@ published to npm. Its developer docs are in
 | `servers.mjs` | routing commands to a registered server |
 | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
 
+The schedule registry stores explicit concurrency caps, leaving the schedule
+cap absent for its effective default of five. Reads migrate legacy stored one
+to absent once, under `registry.lock`, and record `capsVersion: 2`. Registration
+and cap updates use that same short lock; later explicit one stays explicit.
+`readRegistry()` returns stored choices; scheduling and status apply the default
+without writing it back. The trigger cap is independent and absent means no cap.
+
 The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
 a provider. Provider behaviour lives in capabilities; the kernel supplies
 their contracts ([layers](layers.md)).
@@ -235,6 +245,15 @@ runs the full suite (sharded), `check`, `validate`, `pack:check` and the smoke
 test, and is the gate. Tests use local bare repositories and fakes; none
 contacts GitHub, aweb, Jira or Linear.
 
+Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
+load with only Desktop dependencies installed. Cross-package tests that import
+both the kernel and Desktop belong under root `test/`; install dependencies at
+the root and in `packages/desktop` before running those tests. The schedule
+round-trip case is `node --test test/desktop-schedule-roundtrip.integration.mjs`.
+The root runner includes this file with its existing Desktop dependency group.
+With only root dependencies installed, it omits both Desktop suites and this
+integration case and reports that coverage gap before and after the run.
+
 Tests pin behaviour, so a change that alters behaviour changes its test in the
 same commit. Never weaken an assertion to make a change pass.
 

package/docs/official-catalog.md

@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.5.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.framework` | `oats-framework/v1.6.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.8.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
+| `oats.engineering` | `v1.8.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.1.1` or `oats-framework/v1.5.0`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.6.0`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.5.0
+  oats.framework: v1.6.0
   oats.okf: v4.1.1
   oats.aweb: v1.21.1
 teams:
@@ -333,11 +333,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.5.0", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.0", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.5.0`
-resolves to tag `oats-framework/v1.5.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.6.0`
+resolves to tag `oats-framework/v1.6.0`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

package/docs/release-notes/v0.40.0.md

@@ -0,0 +1,181 @@
+# OATS 0.40.0
+
+## Added
+
+- **"Needs input": an instance can say it is blocked on a human** (feature
+  `waiting-on-you`). The `waitingOnYou` fact that `oats instance events` has
+  carried since 0.24.12 finally has producers. It shows on every running
+  instance row of `oats status --json` and on `oats session inspect --json`
+  as `waitingOnYou: {since, producer, reason, message} | null`, and plain
+  `oats status` prints `! needs input (<reason>): <message>` under the row.
+  Claims are display-only: nothing in the kernel acts on them, and
+  `oats session input` is unchanged. See docs/desktop-cli-api.md, "Waiting
+  on you".
+  - `oats instance waiting <set|clear> --producer <id> [--reason
+    permission|question|attention] [--message <text>]` records a producer's
+    claim as a `waiting` event, appended only when the claim changes.
+  - `oats instance attention [--message "<one line>"] [--clear]` is the
+    agent's own claim, run from its home (`$OATS_INSTANCE_HOME` only). The
+    oats.core instructions now teach it: when an agent has asked a human
+    something and cannot continue without the answer, it runs
+    `oats instance attention --message "…"` and ends its turn, then
+    `--clear` once it has the answer. Only the agent or a session boundary
+    clears an agent claim.
+  - `--message` is one line of 1 to 200 characters. Refused, at write and
+    again at read (a refused stored message reads as `null`): control
+    characters, U+2028/2029, the bidi controls U+202A–202E and
+    U+2066–2069, U+200B, U+2060, U+FEFF and the tag characters
+    U+E0000–E007F. Everything else is allowed, ZWJ/ZWNJ (U+200C/D) and
+    LRM/RLM/ALM (U+200E/F, U+061C) included. The Desktop uses the same set.
+  - A claim is live only after the incarnation's latest kernel `launched`,
+    `restarted` or `stopped` row, so a crashed or restarted session never
+    shows a stale claim. `waitingOnYou` and `waitingClaims[]` entries gain
+    `message` (a string or `null`); the shape is otherwise unchanged.
+
+- **oats.core 2.4.0 (oats.framework 1.6.0) reports Claude Code permission
+  prompts and questions.** For a Claude instance, oats.core manages its own
+  hook entries in `<home>/.claude/settings.json`. A permission prompt sets
+  `waitingOnYou` with reason `permission`; AskUserQuestion or an MCP
+  elicitation sets `question`; the claim clears when the session moves on.
+  The hooks always exit 0, print nothing and time out in seconds, so a failing
+  emitter means "unknown", never a blocked tool. Every other key and entry in
+  that file is left alone. oats.core now requires OATS 0.40.0. See
+  docs/capabilities.md, "oats.core: needs input".
+- **Desktop: the sidebar shows which agents are waiting on you.** When an
+  agent is waiting for a tool approval, a question or an attention request,
+  its row shows a "Needs input" mark next to its name. Hover over the row, or
+  focus it from the keyboard, to see what it is waiting for, its message and
+  how long it has waited. A collapsed parent shows "N below" for waiting agents
+  hidden under it, and an open terminal tab shows the mark as well. The mark
+  appears only while the agent is running and the installed OATS reports
+  `waiting-on-you`. It goes on the next roster refresh after the wait ends.
+- **Schedules take an optional `description`**
+  ([#546](https://github.com/awebai/oats/issues/546)): what a job is for, in
+  words. `oats schedule add|update --file` accepts it as one line of 1 to 200
+  characters with no control characters; anything else is
+  `E_SCHEDULE_INVALID` naming `field: "description"`. It is stored as given
+  and returned by `schedule list --json` and `show --json` in each row's
+  `description` (`null` when there is none), which is how the Desktop reads
+  it. It is informational only and never reaches a run. Jobs without one are
+  unchanged. Earlier kernels drop the key without refusing it. See
+  [schedules](../schedules.md#kinds).
+- **`oats doctor` warns about unresolved schedule attempts**
+  (`schedule-unresolved`, [#545](https://github.com/awebai/oats/issues/545)).
+  This covers each job, in this deployment and in the other deployments this
+  host ticks, whose launch has no recorded result. The warning gives the job,
+  the attempt's scheduledFor and startedAt and its age, whether it holds a
+  host slot, the first error, and the remedy: `oats schedule reconcile <id>`,
+  with `--clear` when a command's effects can't be proven. In `--json` it is
+  a `problems[]` item with `severity: "warning"`; the exit status is
+  unchanged. See [schedules](../schedules.md#what-a-run-reports).
+
+## Changed
+
+- **An unknown command or operation run no longer stalls the host's other
+  jobs** ([#545](https://github.com/awebai/oats/issues/545)). Once the kernel
+  has observed the command's process exit (it returned, or was stopped at the
+  timeout), its unresolved attempt stops counting against `maxConcurrent`.
+  The job itself still waits for `oats schedule reconcile`, so it never runs
+  twice on unproven effects. Its attempt now records `exited`, `exitStatus`
+  and `exitSignal`, and `show` reports `running: false`. Spawn jobs keep
+  their slot, and so does an attempt recorded by an earlier kernel, until
+  reconcile.
+- **An unresolved attempt keeps its first error.** Later due ticks used to
+  replace the cause ("command timed out…", "answered no valid envelope…",
+  "command outcome unconfirmed: …") with "launch attempt without a recorded
+  result" in `lastRun` and its history row. The cause is now kept on the
+  attempt (`attempt.error`) and in `lastRun`.
+- **Schedule IDs may contain up to 100 characters**, locally and in workspace
+  definitions. Trigger IDs remain limited to 40. Spawn schedules still need
+  a short enough `purpose` to fit the 64-character instance-name limit.
+- **Desktop timing edits preserve a schedule's description**, including its
+  exact whitespace and Unicode text. Existing jobs without descriptions
+  remain editable.
+- **oats.engineering 1.8.1** (catalog and workspace pin, and the bundled
+  mirrors): a PR is reviewed only after its owner says the developer's review
+  loop converged. `/pr-review` starts on the owner's hand-over (the loop's
+  final verdict and rounds, the exact head, CI green on it), and a head that
+  moves afterwards waits for the next hand-over, after which only the delta is
+  reviewed and the verdict re-bound; a PR with no owning expert is ready when
+  its author marks it ready or asks for review at a named head.
+  Experts verify only converged branches and hand PRs over with all three
+  facts; developers report convergence, with the head, instead of
+  intermediate heads.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.41.0`**, so it runs against
+  this release's kernel; the Desktop 0.39.x refuses a 0.40 CLI.
+- **`oats session start` and `restart` now record a `launched` event**
+  (`data.phase: "start"` or `"restart"`, `data.startId`), as spawn already
+  did, once per start and in each log: a start recovered from an interrupted
+  one's receipt adds none, copies the same row into a log that missed it, or
+  writes one with `phase: "recovered"` dated at its launch when the
+  interrupted start had written it to neither log. A consumer that counts a home's
+  events sees one more row per start.
+- **oats.framework 1.6.0** (oats.core 2.4.0; catalog and workspace pin
+  `oats-framework/v1.6.0`): the package that carries the "needs input"
+  emitter and the `oats instance attention` protocol above. A workspace's
+  `oats.framework: v1.6.0` resolves to that tag through the official
+  catalog; workspaces pinned to v1.5.0 keep oats.core 2.3.0 until they move
+  the pin and sync.
+- **Desktop: collapsing a row hides only rows in its own deployment
+  section.** A row whose parent name matched an agent in another deployment
+  was hidden when that agent was collapsed. It now stays visible.
+
+## Fixed
+
+- **A scheduled command that ignores SIGTERM can no longer wedge the host
+  scheduler** ([#547](https://github.com/awebai/oats/issues/547)). Command and
+  operation runs, workspace-spawn launches and spawn previews now send SIGTERM
+  at the five-minute timeout, then SIGKILL to the remaining process group after
+  two seconds. The runner observes the direct child's exit and bounds output
+  pipe draining before returning. Timed-out commands remain unknown and wait
+  for reconcile, while their exited processes no longer hold host slots;
+  spawn jobs retain their existing slot semantics.
+
+- **Missing harness-package diagnostics give usable direct install commands.**
+  Spawn and restart preflight no longer suggest the removed `oats install`
+  verb. Guidance names the operator's responsibility, quotes the selected
+  executable and context paths, preserves Pi's resource directory, and keeps
+  Claude marketplace registration before plugin installation. OATS still
+  verifies requirements without installing packages.
+
+## Notes
+
+- **Claude Code honours only the last `--settings` flag.** On Claude Code
+  2.1.288 a second `--settings` replaces the first wholesale, even when it
+  has no hooks. That is why oats.core writes the project
+  `<home>/.claude/settings.json`, which composes with the user's settings and
+  with a `--settings`. Any capability that needs Claude settings must manage
+  its own entries in that file, under its own marker, and never pass
+  `--settings`.
+- **Claude instances spawned before the upgrade get the emitter only on
+  respawn.** A home's launch hook comes from its recorded module copy, so a
+  restart keeps the old oats.core. The `attention` verb works on any harness
+  as soon as the kernel is upgraded.
+- If a user's Claude configuration sets `disableAllHooks` or
+  `allowManagedHooksOnly`, the emitter never runs and the field stays `null`.
+- Refusing a Claude Code permission prompt fires no hook (Claude Code
+  2.1.288), so after a "No" the claim stays, labelled `permission`, until the
+  human's next prompt; Claude is waiting for that prompt anyway.
+- The emitter debounces only the per-tool-call clears; `UserPromptSubmit`,
+  `Stop` and `SessionEnd` are not debounced. A turn-boundary clear gets a
+  CLI call: from that hook, or, if another hook holds the lock, from that
+  holder if it still has time; otherwise from the next event. That bounds
+  what an unfenced kernel write can leave wrong
+  ([#568](https://github.com/awebai/oats/issues/568)): after a hook
+  suspended past 5 s mid-call (the machine slept) or a reaper killed at a
+  precise instant, a wrongly shown claim lasts until the end of the turn,
+  or, if the turn's last hook found a reconciliation out of time, until the
+  next event (the human's next prompt); a hidden question lasts until the
+  human answers it. A permission prompt can also stay hidden until it is
+  answered without any of that: when it opens while another hook's
+  reconciliation runs out of time (a slow clear on a loaded machine).
+  Parallel main-thread tool calls may clear a claim early. See
+  docs/capabilities.md, oats.core: needs input, Limits.
+- Tool calls by background or parallel subagents in the same Claude session
+  do not clear the claim: the emitter skips tool events that carry a
+  subagent's `agent_id`. A permission prompt never says who asked, so after
+  a human approves a subagent's prompt the claim stays until the next
+  main-thread event (its next tool call, the subagent's completion, a stop or
+  a prompt). For a foreground subagent the main thread makes no call until
+  the subagent finishes, so the claim can last the whole subagent run: too
+  long, never hiding a real block.

package/docs/release-notes/v0.40.1.md

@@ -0,0 +1,20 @@
+# OATS 0.40.1
+
+0.40.0 was tagged but never published because its Desktop build failed in the release workflow. 0.40.1 is the first published 0.40 release and includes everything in the [0.40.0 notes](v0.40.0.md).
+
+## Changed
+
+- **Scheduled jobs default to a host concurrency of five.** The registry stores
+  explicit choices only. Legacy stored one migrates to the default once; an
+  explicit `oats schedule host install --max-concurrent 1` after upgrade stays
+  one. Use `--max-concurrent N|default` and the independent
+  `--triggers-max-concurrent N|none` to configure caps through the CLI
+  ([#550](https://github.com/awebai/oats/issues/550)). Host status reports both
+  caps; triggers remain uncapped by the host unless explicitly limited.
+
+## Fixed
+
+- **Desktop tests run with only Desktop dependencies installed.** The schedule
+  description round-trip integration test now lives in the root suite, where
+  kernel dependencies are available. Desktop's standalone release test suite
+  retains its unit coverage without importing the kernel.