@awebai/oats 0.67.1 → 0.68.1

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 (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -197,8 +197,10 @@ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowle
197
197
  A running home's hooks and messaging commands read the teams live
198
198
  ([capabilities.md](capabilities.md#teams-in-the-provider-environment)).
199
199
 
200
- A running instance never changes under itself: a member moving or a package
201
- bump affects only new spawns.
200
+ A running instance never changes under itself; a stopped one can be moved to
201
+ the locked package versions with `oats instance upgrade`. Member modules and
202
+ the soul body still require a new spawn. See
203
+ [upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
202
204
 
203
205
  ### The harness starts normally
204
206
 
@@ -339,6 +341,18 @@ so that user's name stays numbered (`harness-failed`). The preview then answers
339
341
  only; any other harness, and any failure of the call, leaves the name numbered
340
342
  and says why
341
343
  ([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
344
+ An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
345
+ machine that spawns makes the same call, names the instance
346
+ `<descriptive>-<role>`, de-duplicated the same way, and numbers it on any
347
+ failure; the result's `naming` says which, and the apply may take up to 20 s
348
+ longer ([On an apply](desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)).
349
+ Without the flag an apply is numbered, as before.
350
+ `oats instance suggest-name --soul <soul> --task-file <f>` asks for the same
351
+ words on this machine for a spawn that will land on another (the Desktop's
352
+ dialog, spawning through `--server`): the soul only gives the role and needn't
353
+ exist here, nothing is written or reserved, and the name is not made unique,
354
+ which the landing host does
355
+ ([A name for a spawn elsewhere](desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
342
356
 
343
357
  From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
344
358
  discovers the workspace over its remotes and confirms membership → finds the
@@ -1935,7 +1949,28 @@ that is `E_WORKTREE_DIRTY`, with Git's message, and the record is kept;
1935
1949
  commit and push the work, or discard it, then run `remove` again. A purpose
1936
1950
  with no record is `E_BAD_ARGS`: remove a tree made another way with
1937
1951
  `git worktree remove`. Any other refusal is `E_WORK_PRESERVATION_FAILED`,
1938
- and nothing is removed. On a `creating` record whose process is gone, `remove`
1952
+ and the record is kept. Git can remove its registration and some files before
1953
+ failing on read-only ignored output (for example, a Go module cache). Once
1954
+ Git's clean check has passed and its registration is gone, `remove` makes
1955
+ the remaining files writable and deletes them, without following symlinks
1956
+ outside the tree. It then prunes, verifies removal and drops the record.
1957
+
1958
+ A retry of an unregistered tree whose `.git` file points at a missing gitdir
1959
+ first compares its surviving files with the recorded branch through a
1960
+ temporary Git index. Deleted files are allowed; modified files and untracked
1961
+ files that are not ignored are `E_WORKTREE_DIRTY`, with their paths listed.
1962
+ Deleted entries are marked skip-worktree in that private index so Git can
1963
+ still read deleted `.gitignore` files from the branch when checking ignored
1964
+ output. This never changes the clone's index. Cleanup grants directories
1965
+ owner read, write and search access, and keeps `.git` until all other entries
1966
+ are deleted, so a failed deletion can be retried.
1967
+ An unreadable branch or a failed inspection keeps the tree and record.
1968
+ Failures after Git started removing files say that removal may be partial
1969
+ and name the retry. If Git already removed `.git` too, automatic comparison
1970
+ is refused: save any work and remove the directory by hand, then run
1971
+ `oats worktree remove --purpose <p>` again to drop the record. The refusal
1972
+ names that step.
1973
+ On a `creating` record whose process is gone, `remove`
1939
1974
  completes the rollback instead. Its answer then says whether the branch was
1940
1975
  kept (`branchKept`, `branchKeptReason`).
1941
1976