@awebai/oats 0.39.4 → 0.40.2

package/docs/release-lane.md

@@ -47,8 +47,8 @@ override; report the risk you accepted). It never touches the checkout it
 runs from: it exports the SHA into a detached worktree under the system
 temporary directory (recorded in `MANIFEST.json`, `--export <dir>` overrides)
 and runs every build step there. The bumped manifests exist only in that
-export; the version-bump commit to `main` remains the workflow's job, or a
-manual PR.
+export; the version-bump commit reaches `main` through the pull request the
+workflow opens (or a manual one), merged by a maintainer.
 
 `publish-npm` and `release-github` print their plan and refuse without
 `--yes`. `tag` creates the local tag without `--yes` but pushes only with
@@ -117,8 +117,12 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
   runs `release.yml`, whose steps are idempotent: it skips the live npm
   versions, re-uploads the same assets, and attaches the attestations. That
   later pass is the way to add provenance; nothing is republished.
-- **The version-bump PR.** The workflow's final step; open it by hand if the
-  workflow does not run.
+- **The version-bump PR.** The workflow's final step opens it and stops: the
+  run never merges into `main`. A maintainer reviews that the diff is the
+  version lines only and merges it. The PR is opened with the workflow token,
+  so no checks run on it by themselves; close and reopen it to run them, and
+  do not read missing checks as green. Open the PR by hand if the workflow
+  does not run.
 - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
   host; the lane says so and `stage` lists what is missing.
 

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.

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

@@ -0,0 +1,120 @@
+# OATS 0.40.2
+
+## Added
+
+- **Unconfirmed spawn and operation failures carry structural evidence**
+  ([#548](https://github.com/awebai/oats/issues/548)). Incomplete keyed spawns
+  and failed spawn compensation set `error.details.unconfirmed: true`; the
+  operation wrapper promotes a provider's literal true marker while retaining
+  its complete envelope. Completed compensation stays unmarked. Existing
+  text fallbacks and scheduler slot/reconcile behavior remain during this
+  additive migration; older copied providers are not upgraded by this change.
+
+## Fixed
+
+- **Schedule registry reads are lock-free and do not mutate state**
+  ([#579](https://github.com/awebai/oats/issues/579)). Status and other readers
+  use coherent atomic-file snapshots, including during registry writes. Legacy
+  cap migration is projected in memory and persisted only by locked mutations,
+  with a one-slot restoration notice on stderr. Invalid stored schedule caps
+  now refuse instead of silently increasing capacity; explicit CLI cap options
+  can repair them. Old hand-set and implicit ones cannot be distinguished, nor
+  can current kernels identify a one reintroduced by an older writer sharing
+  the registry; stop mixed-version writes and explicitly set the desired cap.
+  Shared directory locks wait through transient owner publication/removal within
+  their retry deadline without stealing locks.
+- **OATS Desktop: "Needs input" shows on a remote instance, and a withheld
+  note reads as the reason.** Desktop hid every remote claim: a remote roster
+  row carries no `runtimeState`, and Desktop read "not reported" as "not
+  running" (#582). An unreported state no longer hides the claim; a row
+  reported stopped, unreachable or unsupported, or one whose server did not
+  answer, still shows none. When a claim's note holds a link or text such as
+  `token: …`, Desktop does not show it. The row's description, the terminal
+  tab's title and the hover card now show the reason in words, such as "Asked
+  you a question", where they showed "[Detail withheld]" (#584). The activity
+  view still marks such a note as withheld, and `oats status` prints it in
+  full.
+- **A remote instance's "needs input" reaches the roster**
+  ([#582](https://github.com/awebai/oats/issues/582)). `oats server roster`
+  built a remote row from a fixed list of facts and dropped the host's
+  `waitingOnYou`. A row now carries it when, and 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, so "not reported" stays distinct from `null`
+  ("no claim"). The value passes the kernel's read rule again on this side;
+  anything that is not a claim is `null`. See
+  [the remote roster](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json).
+- **"Needs input" in a deployment addressed through a symlink**
+  ([#583](https://github.com/awebai/oats/issues/583)). A home there has two
+  spellings: `oats status --dir <symlink>` addressed it lexically, while a
+  started or restarted session carries the real path. Event rows are keyed by
+  the home, so the session's claims never showed on status, a restart did not
+  void a claim written under the other spelling, and a clear through one
+  spelling found nothing. Rows are now stored and matched under the home's
+  real path, whichever spelling a writer or reader uses, and both spellings
+  use one workspace log, the deployment's own `.agents/events`. Answers keep
+  the spelling they were asked in: the `home` in `oats instance events --json`
+  (the top-level field and each row's) and in the `oats instance waiting` and
+  `oats instance attention` answers is the home as the caller addressed it.
+  Deployments not reached through a symlink see no change.
+
+  Rows an earlier kernel wrote under the lexical spelling are not rewritten
+  and not matched: after the upgrade they are foreign, counted in
+  `integrity.foreignRows`. In a symlinked deployment that means:
+  - a claim that was live under the lexical spelling (a session that was
+    spawned and never restarted) stops showing. It shows again only when it
+    is made anew: at the agent's next permission prompt, question or
+    `oats instance attention`. A restart starts a new session with no claim;
+  - a claim that stayed set because its restart was recorded under the real
+    path is gone, not stuck;
+  - the rows a started or restarted session wrote under the real path are
+    read now. They cannot show a stale claim: such a session wrote its clears
+    and its session boundaries under the real path too.
+- **oats.core 2.4.1: the Claude Code emitter no longer speaks for another
+  instance** ([#584](https://github.com/awebai/oats/issues/584)). Its hook
+  script took the home from `$OATS_INSTANCE_HOME`. A Claude process that
+  loaded one home's `.claude/settings.json` while carrying another instance's
+  environment (a nested `claude -p`, a `claude -p` started with its working
+  directory in another home, a pane that inherited the variables) set and
+  cleared that other instance's claim, and its `Stop` and `SessionEnd` clears
+  could erase a real one. The launch hook now writes the home's real path
+  into each hook command, and the script acts only when `$OATS_INSTANCE_HOME`
+  names that home, through any spelling; otherwise it does nothing. Ships in
+  oats.framework 1.6.1 (compatibility unchanged; catalog and workspace pin
+  `oats-framework/v1.6.1`): a workspace's `oats.framework: v1.6.1` resolves
+  to that tag through the official catalog, and a workspace pinned to v1.6.0
+  keeps oats.core 2.4.0 until it moves the pin and syncs. A home picks it up
+  at its next spawn. See [capabilities](../capabilities.md).
+- **A waiting row whose time is not a date is no claim**
+  ([#584](https://github.com/awebai/oats/issues/584)). The reader validated a
+  stored claim's producer, reason and message but passed its time through.
+  And `oats help` lists `[--dir <d>]` for `oats instance waiting`.
+- **Catchable scheduler-supervisor shutdown cleans up its owned child group**
+  ([#580](https://github.com/awebai/oats/issues/580)). SIGINT, SIGTERM and SIGHUP
+  enter the existing bounded TERM/KILL cleanup once, preserving observed child
+  exit evidence and treating interrupted envelopes as unconfirmed. The group
+  is checked when its leader exits and never signalled again after it is seen
+  empty, reducing but not eliminating process-group ID reuse races. Escaped
+  sessions and unrecoverable supervisor deaths such as SIGKILL/OOM remain
+  outside that cleanup guarantee; no receipt means no proven child exit, so
+  the unknown attempt and host slot remain pending reconciliation.
+- **Workspace schedule opt-outs and named trust accept 100-character IDs**
+  ([#581](https://github.com/awebai/oats/issues/581)). Host configuration now
+  accepts the full schedule name limit in `schedules.disabled` and
+  `automations.trust`, so enabling/disabling and trusting schedules with
+  41–100-character IDs works through the CLI and workspace placement checks.
+  Trigger definitions and `triggers.disabled` retain their 40-character limit;
+  member syntax, allowed characters and uniqueness rules are unchanged.
+
+## Changed
+
+- **Session input restores single-paste, single-Enter terminal semantics**
+  ([#562](https://github.com/awebai/oats/issues/562)). Corrects 0.39.4's
+  screen-derived extra Enters and `enter-not-taken` refusal after successful
+  terminal commands. Pre-Enter settling remains, with a shared monotonic
+  2-second observation budget; at most two read-only post-Enter looks share
+  1 second. Each probe and sleep is limited by its remaining budget.
+  `submitted: true` reports terminal-operation success; `verified` reports
+  display change only, and false never authorizes retry. Neither proves model
+  acceptance, pending draft state or absence of effects. Command errors and
+  authority checks are unchanged; busy-pane submission, exactly-once delivery
+  and generic-error retry uncertainty are not solved by this correction.

package/docs/schedules.md

@@ -38,7 +38,7 @@ The design is in the
 | `<deployment>/oats-schedules.json` | This machine's local definitions, `{version: 1, jobs: {<id>: …}}`, local triggers included (`kind: "trigger"`). |
 | `<deployment>/.agents/automations/snapshot.json` | The workspace definitions discovered from the members. |
 | `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one lock directory per running job. |
-| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (default 1: running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
+| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
 
 One host lock serializes ticks, run-now, reconcile and remove. It is never
 reclaimed by another process: a lock whose owner is gone is reported with the
@@ -48,7 +48,18 @@ directory to remove.
 
 Every definition carries `id`, `enabled`, `cron`, `tz` and `kind`. `cron` has
 five fields (minute hour day month weekday) and `tz` is a required IANA zone;
-both are evaluated by the croner library.
+both are evaluated by the croner library. Schedule IDs use lowercase letters,
+digits and dashes, from 1 to 100 characters. Spawn schedules with a long ID
+need an explicit shorter `purpose` to fit the instance-name limit below.
+
+Any kind may carry `description`: what the job is for, in words, for the
+people reading `oats schedule list`, `show` and the Desktop. It is one line of
+1 to 200 characters with no control characters (no CR, LF, TAB or any other
+C0 or C1 character, nor a Unicode line or paragraph separator); anything else
+is `E_SCHEDULE_INVALID` with `field: "description"`. It is stored as given and
+is informational only: it never reaches a run's argv, environment, task or
+reconcile. A capability that registers jobs (knowledge harvest's `run-source`
+jobs) sets it so that its command jobs can be told apart.
 
 - **spawn** `{…, agent, agentsRoot?, repo?, backend?, purpose?, task,
   launchConfig?, harness?, model?, yolo?, wake?}` — every due minute launches
@@ -70,7 +81,24 @@ both are evaluated by the croner library.
   no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
   inside the deployment. The runner tracks any instance the command's
   envelope names, including an independent worker it reports, until its home
-  is gone. A command's return is not task completion.
+  is gone. A command's return is not task completion. Command/operation runs and
+  workspace-spawn launches have a five-minute child timeout. The supervisor
+  sends SIGTERM to the child's process group, allows two seconds for cleanup,
+  then sends SIGKILL if the group remains. It observes the direct child's exit
+  before returning; inherited output pipes cannot hold the tick indefinitely.
+  SIGINT, SIGTERM or SIGHUP received by the supervisor enters that same cleanup
+  once; repeated signals do not bypass it. A timeout or interrupted supervisor
+  leaves effects unconfirmed even if the child printed an envelope. Spawn
+  previews use the same bounded runner.
+
+  Cleanup covers the owned process group. A descendant that creates its own
+  session can escape it; inherited pipes are bounded but that escaped process
+  is not terminated by this group cleanup. The supervisor checks the group when
+  the leader exits and never signals it after observing it empty. This reduces
+  the group-ID reuse window; it does not eliminate PID reuse races. SIGKILL,
+  OOM and other unrecoverable supervisor deaths cannot run JavaScript handlers:
+  cleanup is not guaranteed then. Without a private supervisor receipt, the
+  scheduler keeps the unknown attempt and its slot until reconciliation.
 - **wake** `{…, home, message}` — every due minute inspects the instance at
   `home`. Running: `message` is delivered once as terminal input (bracketed
   paste plus Enter), never an interrupt. Not running: the home is started with
@@ -220,7 +248,8 @@ owner: github.com/ana
   is an `E_AUTOMATION_SCHEMA` problem, never silently skipped.
 - **The id** is `id:`, else the filename stem. The same id twice in one member
   for one kind is `E_AUTOMATION_DUPLICATE`, naming both paths; the second file
-  is not listed. A trigger and a schedule may share an id. A member named
+  is not listed. Schedule IDs allow 1 to 100 lowercase letters, digits and dashes; trigger
+  IDs allow 1 to 40. A trigger and a schedule may share an id. A member named
   `local` is refused, because `local/<id>` names this host's own definitions.
 - **A workspace schedule is `run: spawn` or `run: command`.** A command's
   `cwd` is relative to the deployment and must stay inside it. `wake` and
@@ -255,9 +284,12 @@ add` / `oats schedule add` definitions need no trust.
 
 **Opting out on one host.** `oats trigger disable <member>/<id>` writes
 `triggers.disabled`, and `oats schedule disable <member>/<id>` writes
-`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. A
-workspace definition is never edited or removed from the CLI (`update` and
-`remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
+`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. The
+schedule part of a qualified ID accepts up to 100 characters in both
+`schedules.disabled` and named `automations.trust` entries. Trigger definitions
+and `triggers.disabled` keep their 40-character limit; the shared trust list
+does not widen trigger IDs. A workspace definition is never edited or removed
+from the CLI (`update` and `remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
 
 **Refresh.**
 
@@ -288,6 +320,8 @@ oats schedule test <id>           # dry run: where it runs, whether its soul res
 oats schedule tick [--dry-run]    # evaluate this deployment now; --dry-run launches nothing
 oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
 oats schedule host install        # register this deployment and install the one host timer (idempotent)
+oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
+oats schedule host install --max-concurrent default --triggers-max-concurrent none
 oats schedule host status | uninstall
 oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
 ```
@@ -295,7 +329,41 @@ oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --w
 `<id>` is `local/<id>` (or the bare id) or `<member>/<id>`. `host uninstall`
 unregisters the deployment and removes the timer once none is registered.
 Every `oats schedule` subcommand takes `--server <id>` instead of `--dir` to
-run on that registered server.
+run on that registered server. Setting or resetting host caps remotely requires
+the destination to advertise both `schedule` and `schedule-host-caps`; an older
+or unknown peer is refused with `E_REMOTE_INCOMPATIBLE` before host install is
+forwarded. Upgrade OATS on the destination to use these options. A remote
+install without cap options retains its existing behavior.
+
+The host allows five running scheduled jobs by default. Use `host install
+--max-concurrent N` to choose a positive integer, or `--max-concurrent default`
+to restore the default. `--triggers-max-concurrent N` independently limits live
+trigger-spawned instances; `none` removes that cap. Omitted flags preserve the
+current choices. Invalid values fail with `E_BAD_ARGS` before registration or
+timer changes. `host status` reports the effective `maxConcurrent` and
+`triggersMaxConcurrent` (`null` when uncapped).
+
+The registry stores explicit choices only. Reading status or the registry takes
+no registry lock and creates or rewrites no files or directories. A reader
+interprets a pre-migration stored `maxConcurrent: 1` as the default of five in
+memory. Registration, unregistration and cap updates persist that migration
+once, under the registry lock, even if the workspace membership is unchanged.
+Other explicit values and the independent trigger cap survive.
+
+A pre-migration hand-set one is indistinguishable from the old implicit one;
+both follow that compatibility choice. When a write migrates one to the default,
+it prints a notice on stderr with `oats schedule host install --max-concurrent 1`
+to restore one if needed. Pure reads stay silent and JSON stdout is unchanged.
+A later explicit one survives writes by current kernels. Older binaries sharing
+the registry can write one back while preserving `capsVersion: 2`; there is no
+provenance to distinguish that from a new explicit one. Stop mixed-version
+writes and explicitly set the desired cap with the supported CLI.
+
+A present invalid `maxConcurrent` is `E_SCHEDULE_INVALID`, not a fallback to
+five. Correct it with `oats schedule host install --max-concurrent N` (or
+`--max-concurrent default`) from the deployment, or with `--dir <deployment>`.
+An absent value still means five. Set caps through the CLI; do not edit the
+registry by hand.
 
 `oats schedule list --json` answers:
 
@@ -306,14 +374,14 @@ run on that registered server.
   schedules: [ <row> ],
   triggers: { count, command: "oats trigger list" },
   snapshot: { takenAt, problems } | null,
-  scheduler: { installed, active, unit?, lastTick, maxConcurrent, tickIntervalSec,
+  scheduler: { installed, active, unit?, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
                workspace, registered, workspaces, live } }
 ```
 
 Each row is the stored definition plus `id` (bare for a local schedule,
-`<member>/<id>` for a workspace one), `qualifiedId`, `origin`, `owner`,
-`runsOn`, `runsHere`, `reason`, `enabledHere`, `soul`, `nextDue`, `lastRun`,
-`recentRuns` and `running`; an unreadable row carries `unreadable: { code,
+`<member>/<id>` for a workspace one), `qualifiedId`, `description` (`null`
+when there is none), `origin`, `owner`, `runsOn`, `runsHere`, `reason`,
+`enabledHere`, `soul`, `nextDue`, `lastRun`, `recentRuns` and `running`; an unreadable row carries `unreadable: { code,
 message }` instead of failing the list. `scheduler.active` is what the OS
 reports about the timer. `oats trigger list --json` carries the same
 `scheduler`. The field-level contract is in
@@ -328,12 +396,42 @@ you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
 `skipped`. The kernel never claims a task succeeded.
 
 `unknown` means the launch's side effects are unconfirmed: a command timed out
-or answered no envelope, or an attempt was never recorded. The job keeps its
-slot and is skipped until `oats schedule reconcile <id>`, which adopts only an
-attributable receipt (a spawn job's instance, named for its minute, or the
-instance a command's answer named). When nothing is attributable, check the
-roster and the host by hand, then `reconcile <id> --clear` records
-`launch-failed` and frees the slot.
+or answered no envelope, or an attempt was never recorded. The job is skipped
+until `oats schedule reconcile <id>`, which adopts only an attributable
+receipt (a spawn job's instance, named for its minute, or the instance a
+command's answer named). When nothing is attributable, check the roster and
+the host by hand, then `reconcile <id> --clear` records `launch-failed` and
+frees the slot. The unresolved attempt shows in `show` as `attempt:
+{scheduledFor, startedAt, error?, exited?, exitStatus?, exitSignal?}`;
+`error` is the first run's cause, which later skipped ticks keep in `lastRun`.
+
+`oats doctor` warns about each unresolved attempt, in this deployment and in
+the other deployments this host ticks (they share its slots). The text form
+is `! schedule-unresolved: …`; in `--json` it is a `problems[]` item:
+
+```text
+{ code: "schedule-unresolved", severity: "warning", scope, id, kind,
+  scheduledFor, startedAt, ageSeconds, holdsSlot, exited, error, remedy, message }
+```
+
+`holdsSlot` says whether the job counts against `maxConcurrent`. `remedy` is
+`oats schedule reconcile <id>`, with `--clear` for a command or operation
+whose effects no named home proves (check the roster and the host by hand
+first), and with `--dir <scope>` for another deployment. A warning never
+changes doctor's exit status. Workspace command kinds come from the last
+saved automations snapshot, without a refresh or an account lookup. Unresolved
+workspace state is reported even if its definition is no longer available.
+
+Whether an `unknown` job keeps its host slot depends on what is still running:
+
+- A `command` or `operation` job whose process exit the kernel observed (it
+  returned, or was stopped at the five-minute timeout) holds no slot: the
+  process runs nothing any more, and an instance it spawned has its own
+  lifecycle. Its attempt shows `exited: true` with the exit status or
+  signal, and other jobs keep running.
+- A `spawn` job keeps its slot, which stands for the instance it may have
+  launched. So does a command whose exit was not observed (the runner threw,
+  the process never started) and a legacy attempt without exit evidence (no `exited`), until reconcile.
 
 **Slots.** A wake job that starts a stopped home holds a launch slot until the
 harness is proven stopped or the home is gone; delivering to a running home
@@ -344,7 +442,7 @@ continues.
 
 **Changing a job.** `disable` never stops anything. `update` never touches a
 running instance, and while a job holds a slot or has an unresolved attempt
-only `cron`, `tz` and `enabled` can change. `remove` refuses while the job's
+only `cron`, `tz`, `enabled` and `description` can change. `remove` refuses while the job's
 instance is tracked or its effects are unresolved (`--force` forgets the job
 without stopping anything). Retiring an instance removes the wake jobs bound
 to its home.

package/docs/servers.md

@@ -298,7 +298,9 @@ the host's own facts from its `status --json`: `identity`,
 `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
 `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
 `relativeTo` and `spawnOrigin`. A fact the host does not supply is `null`
-(an older host, or a saved route the host no longer lists). A removed or edited registration keeps
+(an older host, or a saved route the host no longer lists). A row also
+carries `waitingOnYou` (needs input) when the host's kernel reports it, and
+only then: an older host's row has no such key. A removed or edited registration keeps
 its group from the saved routes. State is pulled on every call within
 `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
 not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.

package/docs/workspaces.md

@@ -54,7 +54,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.5.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.6.1                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 

package/lib/automations.mjs

@@ -45,6 +45,8 @@ export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewh
 export const KIND_NAMES = Object.freeze(["trigger", "schedule"]);
 const NEVER_SCANNED = new Set(["oats-package", ".git", "node_modules"]);
 export const AUTOMATION_ID_RE = /^[a-z0-9-]{1,40}$/;
+/** Schedule definition names have a wider bound than trigger names. */
+export const SCHEDULE_NAME_RE = /^[a-z0-9-]{1,100}$/;
 /** A model id an automation may pass to `oats spawn --model`: a provider/model id, never an option.
  *  The first character is alphanumeric (or the spawn CLI's own `@native-default`), so no value can
  *  be read as a flag (re-review B #1). `[` `]` admit a harness's context-size alias (`opus[1m]`). */
@@ -106,7 +108,8 @@ export function parseAutomationFile(desc, { stem, path, bytes, member, repoKey,
   const unknown = Object.keys(doc).filter((k) => !allowed.includes(k));
   if (unknown.length) return problem(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} (a ${desc.fileKind} carries ${allowed.join(", ")})`, unknown[0]);
   const name = doc.id === undefined ? stem : doc.id;
-  if (typeof name !== "string" || !AUTOMATION_ID_RE.test(name)) return problem(`the id (${doc.id === undefined ? "the filename stem" : "id:"} ${JSON.stringify(name)}) must be lowercase letters, digits and dashes, 1 to 40 characters`, "id");
+  const namePattern = desc.kind === "schedule" ? SCHEDULE_NAME_RE : AUTOMATION_ID_RE;
+  if (typeof name !== "string" || !namePattern.test(name)) return problem(`the id (${doc.id === undefined ? "the filename stem" : "id:"} ${JSON.stringify(name)}) must be lowercase letters, digits and dashes, 1 to ${desc.kind === "schedule" ? 100 : 40} characters`, "id");
   if (typeof doc.runsOn !== "string" || !HOST_NAME_RE.test(doc.runsOn)) return problem("runsOn: the host name that runs it (oats-local.yaml host.name: lowercase letters, digits and dashes)", "runsOn");
   const owner = parseOwner(doc.owner);
   if (!owner) return problem("owner: the GitHub account it acts as, <host>/<login> (e.g. github.com/acme-kb-bot)", "owner");