@awebai/oats 0.56.0 → 0.57.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.
- package/bin/oats.mjs +18 -10
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +11 -4
- package/docs/implementation.md +99 -4
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +136 -25
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/tui/README.md +16 -7
- package/packages/tui/lib/actions.mjs +8 -1
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +91 -13
- package/packages/tui/lib/model.mjs +202 -5
- package/packages/tui/lib/read.mjs +132 -13
- package/packages/tui/lib/store.mjs +110 -4
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +38 -8
- package/packages/tui/lib/views/help.mjs +11 -5
- package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.
|
|
47
|
+
oats.okf: v5.2.0 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.
|
|
51
|
+
- **Bare version** (`v5.2.0`, `5.2.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.
|
|
54
|
+
convention (`v5.2.0` or `oats-framework/v1.10.2`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,8 +74,8 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.10.
|
|
78
|
-
oats.okf: v5.
|
|
77
|
+
oats.framework: v1.10.2
|
|
78
|
+
oats.okf: v5.2.0
|
|
79
79
|
oats.aweb: v1.27.3
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.0 ✓ (@ 2ac86ccb)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.2.0",
|
|
164
|
+
"commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.2", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.10.
|
|
362
|
-
resolves to tag `oats-framework/v1.10.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.10.2`
|
|
362
|
+
resolves to tag `oats-framework/v1.10.2`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# OATS 0.57.0
|
|
2
|
+
|
|
3
|
+
2026-10-15
|
|
4
|
+
|
|
5
|
+
## Upgrade
|
|
6
|
+
|
|
7
|
+
- **Install the Desktop first and the CLI second,** as
|
|
8
|
+
[Upgrading](../upgrading.md) says: a 0.56 Desktop refuses a 0.57.0 CLI. The
|
|
9
|
+
0.57.0 Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`.
|
|
10
|
+
|
|
11
|
+
- **A script that runs `oats worktree remove`** may now get
|
|
12
|
+
`E_CHILDREN_RUNNING`: the tree is the work of an attached instance whose
|
|
13
|
+
session is running or cannot be read. Nothing is removed, and no flag
|
|
14
|
+
removes anyway: stop that instance (`oats instance stop <instance>`) or
|
|
15
|
+
retire it, then remove again. **A script that attaches a spawn to a tree of
|
|
16
|
+
no known instance** gets one `E_BAD_ARGS` naming every flag still missing,
|
|
17
|
+
where it got a repository refusal and then `E_SPAWN_FAILED` on the retry.
|
|
18
|
+
See Changed ([#958](https://github.com/awebai/oats/issues/958),
|
|
19
|
+
[#964](https://github.com/awebai/oats/issues/964)).
|
|
20
|
+
|
|
21
|
+
- **A retire plan taken before the upgrade** is refused once by the 0.57.0
|
|
22
|
+
kernel with `E_PLAN_STALE` and the fresh plan: the plan's revision now also
|
|
23
|
+
binds the instances attached to each tree. Read the fresh plan and retire
|
|
24
|
+
with it. See Changed ([#964](https://github.com/awebai/oats/issues/964)).
|
|
25
|
+
|
|
26
|
+
- **On Linux and Windows the Desktop's palette is Ctrl+Shift+K,** and
|
|
27
|
+
Ctrl+Shift+P now opens Quick Open, from a focused terminal too. macOS keeps
|
|
28
|
+
⌘K and ⌘P. See Changed
|
|
29
|
+
([#1217](https://github.com/awebai/oats/issues/1217)).
|
|
30
|
+
|
|
31
|
+
- **To get the new provider versions,** pin `oats.framework: v1.10.2` and
|
|
32
|
+
`oats.okf: v5.2.0` in your workspace and run `oats sync`. Instances already
|
|
33
|
+
running keep what they were spawned with. See Provider updates.
|
|
34
|
+
|
|
35
|
+
- **Pin `oats.okf: v5.2.0` and run `oats sync`; only new spawns get the
|
|
36
|
+
capability-owned harvest duty.** Existing homes keep their copied provider
|
|
37
|
+
and instructions, including across session restarts. Deployments whose
|
|
38
|
+
task briefings never mentioned harvests now propose eligible knowledge at
|
|
39
|
+
finished tasks or PR hand-overs. Souls not ready for that must declare
|
|
40
|
+
`knowledge: { harvest: off }`; consultation and working-memory upkeep
|
|
41
|
+
remain. OATS >=0.49.0 is still required.
|
|
42
|
+
|
|
43
|
+
- **The official catalog's versions in this release** are oats.framework
|
|
44
|
+
1.10.2, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
|
|
45
|
+
oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
|
|
46
|
+
and oats.apps 1.0.0.
|
|
47
|
+
|
|
48
|
+
## Added
|
|
49
|
+
|
|
50
|
+
- **`oats tui` stops, starts, restarts and retires an agent**
|
|
51
|
+
([#855](https://github.com/awebai/oats/issues/855)). With an instance
|
|
52
|
+
selected, `X` stops it, `D` retires it, `S` starts it and `R` restarts it,
|
|
53
|
+
each after a confirmation that opens with the focus on `Cancel`: the act
|
|
54
|
+
takes a move (`Left`/`Right` or `Tab`) and a press of `Enter`, and pasted
|
|
55
|
+
text never acts. The rules and the words are the Desktop's: a stop or a
|
|
56
|
+
retire shows the kernel's plan first and applies exactly that plan, on
|
|
57
|
+
this machine or on a registered one; a start or a restart uses the launch
|
|
58
|
+
recorded for the agent. An act you sent runs to its end whatever
|
|
59
|
+
`oats tui` does: closing the confirmation, quitting, a suspend or a signal
|
|
60
|
+
never ends it, and when you leave while one runs a line on standard error
|
|
61
|
+
says so. `tui.json` changes the keys (`stop`, `retire`, `start`,
|
|
62
|
+
`restart`). See [the TUI page](../tui.md#stopping-starting-restarting-and-retiring).
|
|
63
|
+
|
|
64
|
+
- **Desktop: each team has its own page, with your instances on it.** Click
|
|
65
|
+
a card under Workspace › Teams, or press Enter on its name, to open it. The
|
|
66
|
+
page shows the team's card at the top (its default, description, who may
|
|
67
|
+
join, address, problems and actions), then **Your instances on this team**:
|
|
68
|
+
how many there are, how many run, how many are stopped or need attention,
|
|
69
|
+
and on how many machines. Below that, each machine gets a card, with a
|
|
70
|
+
table of its instances: the name, the soul, the state, when it was created
|
|
71
|
+
and a Terminal button when it can be opened. A click on the name shows the
|
|
72
|
+
instance in the roster. The page lists only your instances, the ones on
|
|
73
|
+
this computer and on the machines you added to this workspace. Instances
|
|
74
|
+
other people run on the team are not listed. Back or Esc returns to the
|
|
75
|
+
board, on that team's card.
|
|
76
|
+
|
|
77
|
+
## Changed
|
|
78
|
+
|
|
79
|
+
- **The Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`**
|
|
80
|
+
([#1211](https://github.com/awebai/oats/issues/1211)). The compatibility band
|
|
81
|
+
admits 0.57; a 0.56 Desktop refuses a 0.57 CLI. No new gate on the band.
|
|
82
|
+
`oats tui` runs the kernel it ships with and is held to the same band.
|
|
83
|
+
|
|
84
|
+
- **Desktop on Linux and Windows: the palette is Ctrl+Shift+K, and Quick Open
|
|
85
|
+
is Ctrl+Shift+P and works from a focused terminal**
|
|
86
|
+
([#1217](https://github.com/awebai/oats/issues/1217)). Quick Open was
|
|
87
|
+
Ctrl+P, which a focused terminal keeps for the program in it (shell
|
|
88
|
+
history), so it did not open from there. **Ctrl+Shift+P changes meaning:**
|
|
89
|
+
it has opened the palette since 0.30.3 and now opens Quick Open; the
|
|
90
|
+
palette moves to Ctrl+Shift+K. While the palette is open, Ctrl+Shift+K
|
|
91
|
+
moves down its rows and ArrowUp moves up. xterm sends nothing for either
|
|
92
|
+
chord, so plain Ctrl+K and Ctrl+P still reach the program. A shortcut you
|
|
93
|
+
set yourself is kept; when it is one of these two chords, the shortcuts
|
|
94
|
+
editor shows the clash. A Quick Open shortcut you set yourself now works
|
|
95
|
+
from a terminal too: if it is a plain Ctrl+letter, such as Ctrl+P, the
|
|
96
|
+
program no longer gets that key, so choose a Ctrl+Shift chord. macOS is
|
|
97
|
+
unchanged (⌘K, ⌘P). See
|
|
98
|
+
[Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
|
|
99
|
+
|
|
100
|
+
- **An attached spawn on an extra tree derives its owner and its repository
|
|
101
|
+
(#958).** `oats spawn <soul> --work attached --work-dir
|
|
102
|
+
<home>/.work-<purpose>` was refused twice: first for the repository
|
|
103
|
+
(`pass --repo`), then, with that given, for the owner (`--parent
|
|
104
|
+
<instance>`). For `<home>/work` the kernel derived both. An extra tree of
|
|
105
|
+
a home is that home's tree too, so the same command now spawns with
|
|
106
|
+
neither flag: the owner is the instance in whose home the tree is, the new
|
|
107
|
+
instance is its child, and its repository is the repository of the tree
|
|
108
|
+
it is attached to (for an extra tree the one Git names for it, which can
|
|
109
|
+
be another member repository than the owner's own). `--parent <owner>`
|
|
110
|
+
and `--repo` given explicitly still work, so a command that passes both
|
|
111
|
+
runs on this kernel and on earlier ones. The tree is an extra tree by the
|
|
112
|
+
kernel's own test (a registered linked worktree in a home), never by the
|
|
113
|
+
shape of its path. Nothing changes for `<home>/work`, and no flag, key or
|
|
114
|
+
field changes.
|
|
115
|
+
|
|
116
|
+
A tree of no known instance still needs both flags. Its refusal is now
|
|
117
|
+
one, `E_BAD_ARGS`, and names every flag still missing: `attached workDir
|
|
118
|
+
<path> is not a known instance's <home>/work or an extra tree of a known
|
|
119
|
+
instance's home (<home>/.work-<purpose>), so neither its owner nor its
|
|
120
|
+
repository is derived — pass both: --parent <instance> (the owning
|
|
121
|
+
instance) and --repo <repository>`. With one of the two given it names
|
|
122
|
+
the other. Before, the missing repository was refused first (`no
|
|
123
|
+
repository for a attached instance — pass --repo (the work tree's owner
|
|
124
|
+
records none)`), and the missing owner only on the retry, under the code
|
|
125
|
+
`E_SPAWN_FAILED`. See
|
|
126
|
+
[`attached`](../souls-and-instances.md#attached--another-instances-tree).
|
|
127
|
+
|
|
128
|
+
- **A tree that goes away says what it leaves its attached instances with
|
|
129
|
+
(#964).** An instance can be attached to an extra tree of its owner as to
|
|
130
|
+
the owner's `work/` (#958). Four things change for such a tree:
|
|
131
|
+
|
|
132
|
+
- **A retire that re-homes an extra tree repoints its attached children**
|
|
133
|
+
to the tree's new path, as it does for `work/`: only the recorded
|
|
134
|
+
children the retire stopped, only once the tree is seen at its new path
|
|
135
|
+
with nothing left at the old one, and only a link that is still the one
|
|
136
|
+
the retire found. One that cannot be repointed is a warning in the
|
|
137
|
+
receipt, with the command to do it by hand.
|
|
138
|
+
- **A retire that removes a tree names the attached children it leaves
|
|
139
|
+
without one.** A clean extra tree is removed, as before, and so is
|
|
140
|
+
`work/` with `--discard-worktree`. The plan's note for the tree now
|
|
141
|
+
names its attached children and says that their `work` link would then
|
|
142
|
+
point at a path that is gone, and the receipt's `warnings` (and the
|
|
143
|
+
summary) say so afterwards, naming each child, the tree and the link.
|
|
144
|
+
Before, the plan and the receipt said nothing of them.
|
|
145
|
+
- **An attached instance the retire does not act on is named too.** An
|
|
146
|
+
instance that records the owner as its parent under a name that is not
|
|
147
|
+
unique is listed under the plan's `ambiguous` and is never stopped, so
|
|
148
|
+
its link is not repointed either. The plan's note for the tree it is
|
|
149
|
+
attached to (an extra tree, or `work/`) now names it and says that its
|
|
150
|
+
`work` link would then point at a path that is gone, and the receipt's
|
|
151
|
+
`warnings` say so for each tree that was moved or removed, with the
|
|
152
|
+
command to repoint the link by hand where the tree was re-homed. A
|
|
153
|
+
`--self` retirement's receipt does not carry those warnings.
|
|
154
|
+
- **`oats worktree remove` refuses a tree under a running session.** When
|
|
155
|
+
an instance attached to the tree has a session that is running, or that
|
|
156
|
+
cannot be read, the command answers `E_CHILDREN_RUNNING` before Git is
|
|
157
|
+
asked anything: nothing is removed and the record is kept. `details` is
|
|
158
|
+
`{purpose, path, children: [{instance, home, session}]}`, `session` being
|
|
159
|
+
`"running"` or `"unknown"`. The message names each instance and the
|
|
160
|
+
step: stop it (`oats instance stop <instance>`) or retire it, then remove
|
|
161
|
+
again. The command stops nobody, and no flag removes the tree anyway. An
|
|
162
|
+
attached instance whose session is stopped does not refuse: the tree is
|
|
163
|
+
removed and the answer's `warnings` name the instance and its link.
|
|
164
|
+
|
|
165
|
+
The new sentences are strings in arrays the plan and the answers already
|
|
166
|
+
have (`notes`, `warnings`): no key, field or flag is new, and a tree with
|
|
167
|
+
no attached instance is handled as before. `E_CHILDREN_RUNNING` is the code
|
|
168
|
+
a retire already answers, there for a child it asked to stop and that did
|
|
169
|
+
not; `oats worktree remove` answers it with `details` of its own and no
|
|
170
|
+
`childrenStopped`. See
|
|
171
|
+
[extra trees at retire](../souls-and-instances.md#extra-trees-at-retire)
|
|
172
|
+
and [extra trees](../souls-and-instances.md#extra-trees).
|
|
173
|
+
|
|
174
|
+
- **Desktop: the Workspace › Setup tab reads as one column.** The List view
|
|
175
|
+
puts what the workspace shares through Git above what lives only on this
|
|
176
|
+
computer. It shows the same facts as before.
|
|
177
|
+
- **Under the workspace's name**, a summary counts the members (and those
|
|
178
|
+
that need attention), the packages and the state of the lock. The line
|
|
179
|
+
under it says where the workspace is declared, for example "Declared in
|
|
180
|
+
agents's oats-workspace.yaml at 1a2b3c4."
|
|
181
|
+
- **An Overview** says that the host repository defines the workspace: its
|
|
182
|
+
members and its packages. **For developers**, folded, explains the two
|
|
183
|
+
links that make a repository a member: the host's workspace file lists
|
|
184
|
+
it, and its membership file names the workspace back. It also says what
|
|
185
|
+
each member state means. The Graph view shows the Overview too. The
|
|
186
|
+
legend of badges is gone.
|
|
187
|
+
- **Shared through Git** holds Members, Packages and Defaults. Only the
|
|
188
|
+
host's row carries a tag, **Host** with its workspace file; the Member
|
|
189
|
+
tag is gone from every row. A confirmed member shows a check and
|
|
190
|
+
"confirmed". Any other state keeps its warning chip. In a wide enough
|
|
191
|
+
window every row takes one line.
|
|
192
|
+
- **This computer** holds the deployment's folder, settings, lock, lock
|
|
193
|
+
file, CLI, instances and disabled souls, then the member clones, then the
|
|
194
|
+
Machines box. Instances reads "3, 1 running". The Machines box no longer
|
|
195
|
+
carries a "Not shared" tag; the zone says it.
|
|
196
|
+
- **The Graph view** labels read "Shared through Git", "Members, latest"
|
|
197
|
+
and "Packages, pinned", in sentence case.
|
|
198
|
+
|
|
199
|
+
- **Desktop: the Teams board is one calm column.** Shared teams, local teams
|
|
200
|
+
and which teams each soul may join each have a heading and one line saying
|
|
201
|
+
what they are. A team's card no longer lists its instances: it shows the
|
|
202
|
+
team's facts in labelled rows (Default for, May join, Address), any
|
|
203
|
+
warning with its fix, and a summary line at the bottom ("3 of your
|
|
204
|
+
instances, 1 on other machines"). A click anywhere on the card opens the
|
|
205
|
+
team's page, and each card is one Tab stop. Which teams each soul may join
|
|
206
|
+
is now a table: the pattern, its default team, and the other teams it may
|
|
207
|
+
also join. The type is calmer: fewer sizes and styles, no uppercase labels,
|
|
208
|
+
and the facts that matter stand out by size and weight, not by new colours.
|
|
209
|
+
|
|
210
|
+
## Fixed
|
|
211
|
+
|
|
212
|
+
- **Released in 0.56.0, not noted there: the Desktop's terminals draw again
|
|
213
|
+
after a GPU process restart
|
|
214
|
+
([#1190](https://github.com/awebai/oats/issues/1190), #1192).** After the GPU
|
|
215
|
+
process restarted, xterm's shared glyph store went stale and terminals
|
|
216
|
+
stopped drawing. They now draw again. A 0.56.0 or later Desktop has the
|
|
217
|
+
fix.
|
|
218
|
+
|
|
219
|
+
- **A retire's recovery of a worktree carries a stopped cherry-pick, revert,
|
|
220
|
+
rebase or merge, and the stash, in both ref formats
|
|
221
|
+
([#1038](https://github.com/awebai/oats/issues/1038)).** The recovery
|
|
222
|
+
copied an operation's state as files of the Git directory. Three things
|
|
223
|
+
were missing from it, and nothing said so:
|
|
224
|
+
- where the repository stores its refs in the reftable format,
|
|
225
|
+
`CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD` and `AUTO_MERGE` are not
|
|
226
|
+
files. The recovery had none of them, and its `git status` no longer said
|
|
227
|
+
a cherry-pick or a revert was in progress. The stash's log is not a file
|
|
228
|
+
there either: the recovery's `git stash list` was empty;
|
|
229
|
+
- in both formats, the commit or tree those refs and `MERGE_HEAD` name is
|
|
230
|
+
often in no branch (a commit reset away, a conflict's tree). The recovery
|
|
231
|
+
named it without holding it, so `git cherry-pick --continue`, `git merge
|
|
232
|
+
--continue` or a diff against `AUTO_MERGE` failed there;
|
|
233
|
+
- a link at one of the copied names was left out when it led nowhere.
|
|
234
|
+
|
|
235
|
+
The recovery now writes those four refs through Git at the same ids and
|
|
236
|
+
holds every object they and `MERGE_HEAD` name. It stores the stash's
|
|
237
|
+
entries again, oldest first, with their messages, so `git stash list`
|
|
238
|
+
reads the same. A link is copied as the same link. A ref the source holds
|
|
239
|
+
in the reftable format without its object cannot be written, and refuses
|
|
240
|
+
the retire with `E_WORK_PRESERVATION_FAILED`, the home kept, as any
|
|
241
|
+
recovery that cannot be made does. Which homes a retire recovers, the
|
|
242
|
+
receipt and every code are unchanged.
|
|
243
|
+
|
|
244
|
+
## Provider updates
|
|
245
|
+
|
|
246
|
+
- **oats.okf 5.2.0:** the IMPORTANT inject block requires current instance
|
|
247
|
+
knowledge and compulsory reading of `okf-propose`. The skill holds the
|
|
248
|
+
bounded checkpoint procedure, promotion/search checks, proposal format and
|
|
249
|
+
memory/concurrency gates. No harvest or proposal direction remains in the
|
|
250
|
+
working instance's TASK brief. At most one proposal per completed task or
|
|
251
|
+
PR hand-over, one harvester per instance, and no spawn under memory pressure
|
|
252
|
+
or below 8 GB available; most checkpoints propose nothing. An unrelated
|
|
253
|
+
harvester can outlive its proposer. These limits are instructions, not a
|
|
254
|
+
scheduler or resource reservation.
|
|
255
|
+
- `oats okf status` exposes the duty written by the provider at spawn (`on`,
|
|
256
|
+
`off`, or missing-state `unknown`). An unknown answer or failure permits no
|
|
257
|
+
proposal. Shared inject/skill text explicitly exempts opted-out souls, and
|
|
258
|
+
the harvester independently refuses their recorded source material. No
|
|
259
|
+
kernel composition mechanism is added.
|
|
260
|
+
|
|
261
|
+
- **oats.framework 1.10.2: oats.core 2.6.1 and oats.setup 2.5.4.**
|
|
262
|
+
Instruction text in two skills; no hook, command, schema or provider
|
|
263
|
+
contract changes, and the capability floors are unchanged (oats.core
|
|
264
|
+
`>=0.40.0`, oats.setup `>=0.30.0`).
|
|
265
|
+
- `oats-operate` (oats.core) says that from OATS 0.57.0 `oats worktree
|
|
266
|
+
remove` refuses a tree that is the work of an attached instance whose
|
|
267
|
+
session is running or cannot be read (`E_CHILDREN_RUNNING`): stop that
|
|
268
|
+
instance or retire it, then remove again, as the entry under Changed
|
|
269
|
+
says ([#964](https://github.com/awebai/oats/issues/964)).
|
|
270
|
+
- `oats-onboarding` (oats.setup) pins `oats.okf: v5.2.0` in its knowledge
|
|
271
|
+
section and describes the harvest duty that oats.okf 5.2.0 gives every
|
|
272
|
+
working soul: the compulsory `okf-propose` skill, `oats okf status`, and
|
|
273
|
+
the soul's own opt-out, as the oats.okf entry says.
|
|
274
|
+
- A deployment gets it by pinning `oats.framework: v1.10.2` and running
|
|
275
|
+
`oats sync`. Instances already running keep the skills they were spawned
|
|
276
|
+
with; new spawns get the new ones.
|
|
277
|
+
|
|
278
|
+
## Documentation
|
|
279
|
+
|
|
280
|
+
- [Knowledge operations](../knowledge.md#the-flow) now describes the
|
|
281
|
+
capability-owned flow, opt-out/status answer, narrow checkpoints and
|
|
282
|
+
deferred hand-back. Catalog/workspace pins, package examples, mirrors and
|
|
283
|
+
clean-room composition assertions move together to 5.2.0.
|
package/docs/schedules.md
CHANGED
|
@@ -841,9 +841,14 @@ fails, the spawn result still carries the instance receipt, plus
|
|
|
841
841
|
|
|
842
842
|
## Knowledge harvest and review
|
|
843
843
|
|
|
844
|
-
**oats.okf 5.
|
|
845
|
-
|
|
846
|
-
|
|
844
|
+
**oats.okf 5.x does not schedule harvest jobs.** In 5.2 the capability's
|
|
845
|
+
IMPORTANT inject and compulsory `okf-propose` skill give the duty, not TASK.md.
|
|
846
|
+
A working instance keeps its notes current, checks `oats okf status`, and at
|
|
847
|
+
a finished task or PR hand-over proposes only durable, non-duplicate claims.
|
|
848
|
+
At most one proposal per completed unit of work, one harvester at a time,
|
|
849
|
+
and no spawn under memory pressure or below 8 GB available; otherwise defer
|
|
850
|
+
and hand back the pending claims. Most checkpoints propose nothing. When the
|
|
851
|
+
skill's gates pass, the instance directly spawns the package harvester:
|
|
847
852
|
|
|
848
853
|
```sh
|
|
849
854
|
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
|
@@ -402,7 +402,9 @@ sugar for `--relative-to <instance> --relation child`):
|
|
|
402
402
|
`oats status --json` (`parentInstance` + `siblingInstance` edges).
|
|
403
403
|
- **unrelated** (default): no link, operator-origin, top-level.
|
|
404
404
|
|
|
405
|
-
Attached-mode spawns are ALWAYS children of the owner of the shared work tree
|
|
405
|
+
Attached-mode spawns are ALWAYS children of the owner of the shared work tree
|
|
406
|
+
(the instance in whose home the tree is, as its `work/` or as one of its
|
|
407
|
+
extra trees: see [`attached`](#attached--another-instances-tree)),
|
|
406
408
|
because an attached agent serves that owner; relation flags other than a
|
|
407
409
|
redundant child-of-owner are rejected. Any other spawn, including one from a
|
|
408
410
|
shell that inherited an agent's environment variables, is operator-origin and
|
|
@@ -554,8 +556,16 @@ parses it, so it copies the files Git reads:
|
|
|
554
556
|
- what the copy takes from the Git directories as files, each with its bytes
|
|
555
557
|
and its permission bits: the state of an operation in progress (a merge, a
|
|
556
558
|
rebase, a cherry-pick, a revert, a bisect), `info/attributes` and the
|
|
557
|
-
stash's log
|
|
558
|
-
|
|
559
|
+
stash's log. A link at one of the operation's entries is copied as the same
|
|
560
|
+
link, also one that leads nowhere;
|
|
561
|
+
- the refs an operation leaves that are not files where the refs are stored
|
|
562
|
+
in the reftable format: `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`
|
|
563
|
+
and `AUTO_MERGE`, each written into the copy through Git at the same object
|
|
564
|
+
id. The copy itself always stores its refs as files, whatever format the
|
|
565
|
+
operator's Git configuration or environment gives a new repository;
|
|
566
|
+
- its tags and its stash. Where the stash's log is not a file (the reftable
|
|
567
|
+
format), its entries are read through Git and stored again in the copy,
|
|
568
|
+
oldest first, each with its message, so `git stash list` reads the same;
|
|
559
569
|
- its exclude rules (`core.excludesFile` with the file the copy reads for it,
|
|
560
570
|
and `info/exclude`) and the settings that change what `git status` reports
|
|
561
571
|
(`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
|
|
@@ -708,7 +718,11 @@ Git in the recovery. Set by hand in the recovery only what you trust.
|
|
|
708
718
|
**Every object the copy's Git metadata names is in it.** For the worktree's
|
|
709
719
|
copy and for each nested repository's alike, the copier collects what the
|
|
710
720
|
Git metadata it carries names: every commit the stash's log names (the new
|
|
711
|
-
id of each entry, as `git log -g refs/stash` shows them),
|
|
721
|
+
id of each entry, as `git log -g refs/stash` shows them), the commit each of
|
|
722
|
+
`CHERRY_PICK_HEAD`, `REVERT_HEAD` and `REBASE_HEAD` names, every commit
|
|
723
|
+
`MERGE_HEAD` names (one per line), and the tree `AUTO_MERGE` names with the
|
|
724
|
+
trees and blobs under it that the copy lacks (a conflict's files are in no
|
|
725
|
+
commit), whether the copy took the ref as a file or wrote it, for a nested
|
|
712
726
|
repository the commit of each of its local branches (its own `refs/heads`,
|
|
713
727
|
including a branch its configuration hides from a clone) and every commit
|
|
714
728
|
its `HEAD` and branch reflogs name, and every blob
|
|
@@ -719,8 +733,12 @@ the missing blobs by content (a staged blob or a resolved conflict's side
|
|
|
719
733
|
can be in no commit), then checks the whole set again. An object the
|
|
720
734
|
source cannot supply (a partial clone that lacks it: the retire never
|
|
721
735
|
fetches from a promisor remote) refuses the copy with
|
|
722
|
-
`E_WORK_PRESERVATION_FAILED`, naming it.
|
|
723
|
-
|
|
736
|
+
`E_WORK_PRESERVATION_FAILED`, naming it. An operation's ref that names an
|
|
737
|
+
object the source itself lacks is copied as it is and names nothing in the
|
|
738
|
+
copy either; where that ref must be written (the reftable format), Git
|
|
739
|
+
refuses to write it, and so the copy is refused. So `git stash show
|
|
740
|
+
stash@{2}`, `git checkout -m <path>` and `git cherry-pick --continue` work in
|
|
741
|
+
the copy as in the source. What the copier
|
|
724
742
|
cannot carry at all (an entry that is not a file, a directory or a symbolic
|
|
725
743
|
link, or a nested repository whose path is not valid UTF-8) refuses the copy,
|
|
726
744
|
here as anywhere.
|
|
@@ -1220,10 +1238,14 @@ retry. A relink that fails is a warning in the summary and the receipt's
|
|
|
1220
1238
|
`warnings`, with the command to repoint the link by hand; the retire is not
|
|
1221
1239
|
undone. A child that is not attached, whose link leads elsewhere, or that this
|
|
1222
1240
|
retire did not stop is not touched. With `--discard-worktree` the worktree is
|
|
1223
|
-
removed and an attached child's link
|
|
1224
|
-
|
|
1241
|
+
removed and an attached child's link then points at a path that is gone: the
|
|
1242
|
+
summary and the receipt's `warnings` name each such child, the tree and the
|
|
1243
|
+
link. The retire plan names the attached children in one note that covers
|
|
1244
|
+
both cases. Only the link changes:
|
|
1225
1245
|
the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
|
|
1226
|
-
still name the old path.
|
|
1246
|
+
still name the old path. A child attached to one of the home's extra trees
|
|
1247
|
+
is handled the same way, tree by tree
|
|
1248
|
+
([extra trees at retire](#extra-trees-at-retire)).
|
|
1227
1249
|
|
|
1228
1250
|
#### What `work/` is at retire
|
|
1229
1251
|
|
|
@@ -1370,6 +1392,38 @@ leaves `work/` untouched. For each tree:
|
|
|
1370
1392
|
handled, and the message says what was done. `--force` does not bypass it:
|
|
1371
1393
|
it forces past hook cleanup, not past local work.
|
|
1372
1394
|
|
|
1395
|
+
An instance can be attached to an extra tree as it can to `work/`
|
|
1396
|
+
([`attached`](#attached--another-instances-tree)). The retire finds the
|
|
1397
|
+
attached children of every tree before it moves or removes any of them, among
|
|
1398
|
+
the recorded children it stopped and by the test it uses for `work/`:
|
|
1399
|
+
|
|
1400
|
+
- **Where the tree is re-homed**, each one's `work` link is repointed to the
|
|
1401
|
+
tree's new path, under the conditions `work/` has (the tree is seen at its
|
|
1402
|
+
new path, nothing is left at the old one, and the child's link is still the
|
|
1403
|
+
one that was found) and with the same warnings when it cannot be done. It
|
|
1404
|
+
is done right after that tree's move, not at the end of the retire: a later
|
|
1405
|
+
step can still refuse and keep the home, and the tree has left it either
|
|
1406
|
+
way.
|
|
1407
|
+
- **Where a clean tree is removed**, it is removed as any other, and the
|
|
1408
|
+
child's link then points at a path that is gone. The receipt's `warnings`
|
|
1409
|
+
and the summary name each such child, the tree and the link.
|
|
1410
|
+
|
|
1411
|
+
The plan's note for a tree names its attached children and says which of the
|
|
1412
|
+
two the retire would do. A retire that refuses after it has handled trees
|
|
1413
|
+
says, with the trees it handled, each warning it has about their attached
|
|
1414
|
+
children.
|
|
1415
|
+
|
|
1416
|
+
All of this is about the recorded children, for `work/` too. An attached
|
|
1417
|
+
instance that the plan lists under `ambiguous` (it records this instance as
|
|
1418
|
+
its parent under a name that is not unique) is not asked to stop, so the
|
|
1419
|
+
retire does not repoint its link, which then points at the path the tree
|
|
1420
|
+
has left. The retire says so. The plan's note for an extra tree names such
|
|
1421
|
+
instances in a clause of its own, and `work/` has a note of its own for
|
|
1422
|
+
them. The receipt's `warnings` name each one for every tree the retire moved
|
|
1423
|
+
or removed, with the command to repoint its link by hand where the tree was
|
|
1424
|
+
re-homed. The receipt of a `--self` retirement does not carry those
|
|
1425
|
+
warnings; its plan's notes are the same.
|
|
1426
|
+
|
|
1373
1427
|
`--discard-worktree` applies to `work/` only: a tree that is not clean is
|
|
1374
1428
|
always re-homed. The retire writes one workspace event per handled tree
|
|
1375
1429
|
(`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
|
|
@@ -1598,16 +1652,56 @@ Rules:
|
|
|
1598
1652
|
### `attached` — another instance's tree
|
|
1599
1653
|
|
|
1600
1654
|
`work/` points at **another instance's work tree** — same branch, same
|
|
1601
|
-
uncommitted state. Spawning attached requires `workDir` (
|
|
1602
|
-
instance's `<home>/work`
|
|
1603
|
-
|
|
1655
|
+
uncommitted state. Spawning attached requires `workDir` (`--work-dir`): a
|
|
1656
|
+
tree in the owning instance's home, its `<home>/work` or one of its
|
|
1657
|
+
[extra trees](#extra-trees) (`<home>/.work-<purpose>`). It is a spawn-time
|
|
1658
|
+
choice (`--work attached`) for service agents such as reviewers.
|
|
1659
|
+
|
|
1660
|
+
The kernel derives the owner and the repository from the tree named on the
|
|
1661
|
+
command line, so the spawn needs no `--repo` and no relation flag (an extra
|
|
1662
|
+
tree from 0.57.0, #958):
|
|
1663
|
+
|
|
1664
|
+
```text
|
|
1665
|
+
oats spawn <soul> --work attached --work-dir <home>/work
|
|
1666
|
+
oats spawn <soul> --work attached --work-dir <home>/.work-<purpose>
|
|
1667
|
+
```
|
|
1668
|
+
|
|
1669
|
+
- **The owner** is the instance in whose home the tree is, and the new
|
|
1670
|
+
instance is its child. It must be an instance of the deployment the spawn
|
|
1671
|
+
runs in, and its name must resolve back to that home from there: a name
|
|
1672
|
+
that resolves to another instance is refused, since the parent link would
|
|
1673
|
+
be ambiguous. The parent is never read from the caller's environment.
|
|
1674
|
+
- **An attached instance's repository is the repository of the tree it is
|
|
1675
|
+
attached to.** For `<home>/work` that is the repository its owner
|
|
1676
|
+
recorded. For an extra tree it is the repository Git names for that tree,
|
|
1677
|
+
which can be another member repository than the owner's own
|
|
1678
|
+
(`oats worktree add --repo`).
|
|
1679
|
+
- `--parent <owner>` and `--repo <repository>` given explicitly are
|
|
1680
|
+
accepted. A relation that is not "child of the owner" is refused.
|
|
1681
|
+
- An extra tree is one by the kernel's test of it, the same one a retire
|
|
1682
|
+
uses ([extra trees at retire](#extra-trees-at-retire)): a linked worktree
|
|
1683
|
+
in the home that Git confirms is registered in a repository outside the
|
|
1684
|
+
home. The shape of the path decides nothing. A directory named `.work-x`
|
|
1685
|
+
that is not such a tree (a plain directory, a clone of its own, a tree of
|
|
1686
|
+
a repository inside the home, a tree whose registration was pruned) is a
|
|
1687
|
+
tree of no instance, and so is a path inside an extra tree.
|
|
1688
|
+
- **A tree of no known instance** (an integration worktree, for example)
|
|
1689
|
+
has nothing to derive from: the spawn needs `--parent <instance>` and
|
|
1690
|
+
`--repo <repository>`. One refusal (`E_BAD_ARGS`) names every one still
|
|
1691
|
+
missing, so one retry is enough.
|
|
1604
1692
|
|
|
1605
1693
|
Attached agents are guests: never switch branches or rewrite history, touch
|
|
1606
1694
|
only what the briefing names, keep commits small and attributable. Retiring
|
|
1607
1695
|
an attached instance never removes the shared tree. When its owner retires
|
|
1608
|
-
and the tree is re-homed,
|
|
1609
|
-
|
|
1610
|
-
|
|
1696
|
+
and the tree is re-homed, `work/` or an extra tree, the `work` link of an
|
|
1697
|
+
instance attached to it is repointed to the tree's new path
|
|
1698
|
+
([retire](#retire), [extra trees at retire](#extra-trees-at-retire)); its
|
|
1699
|
+
AGENTS.md and TASK.md still name the old one. When the retire removes the
|
|
1700
|
+
tree (a clean extra tree, or `work/` with `--discard-worktree`), the link
|
|
1701
|
+
then points at a path that is gone: the plan says so beforehand and the
|
|
1702
|
+
receipt's `warnings` afterwards, each naming the instance and the tree. The
|
|
1703
|
+
owner's `oats worktree remove` does not remove an extra tree while an
|
|
1704
|
+
instance attached to it is running ([extra trees](#extra-trees)). The packaged
|
|
1611
1705
|
`work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
|
|
1612
1706
|
|
|
1613
1707
|
### `directory` — independent execution
|
|
@@ -1773,6 +1867,23 @@ and nothing is removed. On a `creating` record whose process is gone, `remove`
|
|
|
1773
1867
|
completes the rollback instead. Its answer then says whether the branch was
|
|
1774
1868
|
kept (`branchKept`, `branchKeptReason`).
|
|
1775
1869
|
|
|
1870
|
+
`remove` does not remove a tree under a running session. An instance is
|
|
1871
|
+
attached to the tree when its `instance.json` says `work: "attached"` and its
|
|
1872
|
+
`work` is a link to it ([`attached`](#attached--another-instances-tree)).
|
|
1873
|
+
When such an instance's session is running, or cannot be read, `remove`
|
|
1874
|
+
refuses with `E_CHILDREN_RUNNING` before it asks Git anything: nothing is
|
|
1875
|
+
removed and the record is kept. The message names each such instance and
|
|
1876
|
+
what was seen (an unread session is not called running), and gives the step:
|
|
1877
|
+
stop it (`oats instance stop <instance>`) or retire it, then run `remove`
|
|
1878
|
+
again. `remove` stops nobody, and no flag removes the tree anyway. An
|
|
1879
|
+
attached instance whose session is stopped does not refuse: the tree is
|
|
1880
|
+
removed, and the answer's `warnings` name the instance and its `work` link,
|
|
1881
|
+
which then points at a path that is gone. The instances looked at are the
|
|
1882
|
+
recorded children of the tree's owner, as its retire plan lists them, and
|
|
1883
|
+
those the plan lists as `ambiguous` (they record the owner as their parent
|
|
1884
|
+
under a name that is not unique): the link makes an instance attached, not
|
|
1885
|
+
its lineage. A tree that is already gone from disk is not checked.
|
|
1886
|
+
|
|
1776
1887
|
**Working in the tree.**
|
|
1777
1888
|
|
|
1778
1889
|
- `git switch` needs Git 2.23 or later.
|