@awebai/oats 0.43.3 → 0.44.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.
Files changed (32) hide show
  1. package/bin/oats.mjs +98 -27
  2. package/docs/capabilities.md +7 -1
  3. package/docs/configuration.md +65 -0
  4. package/docs/desktop-cli-api.md +149 -4
  5. package/docs/execution-targets.md +75 -0
  6. package/docs/implementation.md +14 -1
  7. package/docs/oats-local.schema.json +19 -1
  8. package/docs/oats-workspace.schema.json +1 -1
  9. package/docs/release-notes/v0.44.0.md +161 -0
  10. package/docs/schedules.md +27 -9
  11. package/docs/souls-and-instances.md +7 -0
  12. package/lib/core.mjs +253 -87
  13. package/lib/instance-events.mjs +1 -1
  14. package/lib/instance-inspect.mjs +39 -6
  15. package/lib/launch-prompt-fixtures/README.md +49 -0
  16. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
  17. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
  18. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
  19. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
  20. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
  21. package/lib/launch-prompt-fixtures.mjs +114 -0
  22. package/lib/launch-prompt-policy.mjs +73 -0
  23. package/lib/launch-prompt-transport.mjs +102 -0
  24. package/lib/launch-prompts.mjs +216 -0
  25. package/lib/operator-coverage.mjs +134 -0
  26. package/lib/remote.mjs +15 -9
  27. package/lib/schedule.mjs +57 -10
  28. package/lib/teams-verbs.mjs +3 -3
  29. package/lib/triggers.mjs +2 -2
  30. package/lib/workspace.mjs +20 -2
  31. package/package.json +1 -1
  32. package/skills/oats-getting-started/SKILL.md +15 -0
@@ -578,6 +578,81 @@ its children, waits `--stop-grace <seconds>` (default 20, at most 300), then
578
578
  starts in place. It never escalates: a harness still running is reported
579
579
  (`E_SESSION_STOP_FAILED`) and nothing is launched.
580
580
 
581
+ ### Launch prompt outcomes
582
+
583
+ For a home with [explicit host-local consent](configuration.md#exact-home-launch-prompt-consent),
584
+ spawn, start and restart can observe only the process created by that invocation.
585
+ A new window supplies the exact pane identity. Reusing a pane requires a changed
586
+ numeric process ID and fresh visible bytes differing from the pre-respawn
587
+ screen. An already-running process, stale screen or scrollback grants no input
588
+ authority. Home, socket, pane, PID, geometry and exact visible signature are
589
+ rechecked before each key.
590
+
591
+ Observation is bounded to 30 seconds with 100 ms intervals. Only accepted
592
+ version/platform-specific startup and prompt frames keep authority open;
593
+ unexpected output permanently closes it. Only the exact aweb development-channel
594
+ confirmation can be answered, once, with one Enter. Folder-trust and API-key
595
+ prompts are unexpected and block; no multi-prompt sequence is authorized.
596
+ For a qualified launch, the controller saves the exclusively owned window's
597
+ size policy and dimensions, temporarily pins it to the fixture's 110x35
598
+ geometry, and confirms the size before matching. It audits restoration on
599
+ every exit, including timeout and failure; a replaced process/window is never
600
+ resized during cleanup. Pinning a reused pane cannot establish freshness: that
601
+ must already be proved at its original geometry. The selected-option frame
602
+ is rechecked before Enter. Uncertain submission is never retried. Only the
603
+ qualified Claude executable/platform/geometry in
604
+ [configuration](configuration.md#exact-home-launch-prompt-consent) has an enabled
605
+ development-channel fixture. Installed version alone grants no match. Ordinary
606
+ `session input` and wake delivery do not enter this controller.
607
+
608
+ Both spawn and start return `E_SPAWN_INCOMPLETE` for retained prompt failures.
609
+ With `launchPrompts.status` set to `blocked`, the home, actual terminal target,
610
+ provider effects and committed parent lineage are retained. Only an opted-in
611
+ launch commits a new parent link before dispatch; ordinary launches keep their
612
+ post-launch lineage commit and compensate a failed anchor write. That preserves
613
+ timing, not overwrite behavior: even non-opted-in parent spawns now refuse an
614
+ anchor edited or removed since the original pre-hook snapshot, instead of
615
+ replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
616
+ `answers`, `reason` and event `receipt`; unknown prompts use
617
+ `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
618
+ completed, including a possible key followed by an audit failure. It is
619
+ not proof that no input was sent. Both outcomes record `launched:false` while
620
+ retaining the real process/endpoint for inspection: this is never permission
621
+ to allocate another harness.
622
+
623
+ If metadata or pending-receipt recording fails after controller completion,
624
+ the API escalates to `incomplete` and appends a checked `launch-prompt` incomplete
625
+ event, retaining prior answers and receipts. Failed audit writes remain
626
+ `incomplete`; they never authorize another key or retry.
627
+
628
+ A replaced or unverifiable launch home is the explicit auditing exception.
629
+ There is no new home or deployment row: resolving either log through current
630
+ home metadata could address the replacement incarnation. The API reports
631
+ `launch home identity changed; metadata retained at original home`, preserves
632
+ prior evidence, and adds `{ok:false, results:[]}` to the receipt array. That
633
+ entry means zero audit destinations were attempted, not a successful write.
634
+ No audit or metadata write is directed into the replacement home.
635
+
636
+ A blocked result can follow a successfully submitted Enter. The accepted
637
+ completion families cover exact installed-plugin and plugin-absent banners;
638
+ different model, billing, effort or permission text can leave the pane active while
639
+ reporting a retained block. Inspect `answers` and the event receipts; never infer
640
+ that nothing started or nothing was answered. See the
641
+ [completion limitation](configuration.md#exact-home-launch-prompt-consent).
642
+
643
+ Retiring a blocked or incomplete spawned home can preserve a recovery copy
644
+ labelled `changed instance-home bytes`, even without authored changes: the
645
+ kernel changed metadata from `launched:true` to `false` after its baseline.
646
+ This conservative recovery is intentional. The independent runtime receipt
647
+ still controls the endpoint, and a mismatched metadata endpoint is refused.
648
+
649
+ Inspect the retained home with `oats session inspect --home <home>` and attach
650
+ if needed. A later `oats session start --home <home>` uses the ordinary running
651
+ process checks; it cannot answer into a still-running retained launch. Repeating
652
+ spawn, including the same idempotency key, does not replay prompt answers or
653
+ create a duplicate home. A genuinely new process in a later launch gets its own
654
+ bounded authority. A prompt receipt does not assert receive readiness.
655
+
581
656
  ### Stop
582
657
 
583
658
  `oats instance stop <instance> --plan` reports the session state, recorded
@@ -58,12 +58,15 @@ published to npm. Its developer docs are in
58
58
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
59
59
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
60
60
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
61
+ | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
61
62
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
62
63
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
63
64
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
64
65
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
65
66
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
66
67
  | `servers.mjs` | routing commands to a registered server |
68
+ | `launch-prompt-policy.mjs` | strict host-local exact-home aweb development-channel consent, canonical directory validation and config provenance |
69
+ | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts and the fixture-gated exact aweb development-channel signature |
67
70
  | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
68
71
 
69
72
  The schedule registry stores explicit concurrency caps, leaving the schedule
@@ -116,6 +119,14 @@ timeouts/errors are unchanged. Screen comparison can set only the observational
116
119
  use inert command runners and clocks; they do not qualify broker delivery or
117
120
  harness acceptance.
118
121
 
122
+ Schedule doctor diagnostics read saved definitions, run state, snapshot and
123
+ validated local configuration without constructing a live placement context.
124
+ Only a persisted attempt is described as blocking another run; an unknown last
125
+ observation may be refreshed by a later eligible tick. Workspace exclusions
126
+ can be diagnosed offline, but owner authorization cannot be established there,
127
+ so the remedy remains diagnostic prose. This does not add retained-state
128
+ reconciliation outside current placement or mutate attempts and locks.
129
+
119
130
  The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
120
131
  a provider. Provider behaviour lives in capabilities; the kernel supplies
121
132
  their contracts ([layers](layers.md)).
@@ -192,7 +203,9 @@ gets the plain per-call behaviour. Within a session:
192
203
  the half-initialised cache's wait and the lock-race backoff. What the
193
204
  deadline ends is a `timeout` (a peel or version it ended is never read as a
194
205
  missing commit or an older git), so an unread member degrades as any
195
- unreadable one. A cut wait never changes what it judges: past the deadline
206
+ unreadable one. A peel is judged by git's own result (`timedOut`), never by
207
+ the wall clock: git's timer can fire a moment before `Date.now()` reaches the
208
+ deadline. A cut wait never changes what it judges: past the deadline
196
209
  no lock is taken or reclaimed (live, stale or unreadable), and a cache
197
210
  directory waited for less than in full is not taken for a crash's leftover;
198
211
  - every git child is ended with SIGTERM first and SIGKILL only after a
@@ -26,6 +26,24 @@
26
26
  "additionalProperties": { "type": "string", "minLength": 1 },
27
27
  "description": "<repo key>: <path on this machine> for member clones outside the convention."
28
28
  },
29
+ "launchPromptAnswers": {
30
+ "type": "object",
31
+ "additionalProperties": false,
32
+ "properties": {
33
+ "homes": {
34
+ "type": "object",
35
+ "additionalProperties": {
36
+ "type": "object",
37
+ "additionalProperties": false,
38
+ "properties": {
39
+ "awebDevelopmentChannel": { "type": "boolean" }
40
+ }
41
+ },
42
+ "description": "Exact absolute canonical instance-home paths only; no wildcard or ancestor inheritance. Runtime validation resolves existing ancestors for homes not yet created."
43
+ }
44
+ },
45
+ "description": "Host-only consent to the bounded exact aweb development-channel confirmation. Missing awebDevelopmentChannel is false; provider settings and captured recipes do not grant consent."
46
+ },
29
47
  "settings": {
30
48
  "type": "object",
31
49
  "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
@@ -155,6 +173,6 @@
155
173
  },
156
174
  "$defs": {
157
175
  "launchPreference": { "type": "object", "additionalProperties": false, "required": ["harness"], "properties": { "harness": { "enum": ["pi", "claude", "codex"], "description": "The harness the role should run on." }, "model": { "type": "string", "minLength": 1, "pattern": "^[^\\s-][^\\s]*$", "description": "A model id for that harness; absent: the harness's own model." } } },
158
- "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" }
176
+ "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$", "maxLength": 64, "description": "A team label: at most 64 characters (0.44.0), the length the Desktop shows." }
159
177
  }
160
178
  }
@@ -60,7 +60,7 @@
60
60
  },
61
61
  "$defs": {
62
62
  "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
63
- "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
63
+ "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$", "maxLength": 64, "description": "A team label: at most 64 characters (0.44.0), the length the Desktop shows." },
64
64
  "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
65
65
  "packageId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
66
66
  "packageVersion": {
@@ -0,0 +1,161 @@
1
+ # OATS 0.44.0
2
+
3
+ ## Added
4
+
5
+ - **The launcher can answer one launch prompt for a home you opt in**
6
+ ([#708](https://github.com/awebai/oats/issues/708)). `oats-local.yaml`
7
+ gains the host-only strict boolean
8
+ `launchPromptAnswers.homes.<canonical-home>.awebDevelopmentChannel`, default
9
+ false: no existing home is opted in, and provider development mode is not
10
+ consent. For an opted-in home, a spawn or start the kernel itself launches
11
+ answers Claude Code's aweb development-channel confirmation with one Enter,
12
+ and only on an exact match of a qualified fixture (Claude 2.1.289,
13
+ `darwin-arm64`, 110x35, bound to the executable's SHA-256; completion frames
14
+ with the aweb plugin absent or installed). Everything else is blocked:
15
+ folder trust, API keys and any other or changed prompt. Session input and
16
+ wake delivery gain no prompt authority.
17
+ - The spawn preview reports the home's effective policy and its source
18
+ (`launchPromptAnswers`), and an opted-in launch warns that a harness
19
+ update can block it until fixtures are refreshed. There is never a
20
+ fallback key or a broader matcher.
21
+ - A blocked or uncertain launch keeps the home and pane and answers
22
+ `E_SPAWN_INCOMPLETE` with additive `launchPrompts` details (`status`,
23
+ `answers`, `reason`, `receipt`). Inspect the pane; never resend or
24
+ relaunch automatically. A submitted answer is not readiness, and a
25
+ retained `launched:false` is not proof the process is gone.
26
+ - Every answer and every outcome is a checked `launch-prompt` instance
27
+ event, including metadata or receipt failures after the controller
28
+ finished. A replaced home is the one exception: nothing is written into
29
+ the replacement.
30
+ - `workspaceTrust` is refused with instructions to remove it; folder trust
31
+ is [oats#712](https://github.com/awebai/oats/issues/712).
32
+ - Other model, billing, effort or permission banners after a submitted Enter
33
+ still block (`E_SPAWN_INCOMPLETE`, `blocked`).
34
+
35
+ See [configuration](../configuration.md#exact-home-launch-prompt-consent)
36
+ and [recovery](../execution-targets.md#launch-prompt-outcomes).
37
+ - **The Desktop shows launch-prompt consent and retained launches**
38
+ ([#711](https://github.com/awebai/oats/issues/711)). The spawn dialog shows a
39
+ home's development-channel consent and its source. A retained launch says
40
+ why and gives one next step: inspect the existing pane, then
41
+ `oats session start --home` (no new spawn, no retry). Activity shows
42
+ `launch-prompt` events.
43
+ - A provider's readiness binding check and a layer operation
44
+ (`oats operation run`) get `OATS_SOUL_ID`, and `OATS_AGENT` with the value
45
+ the soul's hooks and dispatched commands get, from a home and with
46
+ `--soul`: every provider surface now sees one soul identity
47
+ ([#707](https://github.com/awebai/oats/issues/707)). The readiness answer is
48
+ unchanged. See [Readiness check](../capabilities.md#readiness-check-bindingcheck).
49
+ - Readiness and doctor warn when a workspace has no operator soul
50
+ ([#671](https://github.com/awebai/oats/issues/671)). An operator soul is a
51
+ soul the workspace offers that composes `oats.setup`. The codes are:
52
+ - `operator-soul-missing`: no such soul;
53
+ - `operator-team-uncovered`: none is eligible for a team;
54
+ - `operator-coverage-unknown`: coverage cannot be read. It never asserts
55
+ absence.
56
+
57
+ Detection is by composition, never by a soul's name. Disabled and
58
+ unresolvable souls do not count, nor does one that empties a layer the
59
+ workspace fills. These are warnings only (`required: false`): nothing
60
+ refuses or spawns, and an eligible soul is not a launched seat.
61
+ - Readiness reports the subject's own teams.
62
+ - Doctor stays offline. It resolves from this machine's cache, which `oats
63
+ souls` fills, and checks every declared team. When the cache cannot answer,
64
+ it says coverage is unknown.
65
+
66
+ See [Operator coverage items](../desktop-cli-api.md#operator-coverage-items).
67
+
68
+ ## Changed
69
+
70
+ - **A team label is at most 64 characters**
71
+ ([#726](https://github.com/awebai/oats/issues/726)). Both
72
+ `oats-workspace.yaml` and `oats-local.yaml` now refuse a longer label. The
73
+ refusal is `E_WORKSPACE_SCHEMA`, and the message names the label and the
74
+ 64-character limit. `oats teams add` and a trigger's `spawn.teams` apply
75
+ the same bound.
76
+ - **Who this breaks:** a workspace or deployment with a label over 64
77
+ characters. The Desktop could never show such a label: it refused the
78
+ whole readiness answer.
79
+ - **What to do:**
80
+ - Shorten the label wherever it is used: `teams:`, `defaultTeam:`,
81
+ `souls:`, oats-local.yaml, and a trigger's `spawn.teams`.
82
+ - Respawn any instance whose recorded default team had the long label.
83
+ It keeps its spawn-time record, so readiness for it still reports
84
+ the long label.
85
+
86
+ See [Teams](../desktop-cli-api.md#teams).
87
+ - For `--soul` on a package soul, a readiness binding check and a layer
88
+ operation get `OATS_AGENT` as `<package>--<soul>`, the value its hooks
89
+ get, instead of the bare soul name.
90
+ - **Ordinary parent spawns refuse an edited anchor**
91
+ ([#708](https://github.com/awebai/oats/issues/708)). A `relation: parent`
92
+ spawn keeps its post-launch lineage timing but now refuses when the anchor's
93
+ `instance.json` was edited or removed since the spawn read it, instead of
94
+ overwriting the change with stale data.
95
+ - **Retirement keeps a recovery copy after a blocked spawn**: a blocked
96
+ spawn's kernel metadata transition counts as a changed home, so retirement
97
+ keeps a recovery copy even when no authored bytes changed.
98
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.45.0`**, so it runs against
99
+ this release's kernel; the Desktop 0.43.x refuses a 0.44 CLI. Upgrade the
100
+ Desktop and the CLI together.
101
+
102
+ ## Fixed
103
+
104
+ - **Readiness clips long item text**
105
+ ([#725](https://github.com/awebai/oats/issues/725)). An item's `reason`,
106
+ `remedy` and kernel `problems[].message` are at most 1000 characters,
107
+ clipped with `…`. A provider's refusal code over 128 characters, or with
108
+ control characters, is reported as `provider-unavailable`. Before, a long
109
+ remote error made the Desktop refuse the whole readiness answer. One
110
+ example is the workspace discovery error in the member and package-soul
111
+ items. A provider's own `result` is still relayed verbatim.
112
+ - **A commit the read just fetched is no longer reported missing**
113
+ ([#728](https://github.com/awebai/oats/issues/728)). When a read's deadline
114
+ or git's own timeout ended the check that a commit is in the cache, the
115
+ read reported the commit missing or "not a commit" (`not-found`), even one
116
+ it had just fetched. git's timer can fire a moment before the wall
117
+ clock reaches the deadline. Such a check is now the read's `timeout`
118
+ (`E_REMOTE_UNREADABLE`, reason `timeout`, stage `fetch`), judged by git's
119
+ own result. This covers a commit already in the cache, too: it is no
120
+ longer refetched or reported missing after a timed-out check. No new codes
121
+ or fields.
122
+
123
+ - **`oats sync --plan` previews; it used to apply**
124
+ ([#731](https://github.com/awebai/oats/issues/731)). `sync` ignored
125
+ `--plan`, so the "preview" wrote the lock. `--plan` now runs the same
126
+ discovery and resolution and gives the same report (`plan: true` in JSON;
127
+ the text says what a bare `oats sync` would change) and writes nothing: no
128
+ lock, no `agents/`, no automations snapshot. `oats sync` also refuses a flag
129
+ or positional it does not read with `E_BAD_ARGS`, naming it and the usage,
130
+ instead of ignoring it. A script that passed an unknown flag to `sync` now
131
+ fails: drop the flag. See [`oats sync`](../desktop-cli-api.md#oats-sync).
132
+
133
+ - **Schedule doctor distinguishes retained attempts from unknown observations**
134
+ ([#584](https://github.com/awebai/oats/issues/584)). Offline workspace warnings
135
+ describe saved placement exclusions or unverifiable authorization instead
136
+ of promising a reconciliation command that cannot run. Unknown observations
137
+ without an attempt no longer claim execution is blocked pending reconciliation.
138
+ For a local schedule whose retained state doctor cannot vouch for (captured
139
+ execution state, an invalid or mismatched stored definition or ID, unreadable
140
+ lock custody, or invalid local configuration), doctor no longer prints a
141
+ reconcile command and says why instead. This fixes diagnosis only:
142
+ retained-state recovery outside current workspace placement remains
143
+ unsupported, and attempts, locks and slot rules are unchanged.
144
+ - A restart no longer brings back older launch settings from the receipt of
145
+ a start that had already completed
146
+ ([#691](https://github.com/awebai/oats/issues/691)). A start keeps its
147
+ launch receipt, and the next start replayed it over `instance.json` even
148
+ when `instance.json` already recorded that start: an older launch recipe
149
+ (hook env, contributions) and older provider metadata replaced newer ones
150
+ before the launch hooks ran, and a plain `session start` on a running
151
+ instance wrote them before answering `E_SESSION_RUNNING`. Now a receipt for
152
+ a recorded start, on the recorded target, is never applied again. With
153
+ such a receipt, a plain start on a running instance answers
154
+ `E_SESSION_RUNNING` with nothing written and no hook run; a restart, or a
155
+ start after the target is gone, starts from `instance.json` as it is, and
156
+ its new receipt replaces the old one. An interrupted start (its metadata
157
+ write failed) is still adopted as before, with no second launch. A receipt
158
+ that names the recorded start on another, still running target is refused
159
+ as ambiguous (`E_SESSION_UNKNOWN`); the message names that target, and a
160
+ restart once it is stopped clears it. Nothing needs editing by hand. See
161
+ [Start and restart](../desktop-cli-api.md#start-and-restart).
package/docs/schedules.md CHANGED
@@ -430,8 +430,9 @@ you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
430
430
  `skipped`. The kernel never claims a task succeeded.
431
431
 
432
432
  `unknown` means the launch's side effects are unconfirmed: a command timed out
433
- or answered no envelope, or an attempt was never recorded. The job is skipped
434
- until `oats schedule reconcile <id>`, which adopts only an attributable
433
+ or answered no envelope, or an attempt was never recorded. A job with a
434
+ persisted attempt is skipped until `oats schedule reconcile <id>` (an
435
+ unknown `lastRun` alone does not block it; see below), which adopts only an attributable
435
436
  receipt (a spawn job's instance, named for its minute, or the instance a
436
437
  command's answer named). When nothing is attributable, check the roster and
437
438
  the host by hand, then `reconcile <id> --clear` records `launch-failed` and
@@ -448,13 +449,30 @@ is `! schedule-unresolved: …`; in `--json` it is a `problems[]` item:
448
449
  scheduledFor, startedAt, ageSeconds, holdsSlot, exited, error, remedy, message }
449
450
  ```
450
451
 
451
- `holdsSlot` says whether the job counts against `maxConcurrent`. `remedy` is
452
- `oats schedule reconcile <id>`, with `--clear` for a command or operation
453
- whose effects no named home proves (check the roster and the host by hand
454
- first), and with `--dir <scope>` for another deployment. A warning never
455
- changes doctor's exit status. Workspace command kinds come from the last
456
- saved automations snapshot, without a refresh or an account lookup. Unresolved
457
- workspace state is reported even if its definition is no longer available.
452
+ `holdsSlot` says whether the job counts against `maxConcurrent`. For a local
453
+ schedule whose saved state supports reconciliation, `remedy` names
454
+ `oats schedule reconcile <id>`, with `--clear` for unproven command/operation
455
+ effects (check the roster and host by hand first), and `--dir <scope>` for
456
+ another deployment. Invalid or unsupported saved inputs instead receive a
457
+ warning to preserve state and inspect effects with the deployment owner.
458
+ A warning never changes doctor's exit status.
459
+
460
+ Workspace guidance uses only validated local settings and the saved automation
461
+ snapshot. A known opt-out, missing saved definition, different assigned host or
462
+ absent trust explains why retained-state reconciliation is currently unavailable.
463
+ Missing saved data does not prove remote deletion. Invalid/unreadable inputs
464
+ are reported as unverifiable; even statically eligible placement is **not**
465
+ verified current authorization, because doctor does not check the owner account,
466
+ refresh discovery or access the network. No unconditional executable workspace
467
+ reconcile remedy is printed. Preserve retained state and inspect effects with
468
+ the deployment owner: this diagnostic correction does not add a way to clear
469
+ workspace attempts outside current placement, and that recovery remains
470
+ unsupported. Do not re-enable or retrust a job merely to clear its state.
471
+
472
+ Only a persisted `attempt` blocks that job pending reconciliation. An unknown
473
+ `lastRun` without an attempt is a last observation that an eligible tick may
474
+ re-observe; doctor does not promise that a tick will clear it or launch again.
475
+ Both cases retain their reported age, error and slot facts.
458
476
 
459
477
  Whether an `unknown` job keeps its host slot depends on what is still running:
460
478
 
@@ -236,6 +236,13 @@ When a claude or codex home is not covered, the spawn says so (text and
236
236
  prompt: trust <deployment> once (<the step>)`. `oats readiness` reports the
237
237
  same in `checks.configured` (code `harness-trust`, not required).
238
238
 
239
+ Exact-home [aweb development-channel consent](configuration.md#exact-home-launch-prompt-consent)
240
+ does not cover folder-trust prompts. It neither writes trust settings nor
241
+ enables existing homes automatically.
242
+ A blocked or incomplete prompt outcome preserves the home and process even
243
+ though its metadata says `launched:false`; inspect that endpoint before any
244
+ recovery. See [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
245
+
239
246
  ### Codex tool commands and the instance environment
240
247
 
241
248
  Codex can run tool commands under its shared app-server daemon rather than as