@awebai/oats 0.69.1 → 0.69.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.
Files changed (67) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +260 -28
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +3 -3
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/servers.md +7 -2
  17. package/docs/soul.schema.json +1 -0
  18. package/docs/souls-and-instances.md +35 -2
  19. package/docs/tui.md +100 -9
  20. package/docs/upgrading.md +9 -5
  21. package/docs/workspaces.md +2 -2
  22. package/injects/instance-boundary.md +19 -33
  23. package/injects/work-attached.md +8 -13
  24. package/injects/work-checkout.md +16 -30
  25. package/injects/work-directory.md +9 -15
  26. package/injects/work-workspace.md +8 -19
  27. package/injects/work-worktree.md +18 -33
  28. package/lib/capability-contract.mjs +2 -2
  29. package/lib/core.mjs +162 -49
  30. package/lib/instance-background.mjs +54 -0
  31. package/lib/instance-inspect.mjs +3 -0
  32. package/lib/instance-lifecycle.mjs +35 -0
  33. package/lib/instance-resolution.mjs +3 -2
  34. package/lib/instance-same-work.mjs +67 -0
  35. package/lib/instance-upgrade.mjs +18 -0
  36. package/lib/materialize.mjs +23 -2
  37. package/lib/resolve.mjs +32 -5
  38. package/lib/servers.mjs +19 -4
  39. package/lib/session-resume-contract.mjs +1 -0
  40. package/lib/session-resume.mjs +36 -9
  41. package/lib/soul-composition.mjs +13 -10
  42. package/lib/workspace.mjs +3 -2
  43. package/package-catalog.json +2 -2
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +30 -8
  46. package/packages/client/deployment-data.mjs +9 -0
  47. package/packages/client/deployment-panel.mjs +4 -0
  48. package/packages/client/instance-tree.mjs +64 -14
  49. package/packages/client/panel-views.mjs +11 -3
  50. package/packages/client/remote-roster.mjs +5 -1
  51. package/packages/client/roster-sections.mjs +50 -6
  52. package/packages/client/same-work.mjs +49 -0
  53. package/packages/client/session-resume.mjs +1 -1
  54. package/packages/client/soul-rows.mjs +2 -0
  55. package/packages/client/spawn-apply-contract.mjs +2 -1
  56. package/packages/client/spawn-decision.mjs +4 -1
  57. package/packages/client/spawn-preview-contract.mjs +12 -1
  58. package/packages/client/spawn-preview.mjs +2 -0
  59. package/packages/tui/README.md +2 -2
  60. package/packages/tui/lib/client.mjs +6 -2
  61. package/packages/tui/lib/main.mjs +44 -11
  62. package/packages/tui/lib/model.mjs +101 -43
  63. package/packages/tui/lib/store.mjs +76 -20
  64. package/packages/tui/lib/views/frame.mjs +2 -0
  65. package/packages/tui/lib/views/help.mjs +2 -0
  66. package/packages/tui/lib/views/instances.mjs +38 -1
  67. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -1,42 +1,28 @@
1
1
  ## Your two directories
2
2
 
3
- **`<instance-home>` is where this session starts** — the specific gitignored OATS
4
- instance directory you woke up in, given to your harness and to every lifecycle
5
- hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
6
- root, and not the work tree. Anything that says "your home" means this directory.
3
+ **IMPORTANT: ALWAYS FOLLOW THESE INSTRUCTIONS FOR WORKING**, here and in your
4
+ work-mode block below.
7
5
 
8
- - **Your brain and your state live here**: `AGENTS.md` (your composed
9
- instructions), `TASK.md` (this task), `instance.json` (what you were given
10
- and from where), and whatever working state your role keeps — your knowledge
11
- layer names those files, if you have one. They belong here, not in the work
12
- tree.
13
- - **Run OATS operational/lifecycle commands, and commands from active
14
- capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
15
- and whatever your own capabilities add; for example, when the
16
- aweb messaging capability is active, run `aw` there too. They resolve their
17
- scope from the directory you run them in, so running them from the work tree
18
- points them at the wrong deployment. To act on a different package or config
19
- scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
20
- - **Soul work is repository work.** If your TASK is to change soul content that
21
- lives in this repository, that is ordinary code work — do it on tracked paths
22
- under `work/`, reviewed like the rest. How your own learnings reach your soul
23
- is your knowledge capability's business, and its instructions below say so if you
24
- have one.
6
+ **Your home is where this session starts** (`$OATS_INSTANCE_HOME`). It is not
7
+ your user home (`~`), not the repository root, and not the work tree.
25
8
 
26
- **`<instance-home>/work` is your repository or workspace view** — whatever your
27
- work mode grants you of the code.
9
+ - It holds your brain and state: `AGENTS.md`, `TASK.md`, `instance.json` and
10
+ your role's working state. Never put them in `./work`.
11
+ - **ALWAYS run OATS commands, and commands from active capabilities, from
12
+ instance home** (for example, when the aweb messaging capability is active,
13
+ `aw` too): they resolve their scope from where you run them. For another
14
+ scope on purpose: `oats <cmd> --dir <path>`.
15
+
16
+ **`<instance-home>/work` is your repository or workspace view**, as your work
17
+ mode grants it.
28
18
 
29
19
  - **Repository work happens there, or in the extra trees your mode block
30
20
  grants, and nowhere else**: reading, editing, building, testing, git and
31
21
  commits, on repository content. Never from the main checkout or from your
32
22
  home root, beyond what your mode block names.
33
- - **What your mode permits is the mode block's call**, immediately below. Some
34
- modes are read-only, some share a tree with others, and that block is the
35
- authority on which operations are yours to perform.
36
- - This is about where the *repository's* content lives, not a ban on writing
37
- anywhere else: the episodic files above, and whatever artifacts your role
38
- calls for (a report written to a temp file before mailing it, a scratch
39
- script), go where your task and tooling direct.
40
-
41
- Move between the two as the task needs — the boundary is what each directory is
42
- *for*, not a place to settle in.
23
+ - **What your mode permits is the mode block's call**: your mode block, below,
24
+ is the authority.
25
+ - If your TASK is to change soul content that lives in this repository, that is
26
+ ordinary repository work. How your own learnings reach your soul is your
27
+ knowledge capability's business.
28
+ - Reports and scratch files go where your task and tooling direct.
@@ -1,16 +1,11 @@
1
1
  ## Work mode: attached
2
2
 
3
- Your `./work` is a symlink to **another instance's work tree** — you share
4
- their branch and their uncommitted state. You are a guest in their workspace.
3
+ Your `./work` is **another instance's work tree**, its branch and uncommitted
4
+ state. You are a guest.
5
5
 
6
- - **Never switch branches, never rebase, never reset** — the tree belongs to
7
- its owner; your job is focused additions on top of their current state.
8
- - Keep your changes and commits **small and clearly attributable** (your
9
- instance name in commit messages where ambiguity is possible).
10
- - Do not touch files the owner is mid-editing unless your task says so; when
11
- in doubt, coordinate through your messaging capability or your spawner.
12
- - Retiring you never removes the shared tree — cleanup of the tree is the
13
- owner's concern, not yours.
14
-
15
- This mode fits service agents (harvesters, reviewers, fixers) that operate
16
- on a live instance's work in flight.
6
+ - **NEVER switch branches, rebase or reset.** Make focused additions on top of
7
+ the owner's current state; keep changes and commits small, and name yourself
8
+ in commit messages where authorship could be unclear.
9
+ - Leave files the owner is editing alone unless your task says otherwise; when
10
+ unsure, ask through your messaging capability or your spawner.
11
+ - The tree's cleanup is its owner's; retiring you never removes it.
@@ -1,40 +1,26 @@
1
1
  ## Work mode: checkout
2
2
 
3
- Your `./work` is a symlink to the repo's **shared checkout** — you are working
4
- in the same tree as the human and possibly other agents.
3
+ Your `./work` is the repository's **shared checkout**: the human and other
4
+ agents work in the same tree.
5
5
 
6
- - **Work on the currently checked-out branch; never switch branches unless
7
- explicitly asked.**
8
- - No destructive git operations (reset --hard, rebase, force-push, checkout
9
- of another branch) without an explicit human instruction.
6
+ - **Stay on the checked-out branch; never switch unless explicitly asked.**
7
+ - **NO destructive git** (reset --hard, rebase, force-push, checking out
8
+ another branch) without an explicit human instruction.
10
9
  - Work that needs its own branch goes in an extra tree, not in `work/`.
11
10
 
12
11
  ### Extra trees
13
12
 
14
- When the work needs another branch, or another repository of this deployment,
15
- create an extra tree in your home. Run this from your home; `<base>` is the
16
- remote branch the work starts from (the branch itself, when you rework an
17
- existing one):
13
+ For another branch or repository, from your home (`--preview` first; `--repo
14
+ <member key|clone path>` for another repository; `<base>`: the remote branch
15
+ to start from, or the one you rework):
18
16
 
19
17
  oats worktree add --purpose <purpose> --branch <branch> --base <base>
20
18
 
21
- It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
22
- `<base>`. The repository is yours unless `--repo <member key|clone path>`
23
- names another; `--preview` shows what it would do.
24
-
25
- - It starts from the remote's current state and moves none of the clone's
26
- refs. Never start a tree from a local branch of the clone, which may be stale.
27
- - Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
28
- If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
29
- Never `-C`/`-B`, which reset a branch someone else may own.
30
- - If a capability of yours sets up new trees, `add` runs that setup, which
31
- may take minutes: give it a long timeout, or run it in the background and
32
- wait for it to exit. A killed `add` rolls back; run it again. Once it has
33
- finished, running it again with the same arguments does nothing.
34
- - The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
35
- (`<base>` when you rework an existing branch).
36
- - Before your task closes, merge each extra tree into your PR branch, or push its
37
- branch and name it in your hand-back; then
38
- `oats worktree remove --purpose <purpose>`, which keeps the branch and
39
- refuses a tree with uncommitted work.
40
- Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
19
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
20
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
21
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
22
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
23
+ - Before you finish, merge each tree into your PR branch, or push it and name
24
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
25
+ Retirement may keep a tree with uncommitted work; don't rely on it.
26
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -1,18 +1,12 @@
1
1
  ## Work mode: directory
2
2
 
3
- Your `./work` is an **instance-owned execution directory**. It is not a Git
4
- worktree, a checkout, or a link to the source instance or deployment context.
5
- The context recorded as `repo` supplies configuration; it grants no permission
6
- to edit that directory.
3
+ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
4
+ checkout or link. The `repo` recorded for you supplies configuration only; it
5
+ grants no permission to edit the `repo` directory.
7
6
 
8
- - Do task work inside `./work`. No Git repository or branch is created for you;
9
- do not initialize a fake repository to satisfy a workflow. Git might discover
10
- a containing repository; that does not authorize work in the containing tree.
11
- - Access external inputs and destinations only as explicitly authorized by the
12
- task and active capabilities. This mode does not impose a storage provider or
13
- a publication protocol.
14
- - Keep canonical instructions in the instance's `AGENTS.md`; `CLAUDE.md` is its
15
- compatibility symlink. Run OATS lifecycle/capability commands from home.
16
- - Retirement removes the execution directory only after nonempty work has a
17
- verified copy in the reported recovery storage beside the home. Recovery is
18
- not publication: deliver your results through the task's own protocol first.
7
+ - Work inside `./work`. **Never initialize a fake repository**; a containing
8
+ repository Git discovers is not yours.
9
+ - Use external inputs and destinations only as your task and capabilities
10
+ explicitly authorize.
11
+ - Deliver results through your task's own protocol before you finish: the
12
+ recovery copy kept at retirement is not publication.
@@ -1,22 +1,11 @@
1
1
  ## Work mode: workspace
2
2
 
3
- Your `./work` is the **whole workspace** (the deployment/team scope), not a
4
- single repo. Every member repo under it is visible context. You are a
5
- cross-repo coordinator: your product is routing, analysis, and coordination —
6
- not code changes.
3
+ Your `./work` is the **whole workspace**, not one repository. You route,
4
+ analyse and coordinate; you do not change code.
7
5
 
8
- - **Read freely across all member repos; never edit or commit inside them.**
9
- Repo changes are routed to that repo's own agents (see `oats status` in the
10
- deployment, your tasks capability, or messaging) or to the human.
11
- - No git state operations in any member repo: no branch switching, no
12
- commits, no worktrees, no resets.
13
- - Your own working state lives in your instance home, not in any member repo,
14
- and needs no git ceremony.
15
- - If one of your capabilities delivers durable updates into a repo, its own
16
- instructions define where and how — including whether anything is committed at
17
- all, and by whom. That is its business, not an exception you take into a
18
- member repo yourself.
19
-
20
- This mode fits coordinators, dispatchers, architects, and analysts whose
21
- scope is the workspace itself; if a task needs actual edits in one repo, ask
22
- for (or route to) a worktree-mode instance of that repo's agent instead.
6
+ - **Read freely across member repositories; never edit or commit inside them,
7
+ and NEVER change their Git state** (no branch switches, resets, pulls,
8
+ stashes or worktrees). Route a repository change to that repository's agents
9
+ or to your human.
10
+ - A capability that delivers updates into a repository follows its own
11
+ instructions; that is not an exception you take yourself.
@@ -1,42 +1,27 @@
1
1
  ## Work mode: worktree
2
2
 
3
- Your `./work` is a **git worktree on your own branch** — a full checkout that is
4
- yours alone: build, test and commit there, on your branch.
3
+ Your `./work` is a **git worktree on your own branch**, yours alone: build,
4
+ test and commit there.
5
5
 
6
- - **Never work in a shared checkout** (the repo's main checkout, or any clone
7
- others use): don't edit, commit or switch branches there. A clone is touched
8
- only through `oats worktree add`/`remove` below. If unsure, `pwd`.
9
- - Everything you change happens in `work/` or your extra trees — **including your
10
- own soul** when it lives in this repo: soul edits are branch changes, reviewed
11
- and merged like code.
12
- - Leave your branch and the worktree list clean when your task closes.
6
+ - **NEVER work in a shared checkout** (the main checkout, or a clone others
7
+ use). Touch a clone only through `oats worktree add`/`remove`. If unsure, `pwd`.
8
+ - Every repository change, **your own soul included**, is a change on your
9
+ branch or an extra tree's, reviewed and merged like code. Leave your branch
10
+ and worktree list clean at the end.
13
11
 
14
12
  ### Extra trees
15
13
 
16
- When the work needs another branch, or another repository of this deployment,
17
- create an extra tree in your home. Run this from your home; `<base>` is the
18
- remote branch the work starts from (the branch itself, when you rework an
19
- existing one):
14
+ For another branch or repository, from your home (`--preview` first; `--repo
15
+ <member key|clone path>` for another repository; `<base>`: the remote branch
16
+ to start from, or the one you rework):
20
17
 
21
18
  oats worktree add --purpose <purpose> --branch <branch> --base <base>
22
19
 
23
- It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
24
- `<base>`. The repository is yours unless `--repo <member key|clone path>`
25
- names another; `--preview` shows what it would do.
26
-
27
- - It starts from the remote's current state and moves none of the clone's
28
- refs. Never start a tree from a local branch of the clone, which may be stale.
29
- - Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
30
- If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
31
- Never `-C`/`-B`, which reset a branch someone else may own.
32
- - If a capability of yours sets up new trees, `add` runs that setup, which
33
- may take minutes: give it a long timeout, or run it in the background and
34
- wait for it to exit. A killed `add` rolls back; run it again. Once it has
35
- finished, running it again with the same arguments does nothing.
36
- - The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
37
- (`<base>` when you rework an existing branch).
38
- - Before your task closes, merge each extra tree into your PR branch, or push its
39
- branch and name it in your hand-back; then
40
- `oats worktree remove --purpose <purpose>`, which keeps the branch and
41
- refuses a tree with uncommitted work.
42
- Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
20
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
21
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
22
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
23
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
24
+ - Before you finish, merge each tree into your PR branch, or push it and name
25
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
26
+ Retirement may keep a tree with uncommitted work; don't rely on it.
27
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
181
181
  * declaration may not cover them: these exact names, and every exact name
182
182
  * starting with one of these prefixes (the events log; the stop, restart and
183
183
  * start receipts and locks; the rollback marker; AGENTS.md backups; the
184
- * attachments directory; the instance colour, `.oats-color.json`). This is the one list: a new kernel-written top-level
184
+ * attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
185
185
  * home entry MUST be added here and to the `not` patterns of
186
186
  * `retirement.disposable.home` in docs/capability-manifest.schema.json. A
187
187
  * prefix declaration can reach none of them except through `.oats-`, which is
188
188
  * refused whole; `.oats-<provider>` as an exact name stays declarable. */
189
189
  const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
190
- const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color"];
190
+ const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-same-work"];
191
191
 
192
192
  /** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
193
193
  * name or prefix), "kernel-owned", or undefined when it is sound. */