@awebai/oats 0.69.17 → 0.69.19
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.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +8 -1
- package/docs/container.md +345 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +100 -53
- package/docs/desktop.md +53 -24
- package/docs/execution-targets.md +66 -48
- package/docs/implementation.md +8 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +30 -23
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +5 -3
- package/docs/souls-and-instances.md +51 -27
- package/docs/trust-model.md +119 -0
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +45 -19
- package/docs/workspaces.md +3 -3
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +26 -11
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +43 -29
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +144 -51
- package/lib/session-seen.mjs +16 -11
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +4 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- package/skills/oats-getting-started/SKILL.md +33 -4
|
@@ -328,23 +328,25 @@ oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/ret
|
|
|
328
328
|
```
|
|
329
329
|
|
|
330
330
|
An instance is named exactly `--name <slug>`, or `<soul>-<purpose>` with
|
|
331
|
-
`--purpose`; with neither, the kernel numbers it.
|
|
332
|
-
person or an agent chooses is
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
331
|
+
`--purpose`; with neither, the kernel numbers it. A typed `--name` is used
|
|
332
|
+
exactly as given. How a person or an agent chooses one is the oats.core
|
|
333
|
+
skill oats-souls, "Name the instance"
|
|
334
|
+
([its rule](../oats-package/capabilities/oats-core/skills/oats-souls/SKILL.md#name-the-instance)).
|
|
335
|
+
`--purpose` derives the name from the soul, for
|
|
336
336
|
automations and scripts that know only the soul and a purpose.
|
|
337
337
|
Names are unique per deployment (a workspace-model deployment has one agents
|
|
338
338
|
root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
|
|
339
|
-
refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog
|
|
340
|
-
|
|
339
|
+
refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog sends a typed
|
|
340
|
+
name as typed, lowercased.
|
|
341
341
|
`oats spawn <soul> --preview --suggest-name --task-file <f>` asks the soul's
|
|
342
|
-
own harness for the
|
|
342
|
+
own harness for the whole name, `<work>-<role>` with the role as the task
|
|
343
|
+
gives it, from the task, in one call that starts
|
|
343
344
|
none of the user's MCP servers, hooks, plugins or extensions. Claude Code's
|
|
344
345
|
built-in plugins, the host's managed-policy hooks and pi's credential commands
|
|
345
346
|
are the stated exceptions; a claude login through `apiKeyHelper` is not read,
|
|
346
347
|
so that user's name stays numbered (`harness-failed`). The preview then answers for
|
|
347
|
-
`--name <
|
|
348
|
+
`--name <that name>`, de-duplicated the same way; nothing appends the soul's
|
|
349
|
+
role. On claude and pi
|
|
348
350
|
only; any other harness, and any failure of the call, leaves the name numbered
|
|
349
351
|
and says why
|
|
350
352
|
([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
|
|
@@ -355,16 +357,16 @@ at spawn (`.oats-background.json`), so a later soul edit moves no existing
|
|
|
355
357
|
instance; `oats instance background <instance> on|off` does. Both flags
|
|
356
358
|
together are `E_BAD_ARGS`.
|
|
357
359
|
An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
|
|
358
|
-
machine that spawns makes the same call, names the instance
|
|
359
|
-
|
|
360
|
+
machine that spawns makes the same call, names the instance with the reply's
|
|
361
|
+
name, de-duplicated the same way, and numbers it on any
|
|
360
362
|
failure; the result's `naming` says which, and the apply may take up to 20 s
|
|
361
363
|
longer ([On an apply](desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)).
|
|
362
364
|
Without the flag an apply is numbered, as before.
|
|
363
|
-
`oats instance suggest-name --
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
365
|
+
`oats instance suggest-name --task-file <f>` asks for the same name on this
|
|
366
|
+
machine for a spawn that will land on another (the Desktop's dialog, spawning
|
|
367
|
+
through `--server`): nothing is written or reserved, and the name is not made
|
|
368
|
+
unique, which the landing host does. `--soul <soul>` is optional: when given it
|
|
369
|
+
is checked as a soul name's shape and does not change the name
|
|
368
370
|
([A name for a spawn elsewhere](desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
|
|
369
371
|
|
|
370
372
|
From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
|
|
@@ -1839,8 +1841,9 @@ after the capability injects (`injects/instance-boundary.md`):
|
|
|
1839
1841
|
target another one deliberately).
|
|
1840
1842
|
- `<instance-home>/work` — the repository or workspace view — is where
|
|
1841
1843
|
repository reading, editing, building, testing, git and commits happen, to the
|
|
1842
|
-
extent the mode below permits. In `worktree
|
|
1843
|
-
instance's [extra trees](#extra-trees) in the home
|
|
1844
|
+
extent the mode below permits. In `worktree`, `checkout`, `workspace` and
|
|
1845
|
+
`directory` mode, the instance's [extra trees](#extra-trees) in the home
|
|
1846
|
+
serve the same purpose.
|
|
1844
1847
|
- The home has no soul link: the composed `AGENTS.md` already carries the
|
|
1845
1848
|
soul's instructions, and `instance.json` `soulDir` records the (read-only,
|
|
1846
1849
|
per-commit) soul directory every hook and dispatched command receives as
|
|
@@ -2012,6 +2015,14 @@ without Git. `repo` (or `--repo`) supplies context only and may be an ordinary
|
|
|
2012
2015
|
directory; without it, the deployment directory (where `oats-local.yaml` is) is
|
|
2013
2016
|
used. No implicit fallback changes the other modes.
|
|
2014
2017
|
|
|
2018
|
+
Repository work that needs a branch — a change the instance's role and task
|
|
2019
|
+
call for, or a repository at the remote's current state — goes in an
|
|
2020
|
+
[extra tree](#extra-trees) of the instance's own, never in `work/` (which
|
|
2021
|
+
never becomes a repository) and never in the `repo` directory. An extra tree
|
|
2022
|
+
always names its repository (`--repo`): the recorded `repo` is context only,
|
|
2023
|
+
the deployment directory by default, so `oats worktree add` without `--repo`
|
|
2024
|
+
is refused when it is not a clone (`E_CLONE_MISSING`).
|
|
2025
|
+
|
|
2015
2026
|
`--work-dir` and `--branch` are rejected. Canonical instructions, skill
|
|
2016
2027
|
composition, provider trust and harness preflight still apply. Retirement preserves nonempty work in verified recovery storage beside the
|
|
2017
2028
|
home (`workRecovery.path/work`) before deleting it, including files created by
|
|
@@ -2046,21 +2057,34 @@ where it works are decoupled.
|
|
|
2046
2057
|
|
|
2047
2058
|
Rules:
|
|
2048
2059
|
|
|
2049
|
-
- Read freely across member repos
|
|
2050
|
-
|
|
2051
|
-
- No
|
|
2060
|
+
- Read freely across member repos through `work/`; **never edit or commit
|
|
2061
|
+
inside the member clones** — others use them.
|
|
2062
|
+
- No Git state operations in any member clone (no branch switches, resets,
|
|
2063
|
+
pulls, stashes, or `git worktree` run by hand).
|
|
2064
|
+
- Work that needs a branch of a member — a change the instance's role and
|
|
2065
|
+
task call for, or a member at the remote's current state — goes in an
|
|
2066
|
+
[extra tree](#extra-trees) of the instance's own, which `oats worktree add`
|
|
2067
|
+
makes without moving any of the clone's refs. Otherwise route the change to
|
|
2068
|
+
the owning repo's agents or the human. The mode says where work happens;
|
|
2069
|
+
what work the instance takes on is its role's and its task's call.
|
|
2052
2070
|
- Knowledge promotion follows the knowledge capability's own protocol, never
|
|
2053
2071
|
direct edits through the workspace view.
|
|
2054
2072
|
|
|
2055
|
-
The instance records no branch: the workspace is not a Git tree.
|
|
2073
|
+
The instance records no branch: the workspace is not a Git tree. For the same
|
|
2074
|
+
reason an extra tree always names its repository (`--repo`): the instance's
|
|
2075
|
+
recorded repository is the deployment directory.
|
|
2056
2076
|
|
|
2057
2077
|
### Extra trees
|
|
2058
2078
|
|
|
2059
|
-
An instance in `worktree` or `
|
|
2060
|
-
Git worktrees in its home, beside `work/`. It does
|
|
2061
|
-
another branch, or another repository of the deployment
|
|
2062
|
-
touches several repositories)
|
|
2063
|
-
|
|
2079
|
+
An instance in `worktree`, `checkout`, `workspace` or `directory` mode can
|
|
2080
|
+
create extra trees: linked Git worktrees in its home, beside `work/`. It does
|
|
2081
|
+
so when the work needs another branch, or another repository of the deployment
|
|
2082
|
+
(one task that touches several repositories); in `workspace` mode, whenever
|
|
2083
|
+
work needs a branch of a member, since `work/` is read-only; in `directory`
|
|
2084
|
+
mode, whenever work needs a branch at all, since `work/` is not a Git tree.
|
|
2085
|
+
The `worktree`, `checkout`, `workspace` and `directory` briefings teach it
|
|
2086
|
+
(the `workspace` and `directory` ones with `--repo` always, in one shared
|
|
2087
|
+
section); the `attached` briefing does not.
|
|
2064
2088
|
|
|
2065
2089
|
```text
|
|
2066
2090
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch>
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Trust model
|
|
2
|
+
|
|
3
|
+
Everything that runs as one operating-system user is one trust group, the
|
|
4
|
+
kernel included. OATS draws no line inside a user, and must never run with
|
|
5
|
+
more authority than the agents whose homes it reads.
|
|
6
|
+
|
|
7
|
+
## The parties
|
|
8
|
+
|
|
9
|
+
- The **operator**: the person, or the control plane acting for them, who
|
|
10
|
+
decides which agents exist and with what configuration.
|
|
11
|
+
- The **kernel**: `oats` commands and `oats host run`. It has no authority of
|
|
12
|
+
its own. It runs as whoever started it.
|
|
13
|
+
- An **agent**: a harness process and everything it starts. It can write its
|
|
14
|
+
own home, and anything else its user can write.
|
|
15
|
+
- A **capability**: code copied into an agent's home at spawn, which the
|
|
16
|
+
kernel runs as hooks and commands.
|
|
17
|
+
|
|
18
|
+
## The line
|
|
19
|
+
|
|
20
|
+
The line is the user boundary and, for a hosted team, the container around
|
|
21
|
+
it ([container.md](container.md)). Inside it nothing protects one agent from
|
|
22
|
+
another, or the kernel's own state from an agent: an agent can read and write
|
|
23
|
+
what the kernel reads and writes.
|
|
24
|
+
|
|
25
|
+
1. **A trust group is the unit of compromise.** If one agent in it is
|
|
26
|
+
subverted, treat every agent, seat and credential in it as subverted.
|
|
27
|
+
2. **One team, one trust group.** Agents that must not be able to read each
|
|
28
|
+
other's identities or affect each other's work do not share a container or
|
|
29
|
+
a user. Nothing in OATS makes that safe. A container holds one team, never
|
|
30
|
+
several.
|
|
31
|
+
3. **The kernel takes no authority across the line.** It is never run as
|
|
32
|
+
root, as a different user, or on another machine against a home that an
|
|
33
|
+
agent on the far side of the line could write. A command given
|
|
34
|
+
`--server` runs `oats` on the home's side
|
|
35
|
+
([servers.md](servers.md)); the Desktop and the TUI start the local `oats`
|
|
36
|
+
and run no kernel code of their own on what a remote home contains.
|
|
37
|
+
The kernel holds itself to this: a start, a resume, a stop, a retire or
|
|
38
|
+
an upgrade of a home that the user running it does not own is refused
|
|
39
|
+
with `E_HOME_NOT_OWNED` before anything is written, root included.
|
|
40
|
+
One piece of the package does run as root, and it is outside this rule:
|
|
41
|
+
the harness-credential receiver `share/oats-login-receive`
|
|
42
|
+
([servers.md](servers.md#harness-credentials)). It runs under a forced
|
|
43
|
+
command, reads only its standard input, writes only the credential file
|
|
44
|
+
its root-owned configuration names and touches no home, so it is not the
|
|
45
|
+
kernel acting on a home.
|
|
46
|
+
4. **An agent's home is untrusted as data, and trusted as code only inside
|
|
47
|
+
its own group.** The kernel executes what it finds there, such as
|
|
48
|
+
lifecycle hooks and a module's commands, because doing so gives the agent
|
|
49
|
+
nothing it does not already have. What it finds there decides nothing
|
|
50
|
+
about another group.
|
|
51
|
+
5. **Inside a group OATS protects the agents' work, not the group's
|
|
52
|
+
secrets.** Locks, claims, recovery copies and the Git hardening at
|
|
53
|
+
retirement exist so that a kill, a race or a hostile repository
|
|
54
|
+
configuration does not lose or corrupt work. They are robustness, not
|
|
55
|
+
access control.
|
|
56
|
+
|
|
57
|
+
## What OATS does not promise
|
|
58
|
+
|
|
59
|
+
Inside one trust group, none of these hold:
|
|
60
|
+
|
|
61
|
+
- That an agent cannot read another agent's seat key, the team's Claude
|
|
62
|
+
token, the launch configurations, the schedule registry or sshd's host
|
|
63
|
+
keys.
|
|
64
|
+
- That an agent cannot stop sshd, `oats host run`, the wake broker or its
|
|
65
|
+
supervisor.
|
|
66
|
+
- That a capability is confined to the outputs it declares.
|
|
67
|
+
- That a command which reads is one which runs nothing.
|
|
68
|
+
`oats readiness --home <home>` executes the home's module commands, and
|
|
69
|
+
today it gives them the environment of whoever runs the read, without that
|
|
70
|
+
caller's `OATS_`, `OAS_` and `PI_` identity variables. Run it for a home of
|
|
71
|
+
another trust group only from an environment that holds nothing the home's
|
|
72
|
+
agent should not have.
|
|
73
|
+
- That a capability the kernel reports as trusted has been judged.
|
|
74
|
+
[Trust is the workspace's declaration](capabilities.md#mental-model) of a
|
|
75
|
+
member repo or a package. The kernel then checks that what it is about to
|
|
76
|
+
run is the copy made at spawn. That copy is in the agent's home, so the
|
|
77
|
+
check is no defence against the agent.
|
|
78
|
+
- That a harness's sandbox is a boundary. OATS counts none as one and relies
|
|
79
|
+
on none. Where a harness restricts what its agent can write, that is the
|
|
80
|
+
harness's property and not a promise of OATS.
|
|
81
|
+
|
|
82
|
+
## Code from outside the group
|
|
83
|
+
|
|
84
|
+
What an agent's home runs comes from the workspace: packages, pinned by the
|
|
85
|
+
deployment's lock, and member repositories, which are not pinned. A member's
|
|
86
|
+
souls and capabilities are used at the member's latest commit, trusted by
|
|
87
|
+
membership ([capabilities.md](capabilities.md#mental-model)).
|
|
88
|
+
|
|
89
|
+
So the default branch of the workspace host and of every member is outside
|
|
90
|
+
every agent group, and it is the operator's to keep there. A commit on it
|
|
91
|
+
becomes the hooks and commands of the next spawn of every soul that composes
|
|
92
|
+
that member, in every deployment of the workspace, and of the next capability
|
|
93
|
+
command an operator runs on their own machine.
|
|
94
|
+
|
|
95
|
+
OATS does not enforce this. An agent holds whatever Git credential its
|
|
96
|
+
deployment gives it. If that credential can push to a member's default
|
|
97
|
+
branch, one subverted agent reaches every other team and the operator, and
|
|
98
|
+
rule 1 no longer bounds the loss. Give agents a credential that cannot:
|
|
99
|
+
branch protection that requires another identity's approval, or a repository
|
|
100
|
+
that is not a member of the workspace.
|
|
101
|
+
|
|
102
|
+
## Keys outside the group
|
|
103
|
+
|
|
104
|
+
One part of the line is enforced by something other than OATS: where a
|
|
105
|
+
team's keys are kept. A hosted aweb team's controller key is kept by the
|
|
106
|
+
service, outside every agent group, and no agent can read it. That holds
|
|
107
|
+
today.
|
|
108
|
+
|
|
109
|
+
The aweb human-assurance design goes further. In it, the keys of a human, of
|
|
110
|
+
a namespace and of a team's controller will be held by a protected signer
|
|
111
|
+
outside every agent group. The deployment root's agent key will stay inside
|
|
112
|
+
the group by design, and what it can do will be bounded by its admission
|
|
113
|
+
policy, so that its loss is the loss of that group and of nothing above it.
|
|
114
|
+
The signer is not shipped.
|
|
115
|
+
|
|
116
|
+
No deployment that brings its own team has this yet. Each still holds its
|
|
117
|
+
team keys under the agents' user, in `~/.awid/team-keys` and `.aweb-roots`.
|
|
118
|
+
Under rule 1 those keys are compromised along with any agent in that group,
|
|
119
|
+
until they are moved to the signer.
|
package/docs/tui.md
CHANGED
|
@@ -176,12 +176,12 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
176
176
|
kernel reported that were withheld (a home outside its soul's directory,
|
|
177
177
|
or one reported twice), `2 withheld`, when there are any.
|
|
178
178
|
- **The list** is the roster the Desktop draws: the same groups in the same
|
|
179
|
-
order, from the same code. It is in
|
|
180
|
-
instance, so starting or stopping an instance moves nothing. An instance
|
|
179
|
+
order, from the same code. It is in spawn order, newest first, by each
|
|
180
|
+
group's top instance, so starting or stopping an instance moves nothing. An instance
|
|
181
181
|
that others were spawned from has them indented under it, and keeps its
|
|
182
182
|
place when it gains or loses one. Under one parent, the instances that do
|
|
183
183
|
its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
|
|
184
|
-
come first, then the others, each part
|
|
184
|
+
come first, then the others, each part newest first, as the Desktop lists
|
|
185
185
|
them. An empty row stands between each run
|
|
186
186
|
of instances related to no other and the group before or after it. The
|
|
187
187
|
indent alone says which instance is under which: no mark is drawn for
|
|
@@ -974,7 +974,7 @@ selected.
|
|
|
974
974
|
```
|
|
975
975
|
acme-platform │ dev
|
|
976
976
|
acme-billing ● │ soul dev
|
|
977
|
-
|
|
977
|
+
lab │ state running
|
|
978
978
|
garnet │ harness claude, claude-opus-5-5 (so…
|
|
979
979
|
+2 │ work worktree, agents/dev
|
|
980
980
|
│ team eng
|
|
@@ -983,7 +983,7 @@ selected.
|
|
|
983
983
|
|
|
984
984
|
The sidebar's first rows list the workspaces this run can show, one row a
|
|
985
985
|
workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
|
|
986
|
-
order: `
|
|
986
|
+
order: `lab` is one row however many machines hold it, and a machine the
|
|
987
987
|
rules shared with the Desktop matched to no workspace is a row by its own
|
|
988
988
|
name, in the same flat list. A row is one line: the name. With one
|
|
989
989
|
workspace the list is its row.
|
|
@@ -1028,7 +1028,7 @@ workspace the list is its row.
|
|
|
1028
1028
|
that list fills the sidebar, which then has no such row, does the line
|
|
1029
1029
|
take a row, the list giving up its last. With the list's focus (`w`) the
|
|
1030
1030
|
focus stays there, the cursor where it was. A workspace with a deployment of this
|
|
1031
|
-
machine not opened yet (
|
|
1031
|
+
machine not opened yet (lab, with `~/Work/lab` on this computer's list)
|
|
1032
1032
|
opens it first, as the switcher's `Enter` does. What the workspace left
|
|
1033
1033
|
had open is kept for it, as for a switch from the
|
|
1034
1034
|
switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
|
|
@@ -1068,9 +1068,9 @@ switcher covers the whole screen.
|
|
|
1068
1068
|
workspaces │ > * acme-platform
|
|
1069
1069
|
│ This machine
|
|
1070
1070
|
Instances 1 │ garnet
|
|
1071
|
-
Souls 2 │
|
|
1071
|
+
Souls 2 │ lab
|
|
1072
1072
|
Capabilities 3 │ This machine · not opened
|
|
1073
|
-
────────────────────────────────────────────────│
|
|
1073
|
+
────────────────────────────────────────────────│ builder (lab)
|
|
1074
1074
|
Ctrl+X commands │ Not matched to a workspace
|
|
1075
1075
|
Ctrl+K palette │ basalt ssh needs a prompt
|
|
1076
1076
|
Enter open │ On this machine, not opened
|
package/docs/upgrading.md
CHANGED
|
@@ -6,11 +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.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.19** ([release notes](release-notes/v0.69.19.md)).
|
|
10
|
+
The 0.69.19 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
|
+
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
11
12
|
|
|
12
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
13
|
-
0.69.
|
|
14
|
+
0.69.19,** in the [release notes](release-notes/): it says what to do before
|
|
14
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
15
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
16
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -19,14 +20,14 @@ prints the version you have.
|
|
|
19
20
|
Then, on each host:
|
|
20
21
|
|
|
21
22
|
```sh
|
|
22
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
23
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.19, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.19 # 1. the CLI
|
|
24
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
25
26
|
oats doctor # 3. in the same deployment
|
|
26
27
|
```
|
|
27
28
|
|
|
28
29
|
The Desktop's installers are the assets of the
|
|
29
|
-
[GitHub Release](https://github.com/
|
|
30
|
+
[GitHub Release](https://github.com/oats-project/oats/releases) of that version
|
|
30
31
|
([OATS Desktop](desktop.md#install)). Then restart the pi sessions that were
|
|
31
32
|
running: a session keeps the bridge it loaded when it started.
|
|
32
33
|
[The steps](#the-steps) says what each step does and why they come in this
|
|
@@ -40,9 +41,12 @@ the version you are upgrading from.
|
|
|
40
41
|
## The steps
|
|
41
42
|
|
|
42
43
|
Upgrading OATS means three things, in this order, on each host, and one
|
|
43
|
-
|
|
44
|
+
more where the Desktop is installed:
|
|
44
45
|
|
|
45
|
-
0. **The Desktop**, where it is installed: the new version's
|
|
46
|
+
0. **The Desktop**, where it is installed: the new version's. Install it
|
|
47
|
+
before the CLI where the Desktop is 0.69.17 or older
|
|
48
|
+
([which goes first](#either-order-works)); with a newer one, either order
|
|
49
|
+
works.
|
|
46
50
|
1. **The CLI** (`@awebai/oats`, the kernel).
|
|
47
51
|
2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
|
|
48
52
|
deployments launch pi with: `oats update`, in each deployment.
|
|
@@ -62,12 +66,21 @@ instances. A pi started outside any instance looks for a global install, an
|
|
|
62
66
|
**A release's own steps are in its notes**, in its `## Upgrade` section.
|
|
63
67
|
This page is the part that is the same for every release.
|
|
64
68
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
69
|
+
<a id="either-order-works"></a>**Either order works**, with a Desktop newer than 0.69.17. Such a Desktop was
|
|
70
|
+
tested with the CLIs of its own minor version, and accepts a newer minor or
|
|
71
|
+
major one: reads, terminals, Spawn, Start, Restart, the colour and the
|
|
72
|
+
background keep working with it, and every other change is held back until
|
|
73
|
+
the Desktop of that version is installed. It says so in one line, in the
|
|
74
|
+
place of the CLI card:
|
|
75
|
+
`This Desktop was tested with oats CLIs up to <X.Y>; the installed CLI is <version>. Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop <version>.`
|
|
76
|
+
A Desktop accepts an older CLI too, down to its floor, so installing it first
|
|
77
|
+
holds nothing back.
|
|
78
|
+
|
|
79
|
+
**A Desktop of 0.69.17 or older still refuses a CLI newer than its own minor
|
|
80
|
+
version:** with the CLI moved first, it lists no instance until it is
|
|
81
|
+
replaced. Where one is installed, step 0 comes first. The CLI can move by two
|
|
82
|
+
commands, the `npm install` and an `oats update` whose plan installs it:
|
|
83
|
+
step 0 comes before either.
|
|
71
84
|
|
|
72
85
|
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
73
86
|
the bridge, never a package. A deployment's capabilities come from the
|
|
@@ -84,12 +97,12 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
|
84
97
|
|
|
85
98
|
`oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
|
|
86
99
|
plan starts with that install, and the bridges move to that same version in
|
|
87
|
-
the same run. So where
|
|
88
|
-
`oats update` too: `oats update --check` shows whether
|
|
89
|
-
install, and runs nothing. When that install is of another minor or major
|
|
100
|
+
the same run. So where a Desktop of 0.69.17 or older is installed, step 0
|
|
101
|
+
comes before such an `oats update` too: `oats update --check` shows whether
|
|
102
|
+
the plan holds that install, and runs nothing. When that install is of another minor or major
|
|
90
103
|
version, the plan says so in one line under its steps, whether or not a
|
|
91
|
-
Desktop is installed: `OATS Desktop
|
|
92
|
-
|
|
104
|
+
Desktop is installed: `An OATS Desktop older than <X.Y> holds actions back with this CLI. Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop <version>. (An OATS Desktop of 0.69.17 or older refuses this CLI until then.)`
|
|
105
|
+
Its second sentence is the Desktop's own notice, word for word.
|
|
93
106
|
|
|
94
107
|
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
95
108
|
older bridge than the one in place:
|
|
@@ -204,6 +217,19 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
204
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
205
218
|
here.
|
|
206
219
|
|
|
220
|
+
- **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
|
|
221
|
+
oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
|
|
222
|
+
`OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
|
|
223
|
+
variable; a non-boolean `identity.e2ee` or `identity.takeOver` is set to
|
|
224
|
+
`true` or `false`. Respawn instances to take the shorter aweb text and the
|
|
225
|
+
workspace and directory modes' extra trees.
|
|
226
|
+
- **[0.69.18](release-notes/v0.69.18.md#upgrade):** from this Desktop on,
|
|
227
|
+
the Desktop and the CLI go in either order (a Desktop of 0.69.17 or older
|
|
228
|
+
still goes first); the catalog pins oats.aweb 1.41.0, oats.okf 6.0.3 and
|
|
229
|
+
oats.framework 1.25.0. Start the host's wake broker before a Codex or
|
|
230
|
+
`delivery: session` home's next start: oats.aweb 1.40.0 and later refuse
|
|
231
|
+
such a home while none runs. Respawn instances to take the new naming and model
|
|
232
|
+
floor texts.
|
|
207
233
|
- **[0.69.17](release-notes/v0.69.17.md#upgrade):** the catalog pins
|
|
208
234
|
oats.okf 6.0.2 and oats.framework 1.24.1; respawn each running
|
|
209
235
|
`oats-engineering-expert` and `oats-product-expert` once after `oats sync`,
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ 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.
|
|
58
|
-
oats.okf: v6.0.
|
|
57
|
+
oats.framework: v1.25.2 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v6.0.3
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
|
@@ -425,7 +425,7 @@ member soul that is the expert in that capability (`oats-okf-expert`,
|
|
|
425
425
|
**OATS's coordination is a member copy of the engineering template.** The
|
|
426
426
|
`oats` repository keeps its own copy of
|
|
427
427
|
[oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
|
|
428
|
-
at template-v3.
|
|
428
|
+
at template-v3.1.3, adapted to OATS: `oats.engineering-expert`,
|
|
429
429
|
`oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
|
|
430
430
|
`oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
|
|
431
431
|
`capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
|
|
@@ -4,9 +4,34 @@ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
|
|
|
4
4
|
checkout or link. The `repo` recorded for you supplies configuration only; it
|
|
5
5
|
grants no permission to edit the `repo` directory.
|
|
6
6
|
|
|
7
|
-
- Work inside `./work
|
|
8
|
-
repository Git discovers is not yours.
|
|
7
|
+
- Work inside `./work`, apart from your extra trees. **Never initialize a
|
|
8
|
+
fake repository**; a containing repository Git discovers is not yours.
|
|
9
|
+
- **Repository work that needs a branch goes in an extra tree of your own**
|
|
10
|
+
(below): a change your role and task call for, or a repository at the
|
|
11
|
+
remote's current state. What work you take on stays your role's and your
|
|
12
|
+
task's call.
|
|
9
13
|
- Use external inputs and destinations only as your task and capabilities
|
|
10
14
|
explicitly authorize.
|
|
11
15
|
- Deliver results through your task's own protocol before you finish: the
|
|
12
16
|
recovery copy kept at retirement is not publication.
|
|
17
|
+
|
|
18
|
+
### Extra trees
|
|
19
|
+
|
|
20
|
+
For a branch of a member repository, from your home (`--preview` first;
|
|
21
|
+
`<repo>`: the member key or clone path, always, since your own `./work` is
|
|
22
|
+
not a Git tree; `<base>`: the remote branch to start from, or the one you
|
|
23
|
+
rework):
|
|
24
|
+
|
|
25
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
|
|
26
|
+
|
|
27
|
+
It moves none of the clone's refs. A tree is yours alone: build, test and
|
|
28
|
+
commit there.
|
|
29
|
+
|
|
30
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
31
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
32
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
33
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
34
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
35
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
36
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
37
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
|
@@ -1,11 +1,37 @@
|
|
|
1
1
|
## Work mode: workspace
|
|
2
2
|
|
|
3
|
-
Your `./work` is the **whole workspace**, not one repository
|
|
4
|
-
|
|
3
|
+
Your `./work` is the **whole workspace**, not one repository: every member
|
|
4
|
+
clone, read through it. What work you take on is your role's and your task's
|
|
5
|
+
call; this block says where it happens.
|
|
5
6
|
|
|
6
|
-
- **Read freely across member repositories
|
|
7
|
-
and NEVER change
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
- **Read freely across member repositories through `./work`; never edit or
|
|
8
|
+
commit there, and NEVER change a member clone's Git state** (no branch
|
|
9
|
+
switches, resets, pulls, stashes, or `git worktree` run by hand). Others
|
|
10
|
+
use those clones.
|
|
11
|
+
- **Work that needs a branch goes in an extra tree of your own** (below): a
|
|
12
|
+
change your role and task call for, or a member at the remote's current
|
|
13
|
+
state. Otherwise route a repository change to that repository's agents or
|
|
14
|
+
to your human.
|
|
10
15
|
- A capability that delivers updates into a repository follows its own
|
|
11
16
|
instructions; that is not an exception you take yourself.
|
|
17
|
+
|
|
18
|
+
### Extra trees
|
|
19
|
+
|
|
20
|
+
For a branch of a member repository, from your home (`--preview` first;
|
|
21
|
+
`<repo>`: the member key or clone path, always, since your own `./work` is
|
|
22
|
+
not a Git tree; `<base>`: the remote branch to start from, or the one you
|
|
23
|
+
rework):
|
|
24
|
+
|
|
25
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
|
|
26
|
+
|
|
27
|
+
It moves none of the clone's refs. A tree is yours alone: build, test and
|
|
28
|
+
commit there.
|
|
29
|
+
|
|
30
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
31
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
32
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
33
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
34
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
35
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
36
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
37
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
package/lib/command-flags.mjs
CHANGED
|
@@ -109,7 +109,7 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
109
109
|
refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
|
|
110
110
|
{ command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
|
|
111
111
|
refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
|
|
112
|
-
usage: "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
|
|
112
|
+
usage: "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
|
|
113
113
|
{ command: "worktree add", operands: [], values: ["--purpose", "--branch", "--base", "--repo"], switches: ["--preview", "--json"], refused: WORKTREE_REFUSED,
|
|
114
114
|
usage: "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]" },
|
|
115
115
|
{ command: "worktree remove", operands: [], values: ["--purpose"], switches: ["--json"], refused: WORKTREE_REFUSED,
|