@awebai/oats 0.39.4 → 0.40.2

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.
 
@@ -539,7 +543,10 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
   home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
   (undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
   false` is relayed with its code and `details: {exit, envelope,
-  unconfirmed?}`. `E_OPERATION_TIMEOUT` (240 s) and `E_OPERATION_RESULT` are
+  unconfirmed?}`. A literal provider `error.details.unconfirmed: true` is
+  promoted to the outer details while its full envelope stays nested. Existing
+  retained-effect text checks remain for compatibility during migration.
+  `E_OPERATION_TIMEOUT` (240 s) and `E_OPERATION_RESULT` are
   unconfirmed outcomes: `details: {exit, signal, unconfirmed: true,
   envelope?, stderr?, cleanup?}`.
 
@@ -1613,7 +1620,7 @@ with `--expect-decision` records the key and decision in `instance.json`.
   `E_IDEMPOTENCY_CONFLICT {instance, home}`.
 - `spawnCompleted` is `false` until launch, lineage and events are done; a
   retry of an unfinished spawn is `E_SPAWN_INCOMPLETE {instance, home,
-  launched}` (recover through the session surface).
+  launched, unconfirmed: true}` (recover through the session surface).
 - The key lives in the home. Mint it on the first confirmation and keep it
   for that intent's retries.
 - `wake: {requested, saved, error}` is recorded and replayed; `saved: null`
@@ -1682,11 +1689,17 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN` | see above | |
 | `E_DECISION_STALE` | `{decision}` | |
 | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
-| `E_SPAWN_INCOMPLETE` | `{instance, home, launched}` | |
+| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}` | |
 | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
 | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
 | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
-| `E_SPAWN_FAILED` | | anything else |
+| `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
+
+Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
+keyed spawn is incomplete (`E_SPAWN_INCOMPLETE`) or compensation cannot confirm
+cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
+Confirmed completed compensation does not set this marker. This is an additive
+producer migration; existing text-based compatibility checks remain.
 
 ## `instance.json` and the roster
 
@@ -1787,6 +1800,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
@@ -1908,6 +1931,15 @@ route target:
   `relativeTo` and `spawnOrigin` are always present, `null` when the host
   does not supply them (a host before 0.31, a fact it never recorded, or a
   saved route the host no longer lists). Nothing is derived on this side.
+- **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
+  only when the host's kernel reports it: a row from a host before 0.40.0,
+  and a saved route the host did not list, have no such key. Absent means
+  "not reported", which is not `null` ("no claim"). When present it is `null`
+  or `{since, producer, reason, message}`, passed through the kernel's read
+  rule again on this side: a value that is not a claim (no valid `since` or
+  `producer`) is `null`, and an unknown `reason` or an invalid `message` is
+  `null` inside a claim that still counts. As on a local row, the host
+  reports a claim only for a running instance.
 - **`addressable`** (0.31): `true` for every row the host reports. Routed
   session and lifecycle commands reach it by `--home`, or by name when the
   name is unique on the host ([addressing](servers.md#run-there); a shared
@@ -2146,34 +2178,169 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
 
 - **Sources.** `home` is `<home>/.oats-events.jsonl`; `workspace` is
   `<deployment>/.agents/events/<agent>--<instance>.jsonl` (it survives the
-  home). Each is `{path, status: "ok" | "absent" | "refused" | "tail",
+  home). The deployment is the one the home's spawn recorded, when that
+  directory really holds the home at `agents/<agent>/instances/<instance>`;
+  otherwise it is the fourth ancestor of the home as it was addressed. Each is `{path, status: "ok" | "absent" | "refused" | "tail",
   bytes}`. Only a regular file is opened (no symlinks, same device and inode
   after open), and at most its last 4 MiB is read (`"tail"`).
 - **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
   `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`).
+  A home has one address in storage, its real path (since 0.40.2): rows are
+  written and matched under it, whatever spelling a writer or reader used (a
+  deployment reached through a symlink, a symlinked agents root). The answer
+  keeps the spelling it was asked in: the top-level `home` and every
+  returned row's `home` are the home as the caller addressed it (`--home`,
+  or the home found under `--dir`), the same string a status row carries.
   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.
+- **Rows from before 0.40.2**, in a deployment addressed through a symlink
+  only. A stored `home` is never rewritten, and never matched under another
+  spelling. A row an earlier kernel wrote under the lexical spelling (a
+  spawn's rows, and the claims of a session that was spawned and never
+  restarted) is foreign after the upgrade, and counted in
+  `integrity.foreignRows`. What that means for a claim:
+  - A claim that was live under the lexical spelling stops showing. Nothing
+    brings that row back: the claim shows again only when a producer makes it
+    anew (the next permission prompt or question, the agent's next
+    `oats instance attention`). A restart starts a new session with no
+    claim, as always.
+  - A claim that stayed set because the restart that should have voided it
+    was recorded under the real path (#583) is gone.
+  - The rows a started or restarted session wrote under the real path, which
+    `oats status --dir <symlink>` could not see, are read now. They cannot
+    surface a stale claim: such a session wrote its clears and its session
+    boundaries under the real path too, so that history is complete.
 - **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, or whose `at` is not a date, 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) and `home` is the home as the caller addressed it (`--home`,
+  `$OATS_INSTANCE_HOME` or the enclosing home); the row is stored under the
+  real path, so a set and a clear through different spellings of one home
+  meet. 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
@@ -2340,6 +2507,42 @@ stderr, not envelopes.
 
 ## Sessions and launch configurations
 
+### Input
+
+```text
+oats session input --home <abs> [--text-file <path>] --json
+```
+
+Input bytes come from stdin or the named file. The existing version-1 success
+answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
+present: true, state, paneId, submitted: true, verified}}`. Session input runs
+on the execution host, including when the wake broker invokes it there;
+`--server` is not supported for input. The adapter sends one literal
+bracketed paste and one Enter after the existing input/authority/target checks.
+
+`submitted` means terminal-operation success, **not model acceptance or
+processing**. `verified` is display observation only: `true` means a bounded
+look changed, possibly because of unrelated output or a dialog; `false` means
+unchanged, unreadable or exhausted observation. False never authorizes retry
+and is not proof of a pending draft or absence of effects. No `reason` is
+emitted; the `enter-not-taken` result from 0.39.4 is removed.
+
+Read-only settling before Enter shares one monotonic 2-second budget starting
+when paste returns; up to two post-Enter looks share a 1-second budget. Probe
+timeouts and sleeps use the remaining budget. Observation failures produce
+`verified: false`, not input errors or extra keys. The original paste/key
+command timeouts and `E_SESSION_INPUT_FAILED` errors remain; the observation
+budgets do not bound those commands, failed buffer cleanup or OS scheduling.
+No busy-pane submission or exactly-once guarantee is provided. Generic command
+errors can still be uncertain after partial effects.
+
+The Desktop terminal's authorized PTY writes are a separate stream; they do not
+consume this `verified` field. The Pi bridge does not interpret this result.
+Scheduler wake still records a nonthrowing input operation as delivered without
+adding acceptance/history fields. Actual broker acknowledgement and retry
+policy require their own consumer qualification; this result is not a native
+harness receipt. See [execution targets](execution-targets.md).
+
 ### Start and restart
 
 ```text
@@ -2359,6 +2562,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 +2706,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 +2831,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,35 +139,40 @@ 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.
-- **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
-  tmux window is refused. The text is pasted once. Enter waits for the pane to
-  settle (two identical captures, at least about 200 ms, longer for a larger
-  paste, at most 2 s), and is judged by whether it changed the bottom 15 lines
-  of the pane. The comparison is of bytes only, and the pane's text is never
-  interpreted. Trailing spaces are ignored. When the pane was seen to change
-  size (a resize, or a second client attaching), a reflow of the same content
-  is not a change either: each side's content must already be on the other
-  side's screen or in its history, so content that appeared or disappeared
-  still counts. An Enter that changed nothing was swallowed, and is resent
-  after a backoff, at most 3 Enters in total. The answer adds:
-  - `submitted: true, verified: true`: an Enter was taken.
-  - `submitted: false, verified: true, reason: "enter-not-taken"`: none of the
-    3 Enters changed the pane. The text stays in the agent's input box; it is
-    not pasted again.
-  - `submitted: true, verified: false`: a capture failed, so no further Enter
-    was sent and the last one was not judged. As before, this means the
-    terminal accepted the keys. When the pane cannot be read before the first
-    resend, exactly one Enter was sent.
-
-  `submitted` never means the agent processed the text. A pane that changes
-  for another reason after Enter (a spinner, a clock, a human typing) reads as
-  taken. A harness that shows no visible reaction to Enter receives up to two
-  extra Enters; real harnesses (claude, codex, pi) redraw on submit. A call takes at most about 4 s plus its tmux calls. A failed paste or
-  key send is `E_SESSION_INPUT_FAILED`, with no retry. Wake schedules and
-  messaging capabilities use this command ([schedules.md](schedules.md)); a
-  wake schedule records any answer as delivered.
+  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** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
+  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
+  is never run by a shell. Existing endpoint authority, fallback-shell,
+  stopped-session and split-window checks still refuse before input.
+
+  Before Enter, a size-based floor (200 ms plus 3 ms per KiB) and read-only
+  settling polls share one **monotonic 2-second observation budget**, starting
+  immediately after the paste command returns, before buffer cleanup. Sleeps
+  and capture timeouts are clipped to the remaining budget; a failed capture
+  or exhausted budget ends settling and proceeds to the single Enter. After
+  Enter, at most two read-only looks share a separate 1-second observation
+  budget. These deadlines do not bound the original paste/key commands, buffer
+  cleanup or OS scheduling. They authorize no further keys.
+
+  Successful terminal commands return `submitted: true` and `verified`, with
+  no `reason`. `verified: true` means only that the bounded display comparison
+  saw a changed look; `false` means unchanged, unreadable or exhausted
+  observation. The comparison retains its whitespace and resize/reflow
+  handling. Display movement can be unrelated output, a spinner or a dialog;
+  an unchanged display is not proof that no effects occurred or that a draft
+  is pending. **Neither value authorizes retry or proves model acceptance.**
+
+  A failed paste or key command remains `E_SESSION_INPUT_FAILED`; an
+  observational failure does not turn successful terminal operations into a
+  refusal. Command errors may themselves be uncertain after partial effects.
+  This transport offers no exactly-once guarantee and does not guarantee that
+  a busy pane accepts the input. Wake schedules retain their existing rule:
+  any nonthrowing input answer is recorded as delivered, meaning terminal
+  operations, not model processing. Broker delivery/ack policy and harness
+  acceptance evidence remain separate contracts.
 - **attach** is interactive and takes no `--json`. It opens a temporary tmux
   session linked to the agent's window alone.
   Closing the viewer leaves the agent running.

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,56 @@ 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. `readRegistry()` is a pure,
+bounded atomic-file snapshot: it takes no lock and writes nothing, projecting
+legacy implicit one to absent and `capsVersion: 2` only in memory. Its no-follow
+regular-file descriptor accepts an atomic rename between stat and open, so it
+returns a complete old or new snapshot; other bounded readers retain their
+identity check. Invalid present schedule or trigger caps are refused.
+Registration, unregistration and cap updates reread under `registry.lock` and
+compare against the raw snapshot, so even unchanged membership persists the
+migration. A successful write removing legacy one emits a stderr notice naming
+the one-slot restoration command. `writeRegistry()` remains a raw atomic writer;
+read-modify-write callers must supply the lock and reread. Later explicit one
+stays explicit, including one reintroduced by an older writer: the stored
+marker cannot distinguish its provenance. The trigger cap stays independent.
+
+The shared mkdir lock retries every occupied-directory window within the
+caller's retry deadline, including owner-file publication and removal. It never
+removes a contender's lock or steals from a live, dead or unreadable owner;
+persistent contention ends in the caller's existing busy error.
+
+Spawn compensation returns its diagnostic and a structural uncertainty flag;
+only an incomplete result marks the original error's `details.unconfirmed`.
+CLI wrappers preserve that field, and the operation runner promotes a provider's
+literal true marker while retaining the nested envelope. Message-based consumers
+remain during the additive producer migration; do not replace stage evidence
+with a substring check or infer uncertainty from a retained home alone.
+
+The schedule child supervisor installs SIGINT/SIGTERM/SIGHUP handlers before
+launch and removes them on settlement. All catchable shutdown signals share
+its idempotent TERM/KILL path; the first stop cause is retained. The private
+receipt records interruption independently of both the first stop cause and
+the direct child's observed exit, so a signal during overflow cleanup still
+keeps an otherwise valid envelope unconfirmed. Group probes
+start at leader exit; an observed-empty group is permanently excluded from
+later probes/signals. Polling cannot eliminate the gap before observation or
+prove away PID reuse. Escaped sessions are outside the owned group, and
+SIGKILL/OOM or unrecoverable supervisor death cannot be cleaned up by handlers;
+a missing receipt supplies no child-exit evidence and cannot release a slot.
+
+Session input keeps terminal operations separate from display observation.
+The pre-Enter budget starts at paste completion, before best-effort buffer
+cleanup; post-Enter observation starts after the single key command returns.
+Both use a monotonic clock, clip sleeps and read-only capture subprocess
+budgets, and stop observing on failure or exhaustion. Capture subprocesses use
+SIGKILL on timeout so an ignored TERM cannot extend a probe; terminal command
+timeouts/errors are unchanged. Screen comparison can set only the observational
+`verified` boolean, never send another key or report terminal failure. Tests
+use inert command runners and clocks; they do not qualify broker delivery or
+harness acceptance.
+
 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 +288,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/oats-local.schema.json

@@ -99,7 +99,7 @@
         "disabled": {
           "description": "Workspace schedules this host does not run, by qualified id <member>/<id>, without a commit (`oats schedule disable <member>/<id>` writes it). Local schedules are enabled and disabled in oats-schedules.json.",
           "type": "array", "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" }
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" }
         }
       }
     },
@@ -111,7 +111,7 @@
           "description": "The workspace triggers and schedules this host agrees to run, by qualified id <member>/<id>, or \"*\" for every one the workspace places on this host (0.30). A workspace automation runs only when its runsOn is host.name, its owner is this host's gh account AND trust admits it; absent or empty, none runs. A host fact: the committed workspace file refuses it. Local triggers and schedules need no trust.",
           "oneOf": [
             { "const": "*" },
-            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" } }
+            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" } }
           ]
         }
       }

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.1` (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.1`) 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.1
   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.1", "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.1`
+resolves to tag `oats-framework/v1.6.1`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.