@awebai/oats 0.69.18 → 0.69.20

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 (52) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +27 -14
  3. package/docs/container.md +416 -43
  4. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  5. package/docs/design/2026-09-28-automations-trust.md +1 -1
  6. package/docs/desktop-cli-api.md +52 -31
  7. package/docs/desktop.md +29 -6
  8. package/docs/execution-targets.md +32 -17
  9. package/docs/implementation.md +4 -3
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +6 -4
  15. package/docs/release-notes/v0.69.19.md +172 -0
  16. package/docs/release-notes/v0.69.20.md +325 -0
  17. package/docs/servers.md +6 -4
  18. package/docs/souls-and-instances.md +37 -13
  19. package/docs/tui.md +8 -8
  20. package/docs/upgrading.md +17 -5
  21. package/docs/workspaces.md +13 -7
  22. package/injects/work-directory.md +27 -2
  23. package/injects/work-workspace.md +32 -6
  24. package/lib/core.mjs +33 -197
  25. package/lib/hook-outcome.mjs +6 -0
  26. package/lib/host-run.mjs +24 -19
  27. package/lib/instance-lifecycle.mjs +3 -1
  28. package/lib/instance-listing.mjs +3 -2
  29. package/lib/launch-prompt-fixtures/README.md +6 -0
  30. package/lib/retire-admission.mjs +215 -0
  31. package/lib/servers.mjs +3 -0
  32. package/lib/session-resume-contract.mjs +1 -1
  33. package/lib/session-resume.mjs +130 -47
  34. package/lib/session-seen.mjs +3 -3
  35. package/package-catalog.json +3 -3
  36. package/package.json +3 -1
  37. package/packages/client/attributed-human.mjs +13 -0
  38. package/packages/client/deployment-data.mjs +4 -0
  39. package/packages/client/deployment-panel.mjs +2 -0
  40. package/packages/client/instance-lifecycle.mjs +6 -4
  41. package/packages/client/instance-presentation.mjs +2 -2
  42. package/packages/client/instance-tree.mjs +18 -7
  43. package/packages/client/lifecycle-confirmation.mjs +4 -2
  44. package/packages/client/lifecycle-contract.mjs +11 -6
  45. package/packages/client/remote-roster.mjs +4 -0
  46. package/packages/record/README.md +15 -2
  47. package/packages/record/docs/capture-service.md +14 -0
  48. package/packages/record/lib/canonical.mjs +2 -70
  49. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  50. package/packages/record/lib/capture-aw.mjs +11 -5
  51. package/packages/record/lib/capture-health.mjs +16 -5
  52. package/skills/oats-getting-started/SKILL.md +3 -3
package/bin/oats.mjs CHANGED
@@ -3012,7 +3012,7 @@ function retireCmd() {
3012
3012
  dropAmbientRoot();
3013
3013
  let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
3014
3014
  try {
3015
- const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
3015
+ const plan = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") });
3016
3016
  if (args.includes("--json")) { jsonOk(plan); return; }
3017
3017
  console.log(`retire ${name} — plan ${plan.planRevision}`);
3018
3018
  console.log(` session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
@@ -3061,7 +3061,7 @@ function retireCmd() {
3061
3061
  // its extra trees as it names them (the retire refuses as stale rather than move or remove one
3062
3062
  // that no longer reads that way when it gets to them).
3063
3063
  revalidate = () => {
3064
- try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
3064
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") }); } catch (e) { planFailure = e; throw e; }
3065
3065
  if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
3066
3066
  return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
3067
3067
  };
@@ -157,6 +157,7 @@ A self-contained package has an `oats.json`:
157
157
  reads what there is to undo from the home and from the service it
158
158
  registered with, and answers `meta: { retired: false, reason:
159
159
  "nothing-to-delete" }` when there is nothing: that is a complete cleanup.
160
+ Every other explicit `retired: false` outcome is an incomplete cleanup.
160
161
  - A capability declaring a **required** spawn hook should declare a `retire` hook
161
162
  too. Without one, OATS has no way to undo what the spawn hook did and no way to
162
163
  know whether it did anything, so a failure quarantines the home rather than
@@ -183,18 +184,30 @@ A self-contained package has an `oats.json`:
183
184
  the branch gone (a damaged ref, a failed read), the retry stays incomplete
184
185
  with `git branch <b>: could not verify whether it still exists (…)`. A retry that still cannot
185
186
  finish keeps the home again, names what is outstanding, and exits nonzero.
186
- - The **escape hatch is `oats retire <instance> --force`**, for a home OATS cannot
187
- identify at all: no `instance.json` and no **usable** cleanup descriptor, or an
188
- `instance.json` that does not say which retire hooks to run and no usable
189
- descriptor beside it. Such a record names no repository (`repo`), which the
190
- retire hooks are run for, and does not show (`capabilityRuntime`) that no
191
- capability has a retire hook: the stub a spawn leaves when it is killed
192
- before its record, where no marker was written before its hooks (a spawn by
193
- a kernel before this rule, or a marker since removed). Retire refuses it
194
- with `E_UNIDENTIFIED_INSTANCE_HOME` before anything is stopped, run or
195
- removed: the spawn hooks may have registered an identity that only the
196
- retire hooks would release. Clean up by hand what the capabilities
197
- registered, then `--force` removes the home, running no hook. Usable
187
+ - **A home whose retire hooks cannot run is refused before anything is stopped,
188
+ run or removed, children included.** The same admission rule applies to
189
+ `oats retire --plan`, the Desktop's Remove plan and every apply path.
190
+ `E_UNIDENTIFIED_INSTANCE_HOME` names the cause, the recorded capabilities
191
+ that may have left state, and the manual-cleanup remedy. No current
192
+ deployment configuration can prove what an old home registered.
193
+ A normal home needs its recorded `capabilityRuntime` and a context repository
194
+ to run its hooks. The context is its recorded `repo`, or the repository Git
195
+ identifies for its own worktree when the record names none. An explicit
196
+ capability set with no retire hooks proves that none is owed. A captured home from before 0.26 cannot run its hooks:
197
+ only an explicit empty captured `hookOrder`, with no capability metadata,
198
+ hook intents, hook failures or lifecycle marked `*-cleanup-required`,
199
+ proves that no capability's spawn hook ran. Missing
200
+ information proves nothing.
201
+ - The **escape hatch is `oats retire <instance> --force`**. This includes
202
+ homes spawned before `capabilityRuntime`, captured homes without proof of
203
+ no spawn hooks, a home without a usable record or cleanup descriptor, and
204
+ a home whose recorded retire hooks have no context repository. Inspect the
205
+ home and clean up external identities and memberships with the provider's
206
+ tooling first. Force can remove the home while leaving that state active;
207
+ its output keeps the warnings about hooks that did not run and state that
208
+ was not revoked. An unreadable `instance.json` still refuses even with
209
+ force. A forced self-retirement carries the force choice into its deferred
210
+ completion. A usable cleanup descriptor can drive the normal retry. Usable
198
211
  means it satisfies the versioned cleanup contract the rollback writes, checked
199
212
  to the depth the retry consumes it: `version`, a context `repo`, a recognised
200
213
  `work` mode (plus a `branch` for `worktree` — an unknown mode would skip the
@@ -245,7 +258,7 @@ A self-contained package has an `oats.json`:
245
258
  verifiably alive (its pid runs with the recorded start time):
246
259
  - `oats status` gives the home's row `spawnInProgress: true` and no
247
260
  `rollbackIncomplete`;
248
- - `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
261
+ - `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--plan` and `--force` included;
249
262
  - `oats session start` refuses it as any quarantined home
250
263
  (`E_INSTANCE_RETIRING`).
251
264
 
@@ -1188,7 +1201,7 @@ own configuration.
1188
1201
  naming the release, not with a schema error.
1189
1202
  3. The blast radius is every soul that composes the capability, on every host
1190
1203
  below the release: one capability can stop every developer soul of a
1191
- workspace from spawning, as in lfx-oats-workspace#22, where one capability
1204
+ workspace from spawning, as in lab-oats-workspace#22, where one capability
1192
1205
  took down every developer soul.
1193
1206
  4. To limit it, put the hook in a small capability composed only by the souls
1194
1207
  that need the setup.