@awebai/oats 0.28.0 → 0.29.1

package/docs/packages.md

@@ -74,8 +74,8 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.1.3
-  oats.okf: v3.0.0
+  oats.framework: v1.3.0
+  oats.okf: v4.0.0
   oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
@@ -263,7 +263,13 @@ oats-package/
   `agents/<package>--<soul>/` (the package id with `.` as `-`:
   `agents/oats-okf--knowledge-maintainer/`), which is also its agent name
   (`OATS_AGENT`, the `oats status` row); its instances are named from it
-  (`oats-okf-knowledge-maintainer-<purpose>`). A soul name never holds `--`,
+  (`oats-okf-knowledge-maintainer-<purpose>`). That prefix counts toward the
+  64-character instance-name limit, so a package soul's purposes are short:
+  `oats-okf-knowledge-maintainer-` is 30 characters, which leaves 34 for the
+  purpose (fewer when a `-2` suffix de-duplicates it). A longer one is
+  `E_INSTANCE_NAME_INVALID { prefix, purpose, maxPurpose }`, naming the budget;
+  a trigger's or schedule's purpose template obeys the same limit when it
+  renders. A soul name never holds `--`,
   so a member soul of the same bare name keeps its own `agents/<soul>/`.
   Two packages whose ids sanitise alike (`a.b`, `a-b`) and that ship a
   same-named soul would share a directory: both are listed with an
@@ -338,8 +344,8 @@ A soul that names one of the package's capabilities with
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.2.0`
-resolves to tag `oats-framework/v1.2.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.3.0`
+resolves to tag `oats-framework/v1.3.0`. Resolving through the catalog never
 advances a lock by itself — `oats sync` does, and
 says so.
 

package/docs/release-lane.md

@@ -30,7 +30,7 @@ under `stage/<tag>/logs/`; a failing step exits non-zero with the log path.
 
 | Phase | Mirrors in `release.yml` | Writes |
 | --- | --- | --- |
-| `build --tag vX.Y.Z [--sha <commit>]` | job `build-and-test`: notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
+| `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
 | `desktop --tag vX.Y.Z --arch arm64\|x64` | one `desktop-build` matrix leg: desktop `npm ci`, `npm test`, `npm run dist -- --<arch>`, strict deep `codesign --verify` (macOS), `dist:smoke` in build-verify mode | `assets/oats-desktop-*` |
 | `stage --tag vX.Y.Z` | publish job, "Checksums" (`shasum -a 256`) | `assets/SHA256SUMS.txt` |
 | `publish-npm --tag vX.Y.Z [--dry-run] --yes` | publish job, the two guarded `npm publish --access public` steps, kernel then adapter | — |

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

@@ -0,0 +1,240 @@
+# OATS 0.29.0
+
+## Added
+
+- **Workspace triggers and schedules** (feature `automations`). A trigger or a
+  schedule can now be declared in Git, in any confirmed member, and shared with the
+  team. It is named `<member>/<id>`, and a machine's own ones are named
+  `local/<id>`. See
+  [schedules.md#workspace-triggers-and-schedules](../schedules.md#workspace-triggers-and-schedules).
+  - Triggers and schedules stay separate:
+
+    | | triggers | schedules |
+    | --- | --- | --- |
+    | folder | `oats-triggers/` | `oats-schedules/` |
+    | file name anywhere in the member | `*.oats-trigger.yaml` | `*.oats-schedule.yaml` |
+    | `kind:` | `oats-trigger` | `oats-schedule` |
+    | commands and list | `oats trigger …` | `oats schedule …` |
+    | opt-out | `triggers.disabled` | `schedules.disabled` |
+
+    `oats-package/`, `.git/` and `node_modules/` are never scanned.
+  - Every file carries `kind`, `schemaVersion: 1`, `runsOn` (the host that runs it)
+    and `owner` (the GitHub account it acts as). The wrong kind is
+    `E_AUTOMATION_SCHEMA`, and a duplicate id is `E_AUTOMATION_DUPLICATE`.
+  - A host runs one only when `runsOn` is its new `oats-local.yaml` `host.name`
+    **and** its `gh` is logged in as `owner`. Otherwise the item is listed as
+    `assigned-elsewhere`, `owner-mismatch` or `host-unnamed`.
+  - `oats trigger disable <member>/<id>` and `oats schedule disable <member>/<id>`
+    stop it on this host without a commit, by writing `triggers.disabled` or
+    `schedules.disabled` in `oats-local.yaml`.
+  - `oats sync` takes a snapshot of them. The host tick reads the snapshot and
+    refreshes it every ten minutes (`oats automations refresh`).
+  - `oats trigger add … --workspace <member> --runs-on <host> --owner <host>/<login>`
+    writes the file in a checkout of the member, or prints it. `oats schedule add`
+    takes the same options.
+  - `oats trigger list --json` and `oats schedule list --json` answer the Desktop's
+    rows for both levels: the owner, where it runs and why (not), the soul and
+    where it comes from, the task verbatim, the event or cron, and the last and
+    next run. Local schedule rows keep their bare `id` and add `qualifiedId`. See
+    [desktop-cli-api.md](../desktop-cli-api.md).
+  - Each row's `origin` carries `url` (the file on GitHub at its commit) and
+    `localPath` (the file in this machine's clone of the member), each `null` when
+    there is none. Both lists carry `host.ghUser` (who `gh` is logged in as, per
+    GitHub host) and the host `scheduler`. "When it next runs" is `nextDue`
+    everywhere.
+- **Desktop facts** (feature `desktop-facts`): kernel facts the Desktop's Workspace
+  view shows, so it never derives them. Every field is an addition. See
+  [desktop-cli-api.md](../desktop-cli-api.md#desktop-facts-feature-desktop-facts-oats-0290).
+  - `oats inspect --soul --json`: each capability's `composedFrom` (`workspace`,
+    `team:<label>` or `soul`), and `capabilitiesOff[]`, the defaults the soul
+    turned off (`<id>: off` or `<slot>: none`).
+  - `oats souls --json` rows: the default `harness`/`model` a spawn starts with,
+    and `spawnable` and `problem`, the refusal a spawn would meet (it spawns
+    nothing). Also `file`.
+  - `oats capabilities --json` rows: `layer` on package rows too, `description`,
+    `skills`/`commands`/`hooks` by name, `file`, and a member capability's `tree`
+    (its Git tree id).
+  - `oats workspace status --json`:
+    - the workspace and team `defaults` as rows;
+    - this computer's member `clones` and the rule that found each;
+    - `disabledSouls`;
+    - `lock` (`path`, `lockfileVersion`);
+    - `packages[].latest` when the shipped catalog has a newer version;
+    - file locations (`workspace.file`, `members[].url`,
+      `members[].membershipFile`).
+  - `oats status --json` instance rows: `startedAt` (the last start or restart),
+    `modelFrom` (also recorded in `instance.json`) and `identityAddress`. A member
+    module's drift `current` gains `version`.
+  - URLs are GitHub pages at the row's commit, `null` for any other host.
+  - `oats help` lists `spawn --provider`.
+- **`oats schedule test <id>`**: where a schedule runs, whether its soul resolves
+  (a spawn preview) and when it is next due. It spawns nothing, like
+  `oats trigger test`.
+- **`launchConfig`** on a trigger's `spawn` and on a spawn schedule: the soul starts
+  on that launch configuration of the running host (`oats-local.yaml`
+  `launch-configs`). A package trigger template can expose it as a parameter.
+- `oats trigger status --json` rows add `nextDue`, `concurrency` and `liveCount`;
+  `oats trigger test --json` `wouldFire` items add `repo`.
+- **`OATS_SETTINGS_ORIGINS`** beside `OATS_SETTINGS`, for every hook and
+  capability command (and readiness probes): where each leaf of the payload came
+  from, a JSON pointer → `{ kind, at }` (`manifest-default`, `workspace`, `soul`,
+  `host`, `spawn`). A provider can tell a soul-set value from a host-set one
+  without reading `soul.yaml`. `instance.json` records it with the settings
+  (`capabilities[].settingsOrigins`, `capabilityRuntime[].settingsOrigins`).
+
+## Changed
+
+- **oats.framework 1.3.0 pinned.** The official catalog pins `oats.framework` to
+  `oats-framework/v1.3.0` (this repository's workspace pins it too). 0.28.1 was never
+  released, so this pin covers three framework releases:
+  - **1.2.0:** the setup-admin skills. oats.setup 2.1.0 adds `oats-setup-model`,
+    `oats-workspace-config`, `oats-teams`, `oats-automations` and a setup inject,
+    and oats.core 2.1.0 is current for an instance's view. The `oats-setup-admin`
+    soul uses them.
+  - **1.2.1:** OKF knowledge operations in onboarding (oats.setup 2.1.1,
+    `oats-onboarding`).
+  - **1.3.0:** `knowledge-theory-expert` is a package soul
+    (`oats spawn oats.framework/knowledge-theory-expert`), with
+    oats.knowledge-theory 1.1.0.
+
+  A workspace picks it up by pinning `oats.framework: v1.3.0` and running
+  `oats sync`.
+- **A local trigger's id is `local/<id>`** in `oats trigger` rows, in its dedup keys
+  and state, and in a triggered instance's `instance.json.trigger.id` and event
+  file. It was the bare id in 0.28.0. Every `oats trigger` verb still accepts the
+  bare id.
+
+## Removed
+
+- **BREAKING: capability-defined agents.** A capability manifest's `agents:` is
+  refused at resolution, with
+  `E_CAPABILITY_AGENTS_REMOVED { capability, agents, from }`. The remedy names the
+  replacement: a **package soul** (`souls/<name>/` in the package, spawned as
+  `oats spawn <package>/<name>`) or a **member soul**. `oats spawn <name>` no
+  longer falls back to an agent declared by a materialized or locked module; an
+  unknown name is `E_SOUL_UNKNOWN`. The manifest schema drops `agents`.
+  - A home an earlier kernel spawned for one (its agent directory holds only
+    `instances/`) is still listed by `oats status`, may be a `--parent`, and
+    retires. Nothing creates one any more.
+  - This repository's users moved:
+    - oats.okf 4.0.0's harvester is a package soul;
+    - the post-commit **`reviewer`** is an oats.dev **1.1.0** package soul
+      (`oats.dev/reviewer`, beside oats.review 1.3.0; the pin moves to
+      `v1.1.0`), and oats.review's inject spawns it unchanged, now named
+      `oats-dev-reviewer-<short-sha>`;
+    - **`knowledge-theory-expert`** is an oats.framework **1.3.0** package soul
+      (`oats spawn oats.framework/knowledge-theory-expert`), with
+      oats.knowledge-theory 1.1.0.
+  - A v2 soul.yaml declares no harness or model, so the reviewer's harness and
+    model now come from the **spawner's launch configuration** (its former pin was
+    pi, gpt-5.6-sol).
+
+## Fixed
+
+- A package soul's derived instance name is checked and de-duplicated as the name
+  the home gets (`acme-pkg-keeper-<purpose>`, not `acme-pkg--keeper-…`). A
+  purpose inside the limit is no longer refused, and a second spawn with the same
+  purpose is `…-2` instead of a collision. An over-long purpose is
+  `E_INSTANCE_NAME_INVALID` naming how many characters the purpose may have
+  (`details.maxPurpose`).
+
+- Concurrent spawns of the same instance: a spawn that loses the race now refuses
+  with `E_PLACEMENT_TAKEN` (it created nothing). It used to fail with an uncoded
+  "instance already exists" error, surfaced as `E_SPAWN_FAILED`.
+- Disabled-here messages name the per-kind key (`triggers.disabled`,
+  `schedules.disabled`).
+
+## Desktop
+
+- **Schedules and Triggers tabs** on the automations contract. Rows are grouped by
+  where they run: on this computer, needing attention here, or elsewhere. Workspace
+  and local items are listed together, with an origin chip, a filter and a search.
+  - Each row has an on-here switch, the soul and where it comes from, the cron in
+    words or the trigger's event, and where it runs and as whom. It also shows the
+    last and next run, and a menu (Open, Test, Run now, on/off here, Open file).
+  - A row opens a detail page: the prompt verbatim, the schedule or event, recent
+    runs, the kernel's placement verdict, where it comes from, and the test result.
+  - The old Schedules read path is gone.
+- **Why each capability is there.** The soul page and an instance's soul tab tag
+  each capability `workspace`, `team · <label>` or `soul`, and list the defaults the
+  soul turned off (including a slot it emptied), from the kernel's Desktop facts.
+- **A moved module names its versions**: "moved 2.1.5 → 2.2.0" in the instance
+  panel's module drift.
+- The Desktop accepts OATS CLIs `>=0.25.8 <0.30.0`.
+
+## Internal
+
+- The release workflow runs the test suite in six parallel shards, like PR CI, and
+  publication waits for every shard.
+
+## Upgrading from 0.28
+
+> **0.29.0 and oats.okf 4.0.0 move in lockstep.** On kernel 0.29.0, oats.okf ≤3.x
+> is refused because it declares a capability agent, and oats.okf 4.0.0 requires
+> kernel 0.29.0. A deployment on okf 3.x therefore **stays on kernel 0.28 until it
+> moves its pins**. It then upgrades in one sitting, in this order:
+
+1. **Upgrade the kernel**: the npm package, the pi adapter and the Desktop, all
+   0.29.0.
+2. **Move the pins** to the official catalog's: `oats.okf: v4.0.0`,
+   `oats.dev: v1.1.0`, `oats.framework: v1.3.0`.
+3. **Run `oats sync`.**
+
+Between step 1 and step 3, a package pinned below its 0.29 release still declares
+`agents:`. A spawn, preview or `inspect --soul` of any soul that composes it
+refuses with `E_CAPABILITY_AGENTS_REMOVED`:
+- **oats.okf ≤3.x** (`memory-harvest`): this is **every soul with oats.okf in its
+  knowledge slot**;
+- **oats.dev 1.0.x** (`reviewer`);
+- **oats.framework ≤1.2.x** (`knowledge-theory-expert`).
+
+Harvest is off by default in okf 4.0.0. Switch it on
+(`oats okf setup --harvest on`) where you want it.
+
+Homes spawned earlier keep loading their recorded modules. Homes spawned for a
+capability agent stay listed and retirable.
+
+## oats.okf 4.0.0 (catalog pin and bundled mirror)
+
+The official catalog now pins `oats.okf` to `v4.0.0` (tag object `239f2885`,
+commit `1f0ba12f`). The copy bundled in this package is its byte mirror.
+
+**BREAKING:**
+- The package requires `oats >=0.29.0`; an older kernel refuses it
+  (`E_CAPABILITY_INCOMPATIBLE`).
+- The `okf` and `memory-harvest` skills are gone from `oats.okf`.
+
+- **Three capabilities.** The package now exports:
+  - `oats.okf`: the knowledge slot;
+  - `oats.okf-harvest`: the harvester's completion and status commands;
+  - `oats.okf-maintenance`: the maintainer's review context.
+
+  The catalog maps `oats.okf-harvest` and `oats.okf-maintenance` to the
+  `oats.okf` package.
+- **Working souls get two skills and the inject.** A soul with `oats.okf` in
+  its knowledge slot gets `okf-consultation` and `okf-instance-knowledge`, and
+  the okf inject.
+- **The harvester is a package soul.** `oats okf run-source` (and `oats okf
+  harvest`) spawns `oats.okf/knowledge-harvester`. It is named
+  `okf-harvester-<run>` and homes under
+  `agents/oats-okf--knowledge-harvester/`. It is no longer the `memory-harvest`
+  capability agent. After a successful completion it stays alive in the `okf`
+  team until its PR is merged or closed. `oats.okf/knowledge-maintainer` is the
+  package's second soul.
+- **The harvest-review trigger.** The package ships the trigger template
+  `harvest-review` (`triggers/harvest-review.json`). It watches the labelled
+  harvest PRs.
+- **`harvest: on|off`** (default **off**). Harvest is a host switch in
+  `oats-local.yaml` `settings.oats.okf.harvest` (`oats okf setup --harvest
+  on|off`). Off means no source registration, capture or custody. A soul can
+  only opt out (`knowledge: { harvest: off }`).
+- **`oats okf read` is removed** (`E_REMOVED`). Use `oats okf cat --base
+  <alias> <path>`, which takes the same path and gives the same text and
+  receipt.
+
+The bundled mirror now covers the three capability directories
+(`capabilities/oats-okf`, `capabilities/oats-okf-harvest`,
+`capabilities/oats-okf-maintenance`). The package's souls and trigger are
+checked byte for byte in `scripts/okf-source-inventory.json` (schemaVersion 2).
+The npm package does not ship them, because the kernel reads a package's souls
+and triggers from Git at its locked commit.

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

@@ -0,0 +1,79 @@
+# OATS 0.29.1
+
+## Added
+
+- **Per-file line counts in `oats instance git`.** Each tracked file entry has
+  `additions` and `deletions` (integers) and `binary`, so the Desktop can show
+  `+84 −3` beside a changed file. They come from one `git diff --numstat`
+  against the observed commit, counting staged and unstaged changes together,
+  which is the same baseline as the status letters and `oats instance diff`.
+  - A binary file has `additions: null, deletions: null, binary: true`.
+  - An untracked file or a submodule has all three `null`.
+  - A rename is counted on its new path.
+  - `instanceGitApi` stays 1: the fields are additive. The text output shows
+    `+N -M` after each path. See
+    [desktop-cli-api.md](../desktop-cli-api.md#instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247).
+
+## Changed
+
+- **The `oats-setup-admin` soul is never harvested.** Its `soul.yaml` opts out
+  of OKF harvest with `knowledge: { harvest: off }`: its sessions work on the
+  deployment's own config and carry deployment specifics that must not reach
+  the shared knowledge base. oats.okf 4.0.0 makes a soul's opt-out absolute, so
+  a deployment that switches harvest on (`settings.oats.okf.harvest: on`)
+  still registers no source, captures nothing and takes no custody for its
+  instances. `oats okf harvest-status` in one of its homes reports
+  `harvest: off` with the soul's reason.
+
+## Desktop
+
+The Desktop now shows the kernel's 0.29 Desktop facts and the Workspace v4
+design's Git & GitHub section. On an older kernel, each fact is absent and its
+view shows nothing new.
+
+- **Souls say when a spawn here would refuse** (#228, #231). A soul the kernel
+  reports as not spawnable shows "Can't spawn here" with the kernel's reason on
+  its card and page, and its Spawn and Schedule… are disabled with that reason.
+  A soul page offers Open file for a hosted soul file, and shows the file's path
+  when it has no web address.
+- **The server passes the kernel's Desktop facts through** (#230). Its souls,
+  capabilities, workspace status and instance projections keep those fields,
+  bounded, instead of dropping them. A soul's spawn default is nested as
+  `spawnDefault`, so it is never read as the soul's own harness or model.
+- **Capability pages** (#232) show the description, what the capability
+  provides (skills, commands and hooks by name, or "Not listable"), its file and
+  its fingerprint.
+- **Setup names the files and this computer's state** (#233). It names the
+  workspace and membership files, and links them when they are hosted. A member
+  panel has Open repository and its clone on this computer. This computer lists
+  the lock file, disabled souls and each member's clone, or "not cloned here".
+  Packages with a newer version say "X available".
+- **Setup shows the workspace defaults** (#237): each slot and its source ("not
+  set" or "none" when empty), the default capabilities, and what each team adds
+  or turns off.
+- **The instance page** (#235) says when the session started, where its model
+  came from (the soul, the spawn, the start, the launch configuration or the
+  harness default), and its messaging address.
+- **Each local instance's pull request on its roster row** (#234, #236). A new
+  `POST /api/forge-roster` maps each instance to its member's clone from the
+  kernel's workspace status and reads the branch's PR with `gh`, cached for a
+  minute. The row shows `#N`, with draft, merged or closed in words. Remote
+  instances, and hosts without a signed-in `gh`, show no badge.
+- **W6 Git & GitHub** (#239, #240, #241, #242, #243). The instance's Git panel
+  follows the design:
+  - **Branch** shows the work mode, the distance from the default branch and
+    whether the tree is clean, with the rest behind Details.
+  - **Changes** is a list of status letters and paths, with Open diff.
+  - **Pull request** shows the title and state, the issues it closes and the
+    checks: failing first, with how long each took. It also shows the review
+    decision with the count of unresolved review threads, and has Open on
+    GitHub.
+  - Check marks are icons. The thread count is read only for the open
+    instance's PR, never for the roster.
+- **Automations through the app proxy** (#224). `/api/automations` has its own
+  proxy route, pinned to the verified workspace like the other workspace
+  endpoints. It has a 90 s deadline, so `trigger test` (which polls the forge)
+  is no longer cut off in the packaged app. The automations docs describe the
+  API and the proxy.
+- **Docs** (#227): the documented Desktop band is `>=0.25.8 <0.30.0`.
+- The Desktop still accepts OATS CLIs `>=0.25.8 <0.30.0`.

package/docs/schedules.md

@@ -39,7 +39,7 @@ see [Captured definitions](#captured-definitions-removed-in-026).
 ## Kinds
 
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
-  repo?, backend?, purpose?, task, harness?, model?, yolo?, wake?}` — every
+  repo?, backend?, purpose?, task, launchConfig?, harness?, model?, yolo?, wake?}` — every
   due minute launches one disposable instance of `agent` with the same
   options `oats spawn` takes. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
@@ -153,7 +153,10 @@ logged in with the keyring or its config file under your HOME works there. A
   request's title and body are untrusted and never reach the task (a template
   naming any other field is refused). `teams` becomes the messaging
   capability's `join=` setting (as `--provider <messaging cap> join=<labels>`).
-  `harness`, `model`, `yolo`, `backend` are as for schedules.
+  `launchConfig` (a launch configuration in the running host's
+  `oats-local.yaml` `launch-configs`), `harness`, `model`, `yolo`, `backend`
+  are as for schedules; a package template may expose any of them as a
+  parameter (`"path": "spawn.launchConfig"`).
 - **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
   (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number, url,
   event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
@@ -169,7 +172,7 @@ oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowl
 oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
 oats trigger test <id>      # dry run: gh auth + credential source, repo + permissions (push/maintain/admin), the soul resolves,
                             # its messaging capability, the teams declared, what WOULD fire now; spawns nothing
-oats trigger status [<id>]  # last poll, pending, fired keys, live instances, last error
+oats trigger status [<id>]  # last poll, next due, pending, fired keys (time, instance), live vs max, last error
 ```
 
 All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
@@ -187,6 +190,119 @@ comma-separated); a required parameter without a value is `E_BAD_ARGS
 { missing }` naming it. The trigger records `template: { package, version,
 commit, template }`.
 
+## Workspace triggers and schedules
+
+(OATS 0.29.0, feature `automations`.) A trigger or a schedule is defined at one of
+two levels:
+
+- **in the workspace**: a file committed in a confirmed member repository, shared
+  through Git and named `<member>/<id>`. This is the default for anything a team
+  relies on.
+- **locally**: in the deployment's `oats-schedules.json` (`oats trigger add`,
+  `oats schedule add`), machine-private and named `local/<id>`.
+
+The two kinds stay separate at every step. Each has its own folder, its own file
+kind, its own ids, its own commands, its own list and its own opt-out.
+
+| | trigger | schedule |
+| --- | --- | --- |
+| canonical folder (at the member's root) | `oats-triggers/` | `oats-schedules/` |
+| file name anywhere in the member | `*.oats-trigger.yaml` | `*.oats-schedule.yaml` |
+| `kind:` | `oats-trigger` | `oats-schedule` |
+| body | `from:` + `set:` (a package template), or `on`, `spawn`, `concurrency` as above | `run: spawn \| command`, `cron`, `tz`, `agent`, `task`, `purpose`, `launchConfig`, `harness`, `model`, `yolo`, `backend`, `wake`, `argv`, `cwd` |
+| commands | `oats trigger …` | `oats schedule …` |
+| opt-out on this host | `triggers.disabled` | `schedules.disabled` |
+
+Every `.yaml`/`.yml` under a canonical folder is a candidate, and so is a file with
+the kind's suffix anywhere in the member (`.yml` works too), e.g.
+`services/billing/nightly.oats-schedule.yaml` beside the code it concerns.
+`oats-package/`, `.git/` and `node_modules/` are never scanned.
+
+```yaml
+# <member>/oats-triggers/okf-harvest-review.yaml
+kind: oats-trigger
+schemaVersion: 1
+description: Review every harvest PR on the knowledge base
+from: oats.okf:harvest-review        # a package template at the locked commit, then its parameters
+set: { repo: github.com/acme/knowledge }
+runsOn: kb-bot-server                # the host.name that runs it
+owner: github.com/acme-kb-bot        # the GitHub account it acts as
+```
+
+```yaml
+# <member>/services/billing/nightly.oats-schedule.yaml
+kind: oats-schedule
+schemaVersion: 1
+run: spawn
+cron: "0 7 * * *"
+tz: Europe/Madrid
+agent: digest-writer                 # resolved like `oats spawn <soul>` (member or package soul)
+task: Write the nightly digest.
+runsOn: ana-laptop
+owner: github.com/ana
+```
+
+- **The file describes itself.** It carries `kind` and `schemaVersion: 1`. A
+  candidate of the wrong kind (a schedule in `oats-triggers/`) or without one 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: they are different things.
+- **A workspace schedule is `run: spawn` or `run: command`.** A `command`'s `cwd` is
+  relative to the deployment. `wake` and `operation` target an instance home on one
+  machine, so they stay local.
+
+**Who runs it.** A host runs a workspace trigger or schedule only when both of these
+hold:
+
+1. its `runsOn` is this host's `host.name` in `oats-local.yaml`;
+2. the host's authenticated `gh` account (`gh api user`, asked once per tick) is its
+   `owner`.
+
+Otherwise the item is listed with a reason:
+
+- `assigned-elsewhere`: another host runs it;
+- `owner-mismatch`: this host is named, but its `gh` is logged in as someone else or
+  not at all. Nothing runs, the tick reports it, and `oats trigger test` says so;
+- `host-unnamed`: this host has no `host.name`.
+
+So exactly one machine runs it, and consent is explicit: the machine's operator
+named the host and is logged in as the account.
+
+**Opting out** without a commit: `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 here (`update` and `remove` are
+`E_AUTOMATION_WORKSPACE`): change the file in Git.
+
+**Refresh.**
+
+- `oats sync` discovers the workspace triggers and schedules of the confirmed
+  members into a snapshot, `.agents/automations/snapshot.json` in the deployment,
+  with one list per kind. It takes one tree listing per member commit.
+- The host tick reads that snapshot. It refreshes it (`oats automations refresh`)
+  when the snapshot is more than ten minutes old, at most once per interval. When
+  the refresh fails, the last good snapshot keeps serving.
+- A change in Git therefore reaches the named host within about ten minutes.
+- The run state (dedup keys, last poll, last run) stays per host and local. A
+  workspace schedule's job lock and state are keyed `<member>~<id>`.
+- A trigger template (`from:`) is instantiated when the snapshot is taken, at the
+  commit the host's lock pins.
+
+**Writing one.** Add `--workspace <member> --runs-on <host> --owner <host>/<login>`
+to `oats trigger add` or `oats schedule add`:
+
+- Run inside a checkout of that member, it writes `oats-triggers/<id>.yaml` or
+  `oats-schedules/<id>.yaml` there, for you to commit and push.
+- Anywhere else, it prints the file.
+- Either way, the file is read back and validated first.
+- `oats trigger test <member>/<id>` checks the placement, and everything else it
+  checked before, on this host.
+
+Everything above still holds: the soul must resolve here, templates name only the
+whitelisted fields, a PR's text is never interpolated, and no definition carries a
+credential.
+
 ## Captured definitions (removed in 0.26)
 
 0.24–0.25 could save captured command definitions: `definitionVersion`,
@@ -217,6 +333,7 @@ oats schedule add <id> --file spec.json --dir <workspace> --json
 oats schedule update <id> --file spec.json
 oats schedule list | show <id> | enable <id> | disable <id> | remove <id>
 oats schedule run <id>            # now, under the same lock and bound
+oats schedule test <id>           # dry run: where it runs, whether its soul resolves, when it is next due; spawns nothing
 oats schedule tick --dry-run      # what would run this minute, launching nothing
 oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
 oats schedule host install        # register this scope and install the ONE host timer (idempotent while active)
@@ -227,8 +344,9 @@ oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --w
 Every subcommand takes `--server <id>` instead of `--dir`: it then runs on
 that host, in its registered workspace, because schedules are host-owned.
 
-`list --json` answers `{schedules: [{id, ...definition, nextRun, lastRun,
-running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
+`list --json` answers `{schedules: [{id, ...definition, nextDue, lastRun,
+running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`
+(`oats trigger list --json` carries the same `scheduler`).
 `active` is what the OS reports about the timer, not whether a file exists.
 
 ## What a run reports
@@ -292,6 +410,16 @@ the instance is neither hidden nor spawned again.
 
 ## OKF v2 source jobs
 
+> **oats.okf 4.0.0:** a source and its job exist only where harvest is
+> effectively on (`harvest: on|off`, default off), and the job spawns the
+> harvester package soul. The review of its PR runs as a **trigger**, run by
+> the same host tick: a workspace file (`oats-triggers/okf-harvest-review.yaml`
+> in a member repo, `kind: oats-trigger`, with `runsOn` and `owner`), or a
+> local one in this file. See
+> [knowledge.md](knowledge.md#knowledge-operations), [Triggers](#triggers) and
+> [Workspace triggers and schedules](#workspace-triggers-and-schedules); the
+> trigger commands are `oats trigger …`.
+
 The [prepared OKF v2 runtime](knowledge.md) registers **one command job per
 source**, not a fleet sweep or a home-bound operation job. It runs from stable
 deployment context with argv equivalent to:

package/docs/souls-and-instances.md

@@ -516,14 +516,12 @@ Default layout:
     docs-expert/         # a workspace soul, defined in a member repository's
       souls/<commit12>/  #   souls/docs-expert/ and copied here per commit
       instances/
-    memory-harvest/      # a capability-defined agent: only instances/, no soul
-      instances/
 ```
 
-A capability-defined agent (declared by a package or member module, such as
-the OKF harvester) homes under the agents root exactly like a soul; its
-directory holds only `instances/`. A name that is both a workspace soul and a
-capability agent is ambiguous (`E_SOUL_AMBIGUOUS`).
+Every agent is a soul — a member soul, or a package soul homed under
+`agents/<package>--<soul>/`. A capability-defined agent (a manifest's
+`agents:`) was removed in 0.29.0; a home an earlier kernel left for one (its
+directory holds only `instances/`) is still listed and retirable.
 
 There are no local souls. A soul is a member repository's `souls/<name>`
 (`soul.yaml` + `AGENTS.md`); author it there and run `oats sync`. OATS 0.25

package/docs/workspaces.md

@@ -59,8 +59,8 @@ 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.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v3.0.0
+  oats.framework: v1.3.0                   # bare version → resolves through the official catalog
+  oats.okf: v4.0.0
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -169,8 +169,17 @@ settings:                                  # host-owned values the manifests ask
     state-dir: /Users/ana/.oats/okf
 souls:
   disabled: [data-analyst]                 # not run on this machine (E_SOUL_DISABLED); oats.okf/knowledge-harvester names a package soul
+host:
+  name: ana-laptop                         # this machine's name: runs the workspace triggers/schedules whose runsOn names it
+triggers:
+  disabled: [knowledge/okf-harvest-review] # workspace triggers this host does not run (oats trigger disable)
+schedules:
+  disabled: [platform/nightly-digest]      # workspace schedules this host does not run (oats schedule disable)
 ```
 
+`host`, `triggers.disabled` and `schedules.disabled` (0.29.0) are machine facts:
+see [schedules.md#workspace-triggers-and-schedules](schedules.md#workspace-triggers-and-schedules).
+
 See [configuration.md](configuration.md). `oats-config.yaml` no longer exists.
 
 ### `oats-lock.json` — lock v3