@awebai/oats 0.49.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -248,6 +248,48 @@
248
248
  }
249
249
  }
250
250
  },
251
+ "triggerSources": {
252
+ "description": "Trigger sources (#669): each a command of this capability that, at each poll, lists the events due now; a trigger names one as on.source \"<capability>:<source>\". Validated only where a source is used (trigger add, a poll, trigger test and trigger poll), never when the capability loads: a malformed declaration fails the triggers naming it (E_TRIGGER_SOURCE) and nothing else. Checked at use only, not by this schema: every pattern compiles; command names a key of commands; a parameter default matches its pattern. A pattern is ECMA-262 with the u flag, matched anchored as ^(?:…)$; the default parameter value pattern is ^[A-Za-z0-9._/:@ ,*-]{0,200}$ and the default field pattern ^[A-Za-z0-9._/:@-]{1,200}$. Whatever its pattern admits, an event's field value is at most 200 code points and carries no control, bidi, invisible or tag character.",
253
+ "type": "object",
254
+ "maxProperties": 16,
255
+ "propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]{0,39}$" },
256
+ "additionalProperties": {
257
+ "type": "object",
258
+ "required": ["command", "events"],
259
+ "additionalProperties": false,
260
+ "properties": {
261
+ "command": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "One of this manifest's commands: the source's program, run once per poll (one JSON request on stdin, one JSON answer on stdout)." },
262
+ "description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
263
+ "events": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } },
264
+ "parameters": {
265
+ "type": "object",
266
+ "maxProperties": 16,
267
+ "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
268
+ "additionalProperties": {
269
+ "type": "object",
270
+ "additionalProperties": false,
271
+ "properties": {
272
+ "required": { "type": "boolean" },
273
+ "default": { "type": "string", "maxLength": 200 },
274
+ "description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
275
+ "pattern": { "type": "string", "minLength": 1 }
276
+ }
277
+ }
278
+ },
279
+ "fields": {
280
+ "type": "object",
281
+ "maxProperties": 16,
282
+ "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
283
+ "additionalProperties": {
284
+ "type": "object",
285
+ "additionalProperties": false,
286
+ "properties": { "pattern": { "type": "string", "minLength": 1 } }
287
+ }
288
+ },
289
+ "urlHosts": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "maxLength": 253, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$" } }
290
+ }
291
+ }
292
+ },
251
293
  "hooks": {
252
294
  "type": "object",
253
295
  "properties": {
@@ -78,6 +78,98 @@ Which teams a soul may join, and its default, are committed in the workspace's
78
78
  commit instead). How teams are resolved, and what a messaging provider does
79
79
  with them, is in [workspaces.md](workspaces.md#teams).
80
80
 
81
+ ## Claude channel delivery: the approved route
82
+
83
+ Claude seats on aweb channel delivery start without Claude's “WARNING:
84
+ Loading development channels” prompt through the **approved route**: the
85
+ `oats.aweb` setting `claudeChannelMode: approved` starts Claude with
86
+ `--channels plugin:aweb-channel@awebai-marketplace`, and Claude shows no
87
+ development prompt. Claude admits the plugin when a root-owned machine
88
+ managed-settings file lists it. The route does not depend on the Claude
89
+ version and needs no OATS mechanism beyond these settings. The operator's
90
+ ordered procedure is the `oats.setup` host step “Claude channel delivery
91
+ (approved route)” in `/oats-workspace-config`, which `/oats-onboarding` card 4
92
+ calls; the provider's side is `/oats-aweb` §4.
93
+
94
+ **The managed-settings file** is a host change made by a human admin with
95
+ sudo. OATS never writes it.
96
+
97
+ | | |
98
+ |---|---|
99
+ | Location | Linux: `/etc/claude-code/managed-settings.json`; macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` |
100
+ | Owner and mode | root, `0644` |
101
+ | Content | exactly `{"channelsEnabled": true, "allowedChannelPlugins": [{"plugin": "aweb-channel", "marketplace": "awebai-marketplace"}]}` |
102
+ | Existing file | merge these two keys into it; never overwrite other keys |
103
+ | Drop-ins | Claude also reads `managed-settings.d/*.json` beside the file |
104
+
105
+ Setting `allowedChannelPlugins` **replaces Anthropic's default channel
106
+ allowlist** on that host. That list is the official discord, telegram,
107
+ fakechat and imessage plugins; a host that uses any of them must list them
108
+ too.
109
+
110
+ **Precedence.** Claude reads its managed policy from the first source
111
+ present: server-managed settings (a claude.ai Team/Enterprise organization's
112
+ admin console), then an MDM profile (`com.anthropic.claudecode` on macOS), then
113
+ the file. On an account governed by server-managed settings or MDM the file is
114
+ ignored, and the organization admin sets the same two keys there instead.
115
+ Pro/Max accounts and plain API-key use have no server-managed settings, so the
116
+ file applies. `channelsEnabled: true` is required for API-key users whenever
117
+ any managed policy exists, and for Team/Enterprise subscribers; Pro/Max ignore
118
+ it. It is harmless there: always include it.
119
+
120
+ **OATS side**, in this host's `oats-local.yaml` under `settings.oats.aweb`:
121
+
122
+ ```yaml
123
+ settings:
124
+ oats.aweb:
125
+ claudeChannelMode: approved # host-only
126
+ delivery: channel # host-wide; or per spawn: --provider oats.aweb delivery=channel
127
+ ```
128
+
129
+ With channel delivery, pi uses its `@awebai/pi` extension and Codex always
130
+ uses the host broker.
131
+
132
+ **The plugin.** `aweb-channel` must be installed from the marketplace named
133
+ `awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
134
+ Claude config directory the host's Claude launch configuration uses (its
135
+ `CLAUDE_CONFIG_DIR`, else `~/.claude`).
136
+
137
+ **Existing homes** keep the delivery and channel mode recorded at their spawn.
138
+ Respawn a home to adopt the route. Setup never restarts running agents
139
+ without the operator's word.
140
+
141
+ **No launch-prompt opt-in** is needed in approved mode: the
142
+ [exact-home consent](#exact-home-launch-prompt-consent) applies only to
143
+ development mode, and qualifies only Claude 2.1.289 on `darwin-arm64`.
144
+
145
+ **Verify:**
146
+
147
+ 1. `oats spawn <soul> --preview` shows `settings.oats.aweb.claudeChannelMode:
148
+ approved` and `delivery: channel`.
149
+ 2. The started session shows no development prompt, and its banner shows
150
+ “Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
151
+ inject directly in this session”, followed by “restart without --channels
152
+ to stop”. At normal terminal widths the banner wraps over two rows: look
153
+ for each part, not for one string.
154
+ 3. The banner says none of `not on the approved channels allowlist`,
155
+ `not on your org's approved channels list`, `blocked by org policy` or
156
+ `plugin not installed`.
157
+ 4. Receive is proven only by the `/oats-aweb` nonce exchange.
158
+
159
+ **Failure banners**, their cause and remedy:
160
+
161
+ | What the session shows | Cause | Remedy |
162
+ |---|---|---|
163
+ | `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
164
+ | `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
165
+ | `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
166
+ | `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
167
+ | the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
168
+
169
+ **Limits.** Channels are an Anthropic research preview. Anthropic's
170
+ account-level feature flag gates channels on every route. The allowlist
171
+ matches the marketplace by name.
172
+
81
173
  ## Exact-home launch prompt consent
82
174
 
83
175
  `launchPromptAnswers` belongs only in the host's `oats-local.yaml`. It is
@@ -114,6 +206,8 @@ selects arguments; it does not grant consent. Approved-mode arguments, another
114
206
  plugin, multiple plugins or contradictory channel arguments cannot qualify.
115
207
  Environment values, spawn flags and saved launch recipes cannot enable consent.
116
208
  Existing harness folder-trust configuration remains independent.
209
+ The version-independent route, with no prompt to answer, is
210
+ [the approved route](#claude-channel-delivery-the-approved-route).
117
211
 
118
212
  Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
119
213
  `consentSource` without terminal capture or input. `--no-launch` never answers.
@@ -398,6 +492,9 @@ is safe to delete.
398
492
  - **Per-instance provider facts:** `oats spawn <soul> --provider <cap> key=value`,
399
493
  recorded in the instance's `instance.json`.
400
494
  - **Shared teams, stores and defaults:** the workspace file.
495
+ - **Claude's channel admission:** Claude's own managed policy (server-managed
496
+ settings, an MDM profile or the root-owned managed-settings file; see
497
+ [the approved route](#claude-channel-delivery-the-approved-route)).
401
498
 
402
499
  ## Inspecting the effective configuration
403
500
 
@@ -43,7 +43,7 @@ see the [official catalog](official-catalog.md) for current pins.
43
43
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
44
44
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
- "server-probe-features","worktree-event"],
46
+ "server-probe-features","worktree-event","session-attach-detach-key"],
47
47
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
48
48
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
49
49
  "capabilityShowApi":1}
@@ -117,7 +117,9 @@ see the [official catalog](official-catalog.md) for current pins.
117
117
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
118
118
  | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
119
119
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
120
+ | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
120
121
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
122
+ | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
121
123
 
122
124
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
123
125
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -220,6 +222,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
220
222
  | teams | soul teams <soul> … --max-age <seconds> --json
221
223
  oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
222
224
  oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
225
+ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
223
226
  ```
224
227
 
225
228
  - **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
@@ -279,8 +282,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
279
282
  `E_BAD_ARGS` first), with
280
283
  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
281
284
  verbs reuse observations (status, workspace status, souls, capabilities,
282
- capabilities show, inspect --soul|--home, spawn --preview, and the read
283
- forms of teams and soul teams)" and,
285
+ capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
286
+ and the read forms of teams and soul teams)" and,
284
287
  with `--server`, "--max-age cannot be combined with --server: observation
285
288
  reuse is local to this machine".
286
289
  A capability command's argv (`oats <namespace> …`) is its provider's: the
@@ -1000,6 +1003,15 @@ nothing reads a working clone.
1000
1003
  [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
1001
1004
  Their `path` is the repository-relative form, unlike the paths above. The
1002
1005
  text form prints them (to stderr with `--file`).
1006
+ - `triggerSources` (feature `trigger-sources`), after
1007
+ `warnings`, only when the manifest declares the key: the declaration
1008
+ exactly as written, whatever its shape (untrusted text: render it as
1009
+ text). `triggerSourceProblems: [{source, pointer, message}]` follows only
1010
+ when the declaration has problems: the ones a trigger naming a source
1011
+ would get as `E_TRIGGER_SOURCE`, `source` `null` for a top-level problem,
1012
+ `pointer` a JSON pointer into the manifest. A malformed declaration never
1013
+ refuses the command and adds nothing to `problems`
1014
+ ([capabilities.md](capabilities.md#trigger-sources-triggersources)).
1003
1015
  - With `--max-age` (`0` included) both the show and the `--file` answer gain
1004
1016
  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
1005
1017
  block `{observedAt, reused, localRevision}`.
@@ -1094,7 +1106,8 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
1094
1106
  (`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
1095
1107
 
1096
1108
  **Without `--json`** the show prints a short listing for an operator: the
1097
- inject's path and size, each skill with its files and sizes, and the
1109
+ inject's path and size, each skill with its files and sizes, the trigger
1110
+ sources (name, command, events, description) and their problems, and the
1098
1111
  problems. `--file` prints the text; a binary file prints a one-line note
1099
1112
  instead, and a truncated file prints its text followed by a one-line note.
1100
1113
 
@@ -1130,6 +1143,12 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
1130
1143
  empty list read as "no warning". Older kernels answer no such `warnings` key
1131
1144
  (inspect, readiness, show, doctor) and refuse the capability instead.
1132
1145
 
1146
+ `oats doctor --json` also lists what retires left behind in `information[]`:
1147
+ one `retained-recovery:` and one `retained-worktree:` line per item, after a
1148
+ line that gives each kind's total, and at most 50 items per kind
1149
+ ([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
1150
+ Each element is one line of text with no newline. The answer has no new key.
1151
+
1133
1152
  ### Desktop facts
1134
1153
 
1135
1154
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -2220,7 +2239,11 @@ its absence.
2220
2239
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2221
2240
  the row's recorded tmux socket and session, never the caller's `$TMUX`;
2222
2241
  `null` with `runtimeState: "unreachable"` and the tmux error as
2223
- `runtimeError` when that server cannot be read; `null` for a home a
2242
+ `runtimeError` when that server cannot be read, and also when its socket
2243
+ file is missing while a process works in the home or the process scan
2244
+ cannot run, `runtimeError` then naming the processes or the scan's error
2245
+ ([#624](execution-targets.md#missing-socket); with no process in the home
2246
+ a missing socket file reads `false`, as after a reboot); `null` for a home a
2224
2247
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2225
2248
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2226
2249
  in the row),
@@ -2917,7 +2940,10 @@ the instance back.
2917
2940
  idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
2918
2941
  "transcript", "launch"], replayed: false}`. A result is `{instance, home,
2919
2942
  ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
2920
- code, message, stillRunning: [pid]}`.
2943
+ code, message, stillRunning: [pid]}`. `code` is `E_SESSION_UNAVAILABLE` when
2944
+ whether the instance runs cannot be established, among them a recorded
2945
+ tmux socket file that is missing while a process works in the home
2946
+ ([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
2921
2947
  - `ok: false`: at least one target still runs (text mode exits 1).
2922
2948
  - A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
2923
2949
  with `replayed: true`.
@@ -2955,8 +2981,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2955
2981
  true, note}` when the session is observably gone: instance.json records no
2956
2982
  launch, or the recorded tmux server is not running, or the recorded window
2957
2983
  is gone and no pane on that server works in the home, and in every case no
2958
- live process on the host has its working directory in the home (`lsof`; a
2959
- scan that cannot run counts as not absent). Retire then proceeds
2984
+ live process on the host has its working directory in the home
2985
+ ([the process scan](souls-and-instances.md#the-process-scan): `/proc` on
2986
+ Linux, `lsof` elsewhere; a scan that cannot run counts as not absent). Retire then proceeds
2960
2987
  without quiescing (hooks run, work is preserved). Otherwise it stays
2961
2988
  `unestablished`, with a `note` saying why, and retire refuses with
2962
2989
  `E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
@@ -3038,7 +3065,10 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
3038
3065
 
3039
3066
  Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
3040
3067
  (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
3041
- `-2` suffix if taken; `detached-<oid12>` when detached), state intact. An
3068
+ `-2` suffix if taken; `detached-<oid12>` when detached), state intact. The
3069
+ `<branch>` leaf is the branch flattened to one path component, and a long one
3070
+ is cut and hashed to fit NAME_MAX
3071
+ ([souls-and-instances.md](souls-and-instances.md#extra-trees-at-retire)). An
3042
3072
  extra tree that is not clean is moved the same way; a clean one is removed.
3043
3073
 
3044
3074
  ```text
@@ -3205,7 +3235,8 @@ A first retire prints the **raw receipt**, not an envelope:
3205
3235
  `capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
3206
3236
  - A deferred self-retire (`--self`) prints `{retired, agent, deferred: true,
3207
3237
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
3208
- `{…, alreadyScheduled: true, requestedAt}`.
3238
+ `{…, alreadyScheduled: true, requestedAt}` while one is scheduled and its
3239
+ completion has not started (below).
3209
3240
 
3210
3241
  **Recorded children**, on every apply (plain, guarded and `--self`), as the
3211
3242
  plan says: each child the plan lists is stopped first (bounded SIGTERM,
@@ -3230,12 +3261,96 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
3230
3261
  `--idempotency-key` together.
3231
3262
  - A used key replays its receipt as an **envelope** with `replayed: true`
3232
3263
  (receipts live beside the instances directory and outlive the home).
3233
- - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
3264
+ - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`. That
3265
+ plan is read once, when the retire holds the home's claim (below): it is
3266
+ the state the retire starts from, and one apply appends one
3267
+ `retire-planned` event. Against a retire in flight or a scheduled
3268
+ self-retire the answer is `E_LIFECYCLE_BUSY` and no plan is read, whatever
3269
+ the plan would read by then: a retire in flight has usually changed it (it
3270
+ stops the session of a launched instance before its hooks run). Before the
3271
+ claim an apply only replays a used key and resolves the home
3272
+ (`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`).
3234
3273
  - The children stopped are those of the revalidated plan, and a refusal
3235
3274
  carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
3236
3275
  - A first guarded retire prints the raw receipt with `planRevision`,
3237
3276
  `idempotencyKey` and `replayed: false`.
3238
3277
 
3278
+ **One retire of a home at a time** (0.51.0, #863). Every retire that applies (plain,
3279
+ guarded, `--self` and its detached completion; with `--server`, on the host)
3280
+ holds the home's claim,
3281
+ `<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
3282
+ has resolved the home until it ends, by success or by any refusal or failure.
3283
+ The claim is a file that names its holder by pid and start time. It lies
3284
+ beside the homes, never inside one: a home's bytes are what its retire
3285
+ observes, copies and removes. A second retire of that home does not wait: it
3286
+ answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
3287
+ message), before it stops a session or a child, writes a recovery, runs a
3288
+ hook or changes a file of the home. **`--force` does not bypass it**, and
3289
+ `--plan` takes no claim and refuses nothing new. A guarded apply answers it
3290
+ before `E_PLAN_STALE`: under the claim the answers come in this order: the
3291
+ home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
3292
+ (`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
3293
+ died, for example a retire killed while its hooks ran, is taken over by the
3294
+ next retire of that name. So a killed retire can always be run again. The
3295
+ claim does not end what the killed retire left running: one of its retire
3296
+ hooks may still be running when the next retire takes the claim over and
3297
+ runs the hooks again (#865). Until
3298
+ that name is retired again its claim file stays where it is, and it is safe
3299
+ to remove once its pid is gone. A retire that ends removes its claim file;
3300
+ the `claims/` directory itself stays, empty.
3301
+
3302
+ `details` is `{instance, home, lock, pid, since}`: `lock` is the file that
3303
+ names the holder, `since` when the holder took it. Every message is one
3304
+ line and says that nothing was done:
3305
+
3306
+ - A live holder: `a retire of <name> is already running (pid <pid>, since
3307
+ <at>); nothing was done — wait for it to finish`.
3308
+ - A holder whose start time cannot be read (where `ps` fails, or a claim
3309
+ that records none) is never taken for gone, and its claim is never taken
3310
+ over. `details.unknown` is the reason. The message names the pid, its
3311
+ recorded start, the reason and the way out: check that pid by hand, and if
3312
+ it is not an `oats retire`, remove `<lock>`, then retry.
3313
+ - A claim file that is not a readable claim is never removed. `details` is
3314
+ `{instance, home, lock}`; the message names the file and says to inspect
3315
+ it and remove it if no `oats retire` holds it.
3316
+ - The retire's own start time cannot be read, so it could not hold the claim
3317
+ verifiably: `details` is `{instance, home, lock}`, and the message gives
3318
+ the reader's own reason (the `/proc` read, or what `ps` answered).
3319
+
3320
+ A scheduled self-retire counts from the moment it is scheduled. Its pending
3321
+ marker (`pendingMarker`) records the completion process as `completionPid`
3322
+ and `completionStart` (`null` when the start could not be read). While that
3323
+ process lives, every other retire of the instance is refused the same way,
3324
+ `--self --keep-dir` included: `a retire of <name> is already scheduled (its
3325
+ completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
3326
+ for it to finish`, with `details.lock` the pending marker, `details.pid` the
3327
+ completion and `details.since` the marker's `requestedAt`. A completion
3328
+ whose start cannot be read is refused as a holder's is (`details.unknown`),
3329
+ the file to remove being the pending marker. A second `--self` answers
3330
+ `alreadyScheduled: true` only while the completion has not started. While
3331
+ the first `--self` is still scheduling, or once the completion holds the
3332
+ claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
3333
+ retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
3334
+ left its outcome at `resultPath` (it failed) or is gone (it died), nor when
3335
+ it names no completion (a marker written before 0.51.0): `oats retire
3336
+ <instance>` then retries the retirement, as before. The completion waits up
3337
+ to 3 s for the retire that scheduled it to release the claim, then takes it
3338
+ as any retire does; one that meets another retire still running is refused,
3339
+ and records that at `resultPath` like any failed completion.
3340
+
3341
+ The home is resolved again once the claim is held. One that another retire
3342
+ removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
3343
+ instance does. If the name is by then the home of another agent, the retire
3344
+ starts over on that home, under that home's claim; after two such changes it
3345
+ answers `E_LIFECYCLE_BUSY` (`the home of <name> changed while its claim was
3346
+ being taken …; nothing was done — retry`, `details: {instance, home, lock}`).
3347
+ A retire of a name that has no home also removes a claim of that name whose
3348
+ holder is gone, left by a retire that was killed after it removed the home.
3349
+
3350
+ The claim orders retires only. `oats instance stop`, `oats session start`
3351
+ and `oats worktree add` do not take it and are not refused by it, and `oats
3352
+ status` does not show a held claim (#866).
3353
+
3239
3354
  Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
3240
3355
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
3241
3356
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
@@ -3244,7 +3359,9 @@ message names the entry or the state that could not be read, or the directory
3244
3359
  Git reads as the top level of a `work/` whose `core.worktree` names another
3245
3360
  one),
3246
3361
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
3247
- `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
3362
+ `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
3363
+ home is running or scheduled, `--force` included: one retire of a home at a
3364
+ time, above; or, feature
3248
3365
  `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3249
3366
  row with `spawnInProgress: true`, `--force` included; or one whose start time
3250
3367
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
@@ -3338,6 +3455,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3338
3455
  `E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
3339
3456
  that target and the way out: stop it, then `oats session restart`, which
3340
3457
  goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
3458
+ - A recorded tmux socket file that is missing while a process works in the
3459
+ home, or the process scan cannot run, is not a stopped server:
3460
+ `E_SESSION_UNKNOWN`, nothing started and no server created at that path
3461
+ ([#624](execution-targets.md#missing-socket)).
3341
3462
  - A lost response does not mean the launch failed: check status before a
3342
3463
  retry. A remote home's saved route names its execution host.
3343
3464
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
@@ -3545,11 +3666,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3545
3666
  ### `oats trigger`
3546
3667
 
3547
3668
  ```text
3548
- oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3669
+ oats trigger list | show <id> | status [<id>] | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3549
3670
  ```
3550
3671
 
3551
3672
  Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3552
- "trigger"`).
3673
+ "trigger"`). A trigger's source is the built-in `github.pull_request` or, with
3674
+ feature `trigger-sources`, `<capability>:<source>`, a source a
3675
+ capability declares ([schedules.md](schedules.md#capability-sources)).
3553
3676
 
3554
3677
  - `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
3555
3678
  `show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
@@ -3561,17 +3684,29 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3561
3684
  - `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
3562
3685
  `local/<id>` or a bare local id.
3563
3686
  - `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
3564
- ready_for_review | labeled | synchronize], labels, base?, poll}`.
3687
+ ready_for_review | labeled | synchronize], labels, base?, poll}`, or for a
3688
+ capability source `{source: "<capability>:<source>", params: {<name>:
3689
+ <string>}, events: [<the source's event names>], poll}`.
3565
3690
  - `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
3566
3691
  yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
3567
- `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`. `teams` are
3692
+ `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`, `{subject}` and
3693
+ `{key}`; a capability source's over `{trigger}`, `{source}`, `{subject}`,
3694
+ `{event}`, `{key}`, `{url}` and `{fields.<name>}`. `teams` are
3568
3695
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3569
3696
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3570
3697
  - `template?`: `{package, version, commit, template}`.
3571
3698
  - `lastRun`: `{at, instance, home, event, number, subject, key}`
3572
3699
  (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3573
- for a run recorded before 0.49.0, its number); `nextDue`: the
3574
- next poll here, `null` before the first.
3700
+ for a run recorded before 0.49.0, its number; a capability source's
3701
+ run has `number: null`); `nextDue`: the next poll here, `null` before
3702
+ the first.
3703
+ - `invalid?`: `{code, message, field?}` when the stored definition no
3704
+ longer validates, as before. A capability source's trigger whose last
3705
+ meaning check failed at a poll carries `invalid: {code, message, field?,
3706
+ at}` instead (`code` `E_TRIGGER_SOURCE` or `E_TRIGGER_INVALID`; `at` when
3707
+ the check ran), until a good poll. `invalid` always means the trigger
3708
+ itself is invalid; an event the source answered badly is an *invalid
3709
+ event* (`invalidEvents`).
3575
3710
  - `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
3576
3711
  runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
3577
3712
  liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
@@ -3582,6 +3717,36 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3582
3717
  `subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
3583
3718
  PR's number, as a string. A record written before 0.49.0 has none, and
3584
3719
  its number is reported.
3720
+ - **A capability source's `status` row** (feature `trigger-sources`) has
3721
+ `repo: null`, `number: null` in `pending[]`, `fired[]` and `live[]`, and
3722
+ adds `source: {capability, name}`, `invalidEvents: [{text, rule}]` (the
3723
+ last good poll's, at most 20; `rule` is `shape`, `unknown-key`, `key`,
3724
+ `subject`, `event`, `url`, `fields` or `duplicate-key`, `text` the first
3725
+ 200 characters of the event's JSON), `skipped: [{subject, why}]` (the last
3726
+ good poll's, at most 100) and, when its last meaning check failed,
3727
+ `invalid: {code, message, field?, at}`. Its `lastPoll` is `{at, ok: true,
3728
+ events, invalidEvents, skipped, filtered}` (counts) or `{at, ok: false,
3729
+ cause, error, source?}`, and `lastError` may carry the same `source`.
3730
+ `cause` is `exit`, `result`, `too-many-events`, `timeout`, `refused` or
3731
+ `resolution`; `source: {code, message?}` is the source's own refusal.
3732
+ `why`, `source.code` and `source.message` are the source's untrusted text,
3733
+ capped (200, 128, 500 characters) with control, separator, bidi,
3734
+ invisible and tag characters replaced by U+FFFD: render them as text,
3735
+ marked as the source's.
3736
+ - **Presence and staleness.** `source`, `invalidEvents` and `skipped` are
3737
+ always present on a capability source's status row. The two lists are
3738
+ `[]` until the trigger's first good poll and hold the last good poll's
3739
+ lists after that. A failed poll (`lastPoll.ok: false`) and a failed
3740
+ meaning check (`invalid`, which leaves `lastPoll` as it was) leave them
3741
+ unchanged, so they can be older than `lastPoll.at`, `lastError.at` and
3742
+ `invalid.at`. The lists are the current source's: changing a trigger's
3743
+ `on.source` empties them and `pending`, and clears `invalid`, `lastPoll`
3744
+ and `lastError` (`fired` stays), in what `status` and `list` answer at
3745
+ once and in the state at the next tick.
3746
+ - **Arrays versus counts.** In `trigger test`'s `source` (`ok: true`) and
3747
+ in `trigger poll`'s answer, `events`, `invalidEvents` and `skipped` are
3748
+ arrays and `filtered` is a count. In `lastPoll` (`ok: true`) and in the
3749
+ tick's `polled` row, all four are counts.
3585
3750
  - `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
3586
3751
  runsHere, reason, detail?, enabledHere}, gh: {ok, account,
3587
3752
  credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
@@ -3596,20 +3761,96 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3596
3761
  purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
3597
3762
  `null` when the soul does not resolve or its name is too long for a
3598
3763
  triggered spawn (that error is then in `problems`).
3764
+ - **`test <id> --run-source` of a capability source's trigger** runs the
3765
+ source (it executes the capability's source command, whatever the host's
3766
+ trust and `runsOn` say, and so only with the flag: see **`--run-source`**
3767
+ below) and answers `{triggerApi, id, ok, placement, gh, repo: null,
3768
+ soul, teams, source, wouldFire, problems, warnings, spawned: false}`, no
3769
+ `pollError`. `gh` is `null` unless the trigger has an `owner` (then as
3770
+ above, for the owner's host). `source` is `{capability, name, ok: true,
3771
+ events, invalidEvents, skipped, filtered}`, `{capability, name, ok: false,
3772
+ filtered: 0, invalid: {code, message, field?, at}, events: [],
3773
+ invalidEvents: [], skipped: []}` when its meaning fails, or `{capability,
3774
+ name, ok: false, filtered: 0, cause, error: {code, message}, source?,
3775
+ events: [], invalidEvents: [], skipped: []}` when the poll fails.
3776
+ Without `--run-source`, `test` answers a trigger whose meaning or
3777
+ resolution fails as above (exit 0, `source.ok: false`: no capability code
3778
+ runs to say so), and a trigger whose meaning holds with
3779
+ `E_TRIGGER_SOURCE_RUN`. `wouldFire` rows are `{key, subject,
3780
+ event, url?, instance, nameCut, held?}`. When the tick would not run the
3781
+ trigger here, `problems` holds `run manually with --run-source; the tick
3782
+ will not run it here: <reason>` (with the placement's detail). `warnings` always holds
3783
+ "this source's credential may not be visible to the host timer: it runs
3784
+ with only PATH and OATS_HOME_DIR set, so keep the source's login in its
3785
+ own store, not in an exported variable".
3786
+ - **`poll <id> --run-source`** (feature `trigger-sources`) runs a capability
3787
+ source's trigger's source once, its meaning checked first, and answers
3788
+ `{triggerApi, id, source: {capability, name}, events: [{key, subject,
3789
+ event, url?, fields}], invalidEvents: [{text, rule}], skipped: [{subject,
3790
+ why}], filtered}`, plus `observation` with `--max-age`. `events` are the
3791
+ valid events the trigger selects, `key` as the source wrote it (stored
3792
+ prefixed `<trigger>:`); `filtered` counts the valid events whose `event`
3793
+ the trigger does not select. It records nothing and spawns nothing, but it
3794
+ executes the capability's source command. A failed poll is `E_TRIGGER_POLL`
3795
+ with `details: {cause, source?}`; a meaning failure is `E_TRIGGER_SOURCE`
3796
+ `{capability, source, pointer?}` or `E_TRIGGER_INVALID {field}`; without
3797
+ the flag it is `E_TRIGGER_SOURCE_RUN`; a `github.pull_request` trigger is
3798
+ `E_BAD_ARGS`, with or without the flag. Without `--max-age` it observes
3799
+ the members live.
3800
+ - **`--run-source`** (feature `trigger-sources`): by hand, `test` and `poll`
3801
+ run a capability source's command only with this switch (it takes no
3802
+ value). It is caller intent, never trust consent: with it they run the
3803
+ source whatever the host's `automations.trust` and the trigger's `runsOn`
3804
+ say, and trust, `runsOn` and `owner` gate the tick exactly as before (the
3805
+ tick passes the flag to its own child). Without it, on a capability
3806
+ source's trigger: `E_TRIGGER_SOURCE_RUN`, `ok: false`, a non-zero exit,
3807
+ `details: {capability, source, flag: "--run-source"}`, and a message
3808
+ naming the command to run again (`oats trigger test|poll <id>
3809
+ --run-source`), and the trigger's `runsOn` when that is another host: it
3810
+ holds only the id, the capability and source names and `runsOn`, never
3811
+ text of the source's. Nothing of the capability has executed and nothing
3812
+ has been written in the deployment, the soul's copy under `agents/` and
3813
+ the capability's directory in the module store included. The
3814
+ order is fixed: a valid definition (`E_TRIGGER_INVALID`), then its meaning
3815
+ and the soul's resolution (`E_TRIGGER_SOURCE`, `E_TRIGGER_INVALID
3816
+ {field}`, `E_TRIGGER_POLL` `cause: "resolution"`), then this gate, then
3817
+ the run. On a `github.pull_request` trigger the flag is accepted and
3818
+ inert: `test` answers byte for byte the same.
3819
+ - **What a `triggerApi: 1` reader sees.** `triggerApi` stays 1. `on.source`
3820
+ is an open string: tell rows apart by it, and gate on `trigger-sources`.
3821
+ The keys above (`source`, `invalidEvents`, `skipped`, a meaning failure's
3822
+ `invalid`, `test`'s `source`) appear only on capability-source rows and
3823
+ are absent, not `null`, on a `github.pull_request` row, whose outputs are
3824
+ exactly as before. On a capability source's rows the PR-only fields are
3825
+ `null` (`repo`, `number`) or absent (`on.repo`, `on.labels`, `on.base`,
3826
+ `wouldFire[].repo`), and `lastPoll` carries the counts above instead of
3827
+ `prs` and `matching`.
3599
3828
  - A triggered instance records `instance.json.trigger`: `{id, key, source,
3600
3829
  repo, number, subject, url, event, headSha, observedAt, eventFile}`
3601
3830
  (`subject` since 0.49.0; `null` when the event had none). Its event file is
3602
3831
  `OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
3603
- event, headSha, labels, observedAt, key}`.
3832
+ event, headSha, labels, observedAt, key}`. For a capability source the
3833
+ record has `repo: null`, `number: null`, `headSha: null` and adds `fields`,
3834
+ and the event file is `{trigger, source, subject, event, key, url?,
3835
+ fields, observedAt}`.
3604
3836
  - `update <id> --description=<text>` (feature `automation-descriptions`)
3605
3837
  changes only a local trigger's description; `--description=` (empty)
3606
3838
  removes it. It sets `updatedAt` and leaves fired and pending events
3607
3839
  untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
3608
3840
  refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
3609
3841
  --description is supported for now"). An older kernel has no `update`.
3842
+ - `add` of a capability source's trigger checks its meaning against the
3843
+ soul's resolution before anything is written (`E_TRIGGER_SOURCE`,
3844
+ `E_TRIGGER_INVALID {field}`, or the soul's own resolution error).
3610
3845
  - Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
3611
- `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_POLL`,
3612
- `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3846
+ `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_SOURCE {capability,
3847
+ source, pointer?}` (a capability source that is undeclared or malformed,
3848
+ whose capability the soul does not compose, or whose command is not a file
3849
+ inside the capability; `pointer` is a JSON pointer into the manifest),
3850
+ `E_TRIGGER_POLL` (`details.cause` and `details.source` for a capability
3851
+ source), `E_TRIGGER_SOURCE_RUN {capability, source, flag}` (`test` or
3852
+ `poll` of a capability source's trigger without `--run-source`: nothing
3853
+ ran, nothing was written), `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3613
3854
  `E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
3614
3855
 
3615
3856
  <a id="automations-shared-rows"></a>
@@ -3681,7 +3922,12 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3681
3922
  `number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
3682
3923
  soul as a tick does, and reports a preview failure or a name that cannot
3683
3924
  fit as `spawn-failed`), `invalid` and
3684
- `not-here`. A workspace schedule's state key is `<member>~<id>`. A failed
3925
+ `not-here`. A capability source's trigger adds `poll-deferred`
3926
+ (`deadline`: its poll could not end by 50 s after the tick started; it
3927
+ goes first next tick), its `polled` carries `events`, `invalidEvents`,
3928
+ `skipped` and `filtered`, `poll-failed` a `cause`, `invalid` a failed
3929
+ meaning check, and its `would-fire` has no `number`, and no `url` when the
3930
+ event has none. A workspace schedule's state key is `<member>~<id>`. A failed
3685
3931
  snapshot refresh is `{workspace, action: "error", error}`.
3686
3932
 
3687
3933
  <a id="the-harness-rename-feature-harness-oats-0270"></a>
package/docs/desktop.md CHANGED
@@ -288,6 +288,19 @@ arguments as written, an operation and its home), its run state and where it
288
288
  comes from. Writing summaries needs OATS 0.43 or later; an older OATS still
289
289
  shows the ones it reports.
290
290
 
291
+ A trigger can take its events from a source a capability declares instead of
292
+ GitHub pull requests (OATS 0.50.0 or later). Its page shows the source and
293
+ what the trigger passes to it, what the source's last poll found or why it
294
+ failed, and which events OATS refused or the source skipped. Text that comes
295
+ from the source, from the trigger's file or from the capability's manifest is
296
+ shown as a quote with a line saying whose it is; it is never a link or a
297
+ button. **Test** on a pull-request trigger reads GitHub and reports what would
298
+ fire. **Test** on such a capability trigger runs the capability's source
299
+ command on this computer, so it first shows what will run and with which
300
+ parameters, and runs it once only when you press **Run test**. Nothing is
301
+ recorded or spawned, and testing does not trust or start a trigger that this
302
+ computer doesn't trust.
303
+
291
304
  The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
292
305
  the schedule to the newly created home, preserving that agent's identity and
293
306
  work. A wake starts that same home if it is stopped, then sends the saved