@awebai/oats 0.70.0 → 0.70.2

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.
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.28.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
12
+ | `oats.framework` | `oats-framework/v1.29.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
13
  | `oats.okf` | `v6.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.47.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
14
+ | `oats.aweb` | `v1.48.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -55,7 +55,7 @@ packages:
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.28.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.29.0`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,9 +78,9 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.28.0
81
+ oats.framework: v1.29.0
82
82
  oats.okf: v6.3.0
83
- oats.aweb: v1.47.0
83
+ oats.aweb: v1.48.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
155
155
  ## `oats package add | remove`
156
156
 
157
157
  ```bash
158
- oats package add oats.aweb v1.47.0 # a catalog version
158
+ oats package add oats.aweb v1.48.0 # a catalog version
159
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
160
160
  oats package remove acme.tools
161
161
  ```
@@ -432,11 +432,11 @@ A soul that names one of the package's capabilities with
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
434
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.3.0", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.28.0", "path": "oats-package" }
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.29.0", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.28.0`
441
- resolves to tag `oats-framework/v1.28.0`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.29.0`
441
+ resolves to tag `oats-framework/v1.29.0`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,70 @@
1
+ # OATS 0.70.1
2
+
3
+ Unreleased
4
+
5
+ A preview on a session provider now asks the provider's own readiness check,
6
+ so it no longer reads clean for a launch the provider then refuses. A
7
+ schedule's save asks the same, with the job's own `yolo`. tmux homes and their
8
+ previews are unchanged.
9
+
10
+ ## Upgrade
11
+
12
+ - **The Desktop and the CLI** can be upgraded in either order.
13
+ - **A scheduled or triggered spawn on a provider that launches only in full
14
+ mode (bb's)** needs `yolo: true` in its definition, or a launch
15
+ configuration that sets it. A job without it is now refused when saved, where
16
+ it used to fail at each run.
17
+
18
+ ## Changed
19
+
20
+ - **A spawn job on a session provider is checked by the provider when it is
21
+ saved.** A spawn's preview now asks a session provider's `check` with the
22
+ launch that is planned, and `oats schedule add`, `update` and `test` ask
23
+ that preview with the job's own launch selection, its `yolo` included
24
+ ([spawn](../schedules.md#kinds)). On a provider that launches only in full
25
+ mode:
26
+ - a job with `yolo: true` is saved and launches, as one whose launch
27
+ configuration sets yolo does (a build with the preview's new check and
28
+ without this change refused the job's own `yolo: true` on `add` and
29
+ `update`, and `oats schedule test` said its soul did not resolve: the
30
+ schedule's preview did not carry it);
31
+ - a job with no `yolo` is refused when saved (`E_SCHEDULE_INVALID`,
32
+ `details.code: "E_BACKEND_SANDBOXED_MODE"`), and `oats schedule test`
33
+ reports it, where it used to fail only at its run. One the
34
+ save did not ask the provider about (its soul was already spawned in
35
+ the deployment, or the provider comes from a member module, which a
36
+ preview does not ask) fails at each run, `launch-failed` with `errorCode:
37
+ "E_BACKEND_SANDBOXED_MODE"`, and leaves no home.
38
+
39
+ ## Fixed
40
+
41
+ - **A preview on a session provider no longer reads clean for a launch the
42
+ provider will refuse.** `oats spawn --preview` of a spawn on a session
43
+ provider read complete, with no problem and no warning, and the spawn was
44
+ then refused by the provider's readiness check and undone (with a provider
45
+ that launches only in full mode and no full-mode choice:
46
+ `E_BACKEND_SANDBOXED_MODE`). A preview now asks the provider's `check` with
47
+ the launch that is planned, as the spawn does before any hook runs
48
+ ([spawn preview](../desktop-cli-api.md), [check](../capabilities.md#check-optional)):
49
+ - a launch the provider would refuse fails the preview with the spawn's own
50
+ code and creates nothing; a provider that cannot be asked is
51
+ `E_BACKEND_NOT_READY`; one that outlasts the preview's budget leaves
52
+ `preflight.status: "timeout"`;
53
+ - `oats launch-config preview --home` of a provider home asks it too, and
54
+ shows a refusal as a failed `backend` item, with `ok: false`;
55
+ - a provider in a member module, which runs only from a spawned home, is
56
+ not asked: the preview says so in `warnings`.
57
+
58
+ For a provider's author: `check` may now be handed a home that does not
59
+ exist yet (a spawn's preview hands its planned path). It must only read,
60
+ and treat an absent home as absent.
61
+
62
+ ## Documentation
63
+
64
+ - **Schedules and triggers on a session provider**
65
+ ([Kinds](../schedules.md#kinds), [Triggers](../schedules.md#triggers)): a
66
+ scheduled or triggered spawn on a provider that launches only in full mode
67
+ needs `yolo: true` in its definition, or a launch configuration that sets
68
+ it; a wake is the input of a provider home's session, and never starts a
69
+ stopped provider home. Tests now cover a wake, a scheduled spawn and a
70
+ triggered spawn on a session provider.
@@ -0,0 +1,93 @@
1
+ # OATS 0.70.2
2
+
3
+ Unreleased
4
+
5
+ A pi agent waiting on a dialog now reads as needing input, and a scheduled
6
+ wake holds until it is answered. The Desktop's Schedules form edits a schedule
7
+ on a session provider. The catalog pins oats.aweb 1.48.0 and oats.framework
8
+ 1.29.0.
9
+
10
+ ## Upgrade
11
+
12
+ - **The Desktop and the CLI** can be upgraded in either order.
13
+ - **The pi bridge** (`@awebai/oats-pi` 0.70.2) reaches each pi folder with
14
+ `oats update`; until then a pi agent's dialog sets no claim.
15
+ - **OATS pins oats.aweb 1.48.0, which needs OATS 0.70.0 or later.** Upgrade
16
+ the CLI to 0.70.0 or later before `oats sync` takes the pin: an older kernel
17
+ refuses the package. Running instances keep the module they were spawned
18
+ with: respawn them, or move a stopped one with `oats instance upgrade`, to
19
+ take 1.48.0.
20
+
21
+ ## Added
22
+
23
+ - **A pi agent's question raises needs-input, in every pi home.** Nothing set a
24
+ claim when a pi instance waited on a dialog, so it read as running while it
25
+ waited for a person, and a scheduled wake's Enter answered the dialog. The pi
26
+ bridge (`@awebai/oats-pi`) now holds a waiting claim of producer `oats.pi`,
27
+ reason `question`, for as long as a dialog an extension opened is open (a
28
+ question tool's `select`, `confirm`, `input`, `editor` or custom screen),
29
+ with the dialog's title as its message. `oats status`, `oats session inspect`
30
+ and the Desktop show the instance as needing input, with the question, and a
31
+ scheduled wake holds until the dialog is answered
32
+ ([A held wake](../schedules.md#a-held-wake)). The claim clears when the
33
+ dialog closes and when the session ends with it open. It reaches every pi
34
+ home, a pi in a tmux pane and one a session provider runs in RPC mode alike,
35
+ on pi 0.84.4 and later, and needs the bridge updated in each pi folder
36
+ ([upgrading](../upgrading.md)). No key or event is new: the claim is the one
37
+ a failed turn already uses, and an open dialog is shown over a failed turn
38
+ ([A pi dialog](../capabilities.md#oatscore-needs-input)).
39
+ - **The bridge clears only its own claim.** It records a mark while its claim
40
+ stands, `<home>/.pi/oats-pi-claim.json`, naming the pi process that set it,
41
+ and tells its claim by that mark, never by the claim's reason. A second pi
42
+ in the home (a nested one, a subagent's session) no longer clears a live
43
+ pi's claim at its first run, and never replaces its question. No other
44
+ producer's claim is touched.
45
+ - **A pi that died with its dialog open.** Its question is cleared when the
46
+ home's next pi starts. With no pi to start it stays and holds the home's
47
+ scheduled wakes, on a session provider until it is cleared: `oats instance
48
+ waiting clear --producer oats.pi --home <home>`.
49
+ - **What it does not cover.** A pi home's `wakeHold` still reads `unknown`:
50
+ the kernel can't see whether the bridge is loaded, and a screen of pi's own
51
+ (its project trust prompt, a picker a person opened) has no claim.
52
+
53
+ - **Desktop: the Schedules form edits a schedule that launches on a session
54
+ provider.** A new-agent schedule's **Session backend** now offers tmux and
55
+ each session provider the chosen soul's capabilities supply (bb, where the
56
+ soul has it), and **Edit** opens a schedule stored on one instead of sending
57
+ you to the CLI; a save keeps the backend
58
+ ([Scheduling agents and wake messages](../desktop.md#scheduling-agents-and-wake-messages)).
59
+ - bb launches only in full mode: choosing it sets permissions to YOLO and
60
+ the form says why. A schedule saved without it (with the CLI, say) is
61
+ marked **Refused at each run** (`yolo: false`) or **Needs YOLO** (no
62
+ `yolo`: refused unless its launch configuration sets it) in the list and
63
+ on its page.
64
+ - A wake to an agent on a session provider is edited as any wake. The form
65
+ says it is sent as the session's input and never starts a stopped agent
66
+ there.
67
+ - An Edit that is still reading the soul's session backends is dropped by
68
+ anything else that happens to the list meanwhile (a switch, a run, a
69
+ Delete, a refresh, another workspace), so a late answer never brings back
70
+ a form holding the old definition.
71
+
72
+ ## Changed
73
+
74
+ - **OATS pins oats.aweb 1.48.0** (from 1.47.0). The package's requirements
75
+ follow the session backend: the channel packages (`aweb-channel`,
76
+ `@awebai/pi`) are required of `tmux` launches only, and a session provider's
77
+ launch requires an installed `aweb-channel` to be 1.7.9 or later, and an
78
+ installed `@awebai/pi` 0.3.10 or later, so no older package opens its own mail stream beside
79
+ the wake broker's. A retire removes a provider home's broker registration
80
+ when either record names a session provider. Homes on tmux behave as before.
81
+
82
+ - **oats.framework 1.29.0** (`oats.core` 2.16.1, `oats.knowledge-theory`
83
+ 1.1.4).
84
+ - `oats.core`'s `/oats-operate` says a pi home's extension dialogs raise
85
+ needs-input, and that the claim holds a scheduled wake while one is open,
86
+ from `@awebai/oats-pi` 0.70.2 (#2071). A pi home's `wakeHold` still reads
87
+ `unknown`: a screen of pi's own has no claim.
88
+ - `oats.knowledge-theory`'s capability-authoring reference shows the
89
+ `oats.framework` v1.28.0 pin in its example (it showed v1.27.0).
90
+ - The catalog pins oats.framework 1.29.0.
91
+ - Guidance text only. Nothing changes for a deployment beyond `oats sync`
92
+ taking the new tag; existing homes take the new skills through
93
+ `oats instance upgrade` or a new spawn.
package/docs/schedules.md CHANGED
@@ -171,11 +171,13 @@ refuses the key on a trigger.
171
171
  package soul the workspace offers, see `oats souls`), whether or not this
172
172
  deployment has spawned it before. `add` and `update` refuse a job whose
173
173
  `oats spawn <agent> --preview`, with the job's `launchConfig`, `harness`,
174
- `model`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
174
+ `model`, `yolo`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
175
175
  with spawn's own message and its code in `details.code`), or whose preview
176
176
  answer cannot be confirmed; a soul this deployment has already spawned is
177
177
  accepted without the preview. `agentsRoot`, when given, must be the deployment's `agents/` root; `repo`
178
- is the work repository, as `--repo`. `backend` is `tmux`; `backend: herdr`
178
+ is the work repository, as `--repo`. `backend` is `tmux`, or the name of a
179
+ [session provider](execution-targets.md#session-providers) of the soul's
180
+ capabilities; `backend: herdr`
179
181
  is refused (`E_HERDR_REMOVED`, naming the file and key: Herdr was removed in
180
182
  0.31.0), and a stored job that names it is reported invalid and never runs.
181
183
  `model` is a model id (a letter or
@@ -189,6 +191,23 @@ refuses the key on a trigger.
189
191
  trailing block naming the job and the minute and ending with `oats retire
190
192
  --self`. `wake` (`{cron, tz, message}`) attaches a wake schedule to each
191
193
  launched instance.
194
+
195
+ **On a session provider** the run's spawn launches through the provider
196
+ `backend` names. A provider that launches only in full mode (bb's does)
197
+ refuses every other launch at its
198
+ [check](capabilities.md#check-optional), `E_BACKEND_SANDBOXED_MODE`. A job
199
+ on such a provider needs `yolo: true` in its definition, or a launch
200
+ configuration that sets it: the job's `launchConfig`, or the deployment's
201
+ [default for the harness](configuration.md#the-harness-default). Without
202
+ it `add` and `update` refuse the job where they ask the preview
203
+ (`E_SCHEDULE_INVALID`, with `details.code: "E_BACKEND_SANDBOXED_MODE"`),
204
+ and `oats schedule test` reports it. A job the save did not ask the
205
+ provider about (its soul was already spawned here, so `add` and `update`
206
+ ask no preview; or the provider comes from a member module, which a
207
+ preview does not ask) fails at each run: the run is recorded
208
+ `launch-failed` with `errorCode: "E_BACKEND_SANDBOXED_MODE"` and the
209
+ provider's message, its spawn is undone and no home is left; the job tries
210
+ again at its next due minute.
192
211
  - **command** `{…, cwd, argv}` — runs an oats-only argv (`argv[0]` is `oats`,
193
212
  no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
194
213
  inside the deployment. The runner tracks any instance the command's
@@ -221,6 +240,21 @@ refuses the key on a trigger.
221
240
  again only at due minutes, so a harness that keeps exiting is not restarted
222
241
  in a loop. Unobservable or still starting: skipped, delivery kept pending.
223
242
  Word wake messages so that receiving one again is harmless.
243
+
244
+ A home on a [session provider](execution-targets.md#session-providers) has
245
+ no terminal: the message is its session's input, sent once through the
246
+ provider, and a live claim holds it the same way. **A wake never starts a
247
+ provider home OATS stopped.** Its input is refused before any provider
248
+ call: the run is `skipped` with `errorCode: "E_SESSION_NOT_RUNNING"`, and
249
+ the delivery stays pending until the home is started (`oats session
250
+ start`). To a session that is lost (gone, and not stopped by OATS) the
251
+ input is a resume, on which the provider restarts the session, counted
252
+ against the home's cap
253
+ ([lost sessions](execution-targets.md#session-providers)). An input the provider itself refuses
254
+ (`E_SESSION_PROMPT_OPEN` while its session shows a prompt,
255
+ `E_SESSION_INPUT_QUEUED`) is `skipped` with that `errorCode`: nothing was
256
+ sent, and the pending delivery is tried again at every tick, then delivered
257
+ once.
224
258
  - **operation** `{…, operation, home}` — runs a provider operation
225
259
  (`<layer>:<name>`, one the capability filling that layer declares) in the
226
260
  instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
@@ -299,7 +333,12 @@ when the timer cannot reach it.
299
333
  request's title and body are untrusted and never reach the task. `teams` (optional) becomes the messaging capability's `join=`
300
334
  setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
301
335
  `launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
302
- schedules.
336
+ schedules. On a session provider that launches only in full mode (bb's
337
+ does) the spawn needs `yolo: true`, or a launch configuration that sets
338
+ it, as [a schedule's spawn](#kinds) does. Without it each event's spawn
339
+ fails (`spawn-failed`, `E_BACKEND_SANDBOXED_MODE`, kept as the trigger's
340
+ `lastError`), no home is created, and the event stays pending and is tried
341
+ again at each poll.
303
342
  - **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
304
343
  the slug of the soul's agent name (a package soul's is
305
344
  `<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
@@ -1092,8 +1131,11 @@ A hold reads claims, so it can only be as good as they are. `on-claims` says no
1092
1131
  more than that:
1093
1132
 
1094
1133
  - **Harnesses with no claims stay exposed.** No claim is ever written there, so
1095
- every wake types. pi homes read `unknown`: an extension can open its own
1096
- dialog, and the kernel can't see which load.
1134
+ every wake types. pi homes read `unknown`. A dialog an extension opens there
1135
+ holds a wake, through the pi bridge's `question` claim
1136
+ ([A pi dialog](capabilities.md#oatscore-needs-input), `@awebai/oats-pi` after
1137
+ 0.70.1 on pi 0.84.4 or later), but the kernel can't see whether that bridge is
1138
+ loaded, and a screen of pi's own fires no event.
1097
1139
  - **A dialog that opens before the Enter is still answered.** That covers one that
1098
1140
  opens between the read and the Enter, and the lag between a dialog opening and
1099
1141
  its claim being written. A claim lands after its dialog: a `permission` claim
package/docs/upgrading.md CHANGED
@@ -6,12 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.70.0** ([release notes](release-notes/v0.70.0.md)).
10
- The 0.70.0 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
9
+ The latest version is **OATS 0.70.2** ([release notes](release-notes/v0.70.2.md)).
10
+ The 0.70.2 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
11
11
  Desktop and the CLI can be upgraded [in either order](#either-order-works).
12
12
 
13
13
  **First, read the `## Upgrade` section of every release after yours, up to
14
- 0.70.0,** in the [release notes](release-notes/): it says what to do before
14
+ 0.70.2,** in the [release notes](release-notes/): it says what to do before
15
15
  the CLI changes, and what else must change with it (the Desktop, another
16
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
17
17
  names the releases that ask for more than the steps below. `oats version`
@@ -20,8 +20,8 @@ prints the version you have.
20
20
  Then, on each host:
21
21
 
22
22
  ```sh
23
- # 0. where the Desktop is installed: Desktop 0.70.0, in either order
24
- npm install -g @awebai/oats@0.70.0 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.70.2, in either order
24
+ npm install -g @awebai/oats@0.70.2 # 1. the CLI
25
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
26
26
  oats doctor # 3. in the same deployment
27
27
  ```
@@ -217,6 +217,14 @@ of the Desktop and the CLI, and an optional package pin. A change a script
217
217
  must follow is in its release's Upgrade section whether or not it is listed
218
218
  here.
219
219
 
220
+ - **[0.70.2](release-notes/v0.70.2.md#upgrade):** the catalog pins
221
+ oats.aweb 1.48.0, which needs OATS 0.70.0 or later, and oats.framework
222
+ 1.29.0: upgrade the CLI before `oats sync`, and respawn or move instances
223
+ with `oats instance upgrade` to take them.
224
+ - **[0.70.1](release-notes/v0.70.1.md#upgrade):** a scheduled or triggered
225
+ spawn on a provider that launches only in full mode (bb's) needs `yolo:
226
+ true`, or a launch configuration that sets it; a job without it is now
227
+ refused when saved.
220
228
  - **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
221
229
  the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
222
230
  reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.28.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.29.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v6.3.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
package/lib/core.mjs CHANGED
@@ -66,10 +66,43 @@ import { assertNoPartialUpgrade, packageRespawnWarning, packageUpgradeDrift, upg
66
66
  import { refuseHomeOfAnotherUser } from "./home-owner.mjs";
67
67
  import { oatsError, afterEndedSteps, afterFirstEffect, asKernelError, BEFORE_EFFECT_CODES, checkHolderByHand, errorCause, ifItDoesNotEnd, isAnswerCode, isDefect, isKernelCode, kernelCode, lifecycleBusy, nothingAfter, reportDefect, OWN_NAME_FAILURES, OWN_START_REMEDY, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
68
68
  import { envRows, recordedTeams } from "./teams.mjs";
69
+ import { safeText } from "./refused-text.mjs";
69
70
  import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigAmbiguous, launchConfigUnknown, launchConfigUnknownFix, launchLayers, launchPreferenceUnmatched, launchPreferenceUnmatchedProblem, launchReport, selectionFrom } from "./launch-preference.mjs";
70
71
  import { shq, shellWord } from "./shell-word.mjs";
71
72
  import { CONFIG_DIR_VAR, HARNESS_FOLDER_VAR, claudeTrusts, codexTrustsRoot, harnessConfigFile, harnessTrustWarning, launchConfigFolder } from "./harness-trust.mjs";
72
73
  async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
74
+ /** What a home's record says of the workspace and the teams, from the prepared resolution: the
75
+ * final record's, the spawn-in-progress marker's, and a preview's question to a session provider. */
76
+ const workspaceRecordOf = (prepared) => (prepared ? {
77
+ workspace: { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, resolution: prepared.resolution.revision, standalone: prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(prepared.soulEntry), repoKey: prepared.soulEntry.repoKey, commit: prepared.soulEntry.commit, ...(typeof prepared.soulEntry.package === "string" ? { name: prepared.soulEntry.name, qualifiedName: prepared.soulEntry.qualifiedName, package: { id: prepared.soulEntry.package, version: prepared.soulEntry.version, commit: prepared.soulEntry.commit, digest: prepared.soulEntry.digest, path: prepared.soulEntry.path } } : {}) }, layers: layerRows(prepared.resolution) },
78
+ teams: envRows(prepared.resolution.teams ?? []),
79
+ defaultTeam: structuredClone(prepared.resolution.defaultTeam ?? null),
80
+ } : {});
81
+ /** The soul directory a home records and its hooks and provider calls are handed (OATS_SOUL): for
82
+ * a workspace soul its commit's directory in the per-commit cache, by real path, never the
83
+ * swappable `agents/<name>/soul` pointer; else what that pointer shows now; else `soulDir`.
84
+ * `planned` (a spawn's preview, which may have read the soul from a temporary copy): the
85
+ * per-commit directory the apply will record, though it is not fetched there yet. */
86
+ function homeSoulTargetOf(agent, prepared, soulDir, { planned = false } = {}) {
87
+ if (prepared?.soulEntry?.commit) {
88
+ const perCommit = join(agent._dir, "souls", String(prepared.soulEntry.commit).slice(0, 12));
89
+ if (existsSync(join(perCommit, "soul.yaml"))) return realpathSync(perCommit);
90
+ if (planned) return realPathOrNearest(perCommit);
91
+ }
92
+ // Not prepared (or the cache entry is absent): still never link a swappable pointer —
93
+ // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
94
+ try {
95
+ if (lstatSync(soulDir).isSymbolicLink()) {
96
+ const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
97
+ const rel = relative(soulsReal, real);
98
+ if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) return real;
99
+ }
100
+ } catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
101
+ return soulDir;
102
+ }
103
+ /** The verified tree of a package module in the deployment's module store (lib/operator-dispatch.mjs
104
+ * ensureModuleTree), for a spawn preview's question to a session provider: no home holds it yet. */
105
+ async function providerTreeDefault(prepared, module) { const m = await import("./operator-dispatch.mjs"); return m.ensureModuleTree(prepared.deployment, module, prepared.lock, { remoteOptions: prepared.remoteOptions }); }
73
106
  async function plannedSkillsDefault(prepared) { const m = await import("./instance-resolution.mjs"); return m.plannedPreparedSkills(prepared); }
74
107
  // Capability rows for a PREPARED spawn (workspace model): the one function that
75
108
  // turns a Resolution's modules into the row shape hooks/environment/requirements/
@@ -3140,9 +3173,11 @@ function requirementsWithArgsMessage(harness, providers, config, backend = "tmux
3140
3173
  * expected to have (paneEnvironment's shape, or a function giving it, called only when a check
3141
3174
  * needs a name the launch itself does not set); every check here reads it through the one answer
3142
3175
  * (launchEnvironment), and says so when it is not established. */
3143
- export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane }) {
3176
+ export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane, providerCheck = null }) {
3144
3177
  assertRoots?.();
3145
3178
  const problems = [];
3179
+ // (The home's session provider as it is bound below, for the preview's question to it.)
3180
+ let providerBound = null;
3146
3181
  const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
3147
3182
  // A recorded recipe is validated before anything is observed. A home without
3148
3183
  // one predates recipes: there is nothing this kernel plans from.
@@ -3186,7 +3221,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
3186
3221
  // The provider's own rules for this launch: the harness is one it runs, and no executable is named.
3187
3222
  // The home's modules as they are now, under the spawn's own selection: one name has one
3188
3223
  // meaning (E_BACKEND_AMBIGUOUS), and the harness is one the provider runs (E_BACKEND_HARNESS).
3189
- const bound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
3224
+ const bound = providerBound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
3190
3225
  let refusal = null;
3191
3226
  if (!bound.problem) { try { selectSessionBackend(sessionProvider.backend, Object.values(capabilityManifests(home)).map((m) => ({ id: m.capability, manifest: m })), harness, "nothing was stopped or started"); } catch (e) { if (!isKernelCode(e?.code)) throw e; refusal = e; } }
3192
3227
  if (bound.problem) fail("backend", "E_SESSION_START_FAILED", `${meta?.instance || instance || basename(home)} cannot be launched on session backend ${sessionProvider.backend}: ${bound.problem}; nothing was stopped or started`);
@@ -3293,9 +3328,35 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
3293
3328
  const { trustHome } = sessionProvider ? { trustHome: false } : launchFolderTrust({ harness, home, meta, yolo: recipe.yolo, launch: trustLaunch, env, configEnv, launchConfig: config?.name });
3294
3329
  const command = sessionProvider ? undefined : renderLaunchRecipe(recipe, { home, instance: instance || meta?.instance || basename(home), trustHome });
3295
3330
  const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
3331
+ // A preview of a launch on a session provider asks the provider what the start will ask it
3332
+ // (startProviderSession's askCheck): its `check`, with the launch that is planned, so a launch the
3333
+ // provider would refuse reads refused here and not ready. `check` only reads. `providerCheck`:
3334
+ // `{ sandboxSource }`, the caller's reading of the deployment's configuration (as a start's), from
3335
+ // the command that previews a launch; never from the start's own preview pass, which asks once
3336
+ // itself. Nothing is created: the allowances' paths are not made, nor the kernel's directory.
3337
+ const providerWarnings = [];
3338
+ if (preview && providerCheck && sessionProvider && providerBound?.binding && problems.every((c) => c.ok)) {
3339
+ try {
3340
+ const source = providerCheck.sandboxSource;
3341
+ let sandbox = { unavailable: source?.unavailable ?? "this preview did not resolve the deployment's configuration" };
3342
+ if (source && !source.unavailable) {
3343
+ const allowed = homeSandboxAllowances({ source, home: canonicalHomePath(home), moduleNames: Object.keys(isPlainObject(meta?.modules) ? meta.modules : {}) });
3344
+ for (const { capability, reason } of allowed.skipped ?? []) providerWarnings.push(`sandbox allowances: ${capability} adds no host: ${reason}`);
3345
+ sandbox = sandboxLaunchInput(allowed);
3346
+ // What the start refuses of the paths it would make (E_BACKEND_SANDBOX_HOST): refused here, with nothing made.
3347
+ const refused = sandboxWritePathsRefusal(sandbox.write);
3348
+ if (refused) throw refused;
3349
+ }
3350
+ const notReady = launchReadinessRefusal(providerBound.binding, { launch: plannedLaunch({ home: canonicalHomePath(home), harness, yolo: recipe.yolo, args: recipe.args, sandbox, preview: true }) });
3351
+ if (notReady) problems.push({ check: "backend", ok: false, detail: notReady.message, code: notReady.code });
3352
+ } catch (e) {
3353
+ if (!isKernelCode(e?.code)) throw e;
3354
+ problems.push({ check: "backend", ok: false, detail: e.message, code: e.code });
3355
+ }
3356
+ }
3296
3357
  // A preview states what the start will do; the start states it in its own output.
3297
3358
  const previewNotices = preview && !sessionProvider ? launchStartNotices(dirname(dirname(dirname(dirname(home)))), harness, command) : [];
3298
- return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
3359
+ return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices, ...providerWarnings], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
3299
3360
  }
3300
3361
  /** The names a package probe of `harness` depends on: where its program is found and runs, the
3301
3362
  * home directory, and that harness's own selector. */
@@ -3408,10 +3469,11 @@ function homeTrees(home) {
3408
3469
  * home's modules (lib/home-integrity.mjs: what the kernel runs, and where the home's hooks point
3409
3470
  * the harness), the receipts, the claims and the provider calls in flight. Each is made here
3410
3471
  * when it is missing (a deployment's first home), so that a provider that refuses a launch for
3411
- * a missing one refuses a fault and never a first launch. Never derived from the home's record. */
3412
- function homeProtected(home) {
3472
+ * a missing one refuses a fault and never a first launch. Never derived from the home's record.
3473
+ * `create: false`: a preview's, which names the same directory and makes nothing. */
3474
+ function homeProtected(home, { create = true } = {}) {
3413
3475
  const paths = [instancesRetirementRoot(dirname(canonicalHomePath(home)))];
3414
- for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
3476
+ if (create) for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
3415
3477
  return paths;
3416
3478
  }
3417
3479
  function providerLaunchInput({ home, instance, recipe, env: hostEnv, removed = [], previous = null, sandbox }) {
@@ -3462,8 +3524,12 @@ const capabilityRuntimeRows = (resolvedCfg) => resolvedCfg.capabilities.map((cap
3462
3524
  * `{ harness, yolo, args, sandbox, trees, protected }`. `args` are the launch configuration's own: the
3463
3525
  * arguments a capability's hooks contribute are not known yet, and reach the launch input only.
3464
3526
  * `trees` and `protected` are the launch input's (homeTrees, homeProtected): a provider that
3465
- * would refuse a launch for either refuses it here, before a restart stops anything. */
3466
- const plannedLaunch = ({ home, harness, yolo, args, sandbox }) => ({ harness, yolo: yolo ?? null, args: [...(args || [])], ...(sandbox ? { sandbox } : {}), trees: homeTrees(home), protected: homeProtected(home) });
3527
+ * would refuse a launch for either refuses it here, before a restart stops anything.
3528
+ * `preview`: asked by a command that creates nothing (a spawn's preview, whose home does not
3529
+ * exist yet; a launch's): the same paths, with nothing made, and for a home that is not there
3530
+ * the one tree every home has. */
3531
+ const plannedLaunch = ({ home, harness, yolo, args, sandbox, preview = false }) => ({ harness, yolo: yolo ?? null, args: [...(args || [])], ...(sandbox ? { sandbox } : {}),
3532
+ trees: preview && !existsSync(home) ? [join(home, "work")] : homeTrees(home), protected: homeProtected(home, { create: !preview }) });
3467
3533
  /** A home's independent session receipt, read to be written again with another `runtime` → `{ path,
3468
3534
  * baseline }`. Refused as every writer of it refuses: E_RUNTIME_ENDPOINT_UNKNOWN for a receipt that
3469
3535
  * is missing, unreadable, of another home, or that authorises nothing. */
@@ -3774,7 +3840,7 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
3774
3840
  const it = spawnBody(root, agent, o);
3775
3841
  let step = it.next();
3776
3842
  while (!step.done) {
3777
- // The single yield hands back a promise-producing thunk; await it and feed the
3843
+ // Each yield hands back a promise-producing thunk; await it and feed the
3778
3844
  // result (or throw the failure) back into the body.
3779
3845
  try { const value = await step.value(); step = it.next(value); }
3780
3846
  catch (e) { step = it.throw(e); }
@@ -4354,6 +4420,44 @@ function* spawnBody(root, agent, o = {}) {
4354
4420
  if (suggesting) paneCwd = home;
4355
4421
 
4356
4422
  if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
4423
+ // A preview of a spawn on a session provider asks the provider what the apply will ask it before
4424
+ // any hook runs (below, `refusedBeforeHooks`): its `check`, with the launch that is planned. A
4425
+ // launch the provider would refuse fails the preview with the apply's own code, as every other
4426
+ // refusal of a backend does; nothing is created. `check` only reads.
4427
+ // - The home does not exist yet: the check is handed its planned path, and the kernel's
4428
+ // directory (`protected`) by name, not made.
4429
+ // - The provider's script runs from its package's verified tree in the deployment's module
4430
+ // store (as `oats readiness --soul` runs it), fetched there when it is absent. A provider in
4431
+ // a member module runs only from a spawned home: the preview says it was not asked.
4432
+ // - It runs within what is left of the preview's one budget; a provider that does not answer
4433
+ // in it leaves the preflight a `timeout`.
4434
+ // A provider that declares no check has nothing to be asked, here as at the apply.
4435
+ let previewCheckWarning = null;
4436
+ if (o.preview === true && launch && provider && provider.provider?.commands?.check) {
4437
+ const said = `${provider.capability}'s session provider ${backend}`, notAsked = (why) => `${said} was not asked whether it can take this launch (${why}): the spawn asks it before any hook runs, and refuses what it refuses`;
4438
+ const module = (o.prepared.resolution?.modules || []).find((m) => m.name === provider.capability);
4439
+ let dir = null, unread = null;
4440
+ if (module?.from?.kind === "package") { try { dir = yield () => (o.providerTree ?? providerTreeDefault)(o.prepared, module); } catch (e) { unread = safeText(e?.message ?? e, 300); } }
4441
+ const left = preflightStarted + preflightBudgetMs - Date.now();
4442
+ if (module?.from?.kind !== "package") previewCheckWarning = notAsked("a provider in a member module runs only from a spawned home");
4443
+ else if (!dir) previewCheckWarning = notAsked(`its package's tree could not be read${unread ? `: ${unread}` : ""}`);
4444
+ else if (left <= 0) preflight.status = "timeout";
4445
+ else {
4446
+ const rows = capabilityRuntimeRows(resolvedCfg), row = rows.find((c) => c.id === provider.capability);
4447
+ // The provider's environment is the apply's: the soul directory the home will record (not a
4448
+ // preview's temporary copy of the soul), and the capability's level, which is the home.
4449
+ const planned = { agent: agent.name, instance, home, soulDir: homeSoulTargetOf(agent, o.prepared, soulDir, { planned: true }), harness, capabilityRuntime: rows, ...workspaceRecordOf(o.prepared) };
4450
+ const binding = { home, meta: planned, capability: provider.capability, name: backend, provider: provider.provider, moduleDir: dir, digest: null, soulId: preparedSoulIdOf(o.prepared.soulEntry),
4451
+ cap: { id: provider.capability, layer: row?.layer ?? "", level: row?.level ?? home, settings: isPlainObject(row?.settings) ? row.settings : {}, settingsOrigins: isPlainObject(row?.settingsOrigins) ? row.settingsOrigins : {} } };
4452
+ // (Never longer than the apply gives it: a check slower than its own limit is refused there.)
4453
+ const own = sessionProviderTimeout("check");
4454
+ const notReady = launchReadinessRefusal(binding, { timeoutMs: Math.min(left, own), launch: plannedLaunch({ home, harness, yolo, args: launchConfig?.args, sandbox: sandboxLaunchInput(sandbox), preview: true }) });
4455
+ // Ended by the budget: the preflight did not finish. Ended by its own limit: the apply's refusal.
4456
+ if (notReady?.timedOut && left <= own) preflight.status = "timeout";
4457
+ else if (notReady) throw Object.assign(oatsError(notReady.code, `${instance} would not be launched: ${notReady.message}; nothing was created`), { details: { backend, capability: provider.capability } });
4458
+ }
4459
+ preflight.elapsedMs = Date.now() - preflightStarted;
4460
+ }
4357
4461
  // K6: everything a spawn decides is decided by here — and nothing has been
4358
4462
  // touched. Branch/base for a worktree are named now (not after mkdir) so the
4359
4463
  // preview and the apply agree on them; `o.baseRef` selects the start point.
@@ -4425,7 +4529,7 @@ function* spawnBody(root, agent, o = {}) {
4425
4529
  const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
4426
4530
  // The preview's warnings are strings: the launchPromptAnswers notice, then what a module declares and this kernel ignores.
4427
4531
  // The development-channel statement is the apply's: no launch hook runs here, so the argv is unknown.
4428
- const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning()].filter(Boolean)];
4532
+ const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning(), previewCheckWarning].filter(Boolean)];
4429
4533
  const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
4430
4534
  return deliver({
4431
4535
  // Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
@@ -4606,22 +4710,7 @@ function* spawnBody(root, agent, o = {}) {
4606
4710
  // including a preview's). The record names ITS commit's directory by realpath — never
4607
4711
  // the pointer — so a later fetch can move "current" without changing what a running
4608
4712
  // instance's hooks see (decision 7); the OKF hook's owner pin stays valid.
4609
- let homeSoulTarget = soulDir;
4610
- if (o.prepared?.soulEntry?.commit) {
4611
- const perCommit = join(agent._dir, "souls", String(o.prepared.soulEntry.commit).slice(0, 12));
4612
- if (existsSync(join(perCommit, "soul.yaml"))) homeSoulTarget = realpathSync(perCommit);
4613
- }
4614
- if (homeSoulTarget === soulDir) {
4615
- // Not prepared (or the cache entry is absent): still never link a swappable pointer —
4616
- // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
4617
- try {
4618
- if (lstatSync(soulDir).isSymbolicLink()) {
4619
- const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
4620
- const rel = relative(soulsReal, real);
4621
- if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) homeSoulTarget = real;
4622
- }
4623
- } catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
4624
- }
4713
+ const homeSoulTarget = homeSoulTargetOf(agent, o.prepared, soulDir);
4625
4714
  if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
4626
4715
 
4627
4716
  // Skills: module skills were copied WHOLE and FLAT into <home>/.agents/skills/<skill>/
@@ -4837,11 +4926,7 @@ function* spawnBody(root, agent, o = {}) {
4837
4926
  // rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
4838
4927
  // capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
4839
4928
  // what they fall back to when the workspace cannot answer.
4840
- const workspaceRecord = o.prepared ? {
4841
- workspace: { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) },
4842
- teams: envRows(o.prepared.resolution.teams ?? []),
4843
- defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null),
4844
- } : {};
4929
+ const workspaceRecord = workspaceRecordOf(o.prepared);
4845
4930
  // #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
4846
4931
  // in-progress marker that covers a parent killed while its spawn or worktree hooks run.
4847
4932
  const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];