@awebai/oats 0.69.12 → 0.69.15
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 +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/docs/schedules.md
CHANGED
|
@@ -31,6 +31,10 @@ while the machine slept are skipped, never replayed; there are no retries and
|
|
|
31
31
|
no queue. A schedule on a registered server keeps running while your laptop
|
|
32
32
|
sleeps.
|
|
33
33
|
|
|
34
|
+
A host with neither launchd nor a systemd user manager (a container) has no
|
|
35
|
+
timer: there `oats host run`, a foreground process, runs the same tick at
|
|
36
|
+
second 0 of every minute ([Without a host timer](#without-a-host-timer)).
|
|
37
|
+
|
|
34
38
|
The design is in the
|
|
35
39
|
[knowledge-operations design record](design/2026-09-26-okf-knowledge-operations.md#23-triggers)
|
|
36
40
|
(§2.3 and §2.3a).
|
|
@@ -41,12 +45,100 @@ The design is in the
|
|
|
41
45
|
| --- | --- |
|
|
42
46
|
| `<deployment>/oats-schedules.json` | This machine's local definitions, `{version: 1, jobs: {<id>: …}}`, local triggers included (`kind: "trigger"`). |
|
|
43
47
|
| `<deployment>/.agents/automations/snapshot.json` | The workspace definitions discovered from the members. |
|
|
44
|
-
| `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one
|
|
48
|
+
| `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one slot directory per running job, `locks/<id>/` with its record `owner.json`. |
|
|
45
49
|
| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
|
|
46
50
|
|
|
47
|
-
One host lock serializes ticks, run-now,
|
|
48
|
-
|
|
49
|
-
|
|
51
|
+
One host lock, `~/.oats/schedules/host.lock`, serializes ticks, run-now,
|
|
52
|
+
reconcile and remove. Changes to the registry hold
|
|
53
|
+
`~/.oats/schedules/registry.lock`, and changes to a deployment's definitions
|
|
54
|
+
and state hold `<deployment>/.agents/schedules/scope.lock`. Each is a file that
|
|
55
|
+
names the process holding it, by its pid and the time it started.
|
|
56
|
+
|
|
57
|
+
**A lock left by a command that was killed is taken over by the next
|
|
58
|
+
command.** A tick that is killed, or lost in a reboot, while it holds the host
|
|
59
|
+
lock therefore does not stop the scheduler: the next tick finds that the
|
|
60
|
+
process the file names is gone, takes the lock and runs. A holder that is
|
|
61
|
+
still running is never taken over: the command answers `E_SCHEDULER_BUSY`
|
|
62
|
+
(`pid <n> holds it`), and nothing was changed.
|
|
63
|
+
|
|
64
|
+
Three cases are left to the operator. Each is `E_SCHEDULER_BUSY`, the message
|
|
65
|
+
says which it is and names the path, and nothing at that path is removed for
|
|
66
|
+
you:
|
|
67
|
+
|
|
68
|
+
| The message says | What is there | What to do |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `the record at <path> is unreadable` | a file that is not a lock's record | remove that file once no `oats schedule` process is running |
|
|
71
|
+
| `whether pid <n>, which holds it, still runs cannot be established` | a record whose process cannot be told from another with the same pid (the record has no start time, or this host cannot read one) | check pid `<n>` by hand; if it is not an `oats schedule` process, remove the lock file |
|
|
72
|
+
| `<path> is a lock directory written by an earlier kernel` | a directory, the lock of an oats older than this one | if an older oats is still running a schedule command, wait for it; otherwise remove the directory |
|
|
73
|
+
|
|
74
|
+
A lock whose holder is gone and whose record cannot be taken over (a record
|
|
75
|
+
without the identifier a takeover needs) is reported the same way, with the
|
|
76
|
+
file that must be removed.
|
|
77
|
+
|
|
78
|
+
**A job's slot is never there without its record.** The slot a running job
|
|
79
|
+
holds against `maxConcurrent`, `.agents/schedules/locks/<id>/`, is no lock
|
|
80
|
+
between processes: the host lock serializes everything that takes or
|
|
81
|
+
releases it, and it stands for the job's run until that run's instance ends.
|
|
82
|
+
Its record is written in `.agents/schedules/.slot-<id>/`, which is then
|
|
83
|
+
renamed to the slot, and a release renames the slot back there before
|
|
84
|
+
removing it. A command killed while it takes or releases a slot leaves the
|
|
85
|
+
slot with its record or no slot, and at most that directory, which the next
|
|
86
|
+
take or release of the slot removes.
|
|
87
|
+
|
|
88
|
+
**A slot whose record cannot be read stops only its job.** A slot directory
|
|
89
|
+
without its record (which an earlier oats could leave), a record that does
|
|
90
|
+
not parse, or something else at the slot's path says nothing about whether
|
|
91
|
+
the run it stands for still runs. OATS never writes into it or removes it
|
|
92
|
+
for you. The tick reports that job `invalid`, with the error `the slot <path>
|
|
93
|
+
has no readable record; check oats schedule show <id>; once its last run is
|
|
94
|
+
not running, run oats schedule reconcile <id> --clear to release the slot`
|
|
95
|
+
(`E_SCHEDULE_INVALID`), and ticks the deployment's other jobs as usual; the
|
|
96
|
+
slot counts against `maxConcurrent` until it is released. `oats schedule
|
|
97
|
+
run <id>` refuses with the same words. `oats schedule reconcile <id>`
|
|
98
|
+
answers `reconciled: "unknown"` with that sentence as its `remedy` and
|
|
99
|
+
leaves the slot; once you have checked, `reconcile <id> --clear` releases
|
|
100
|
+
it (`reconciled: "cleared"`), and reconciles an attempt beside it as
|
|
101
|
+
`--clear` does any attempt. `oats doctor` lists the slot as a
|
|
102
|
+
`schedule-slot-unreadable` problem ([Unresolved attempts](#what-a-run-reports)).
|
|
103
|
+
|
|
104
|
+
**A slot whose schedule is not defined is held until a person releases it.**
|
|
105
|
+
A schedule that is gone can leave its slot behind, readable or not, and it may
|
|
106
|
+
stand for a run that is still going. A local schedule is gone when it is no
|
|
107
|
+
longer in `oats-schedules.json`. A workspace schedule is gone when the saved
|
|
108
|
+
automation snapshot says so: its member was read at a commit, the snapshot
|
|
109
|
+
has no problem of that member that could hide a schedule (a schedule file
|
|
110
|
+
that could not be read or parsed, which may carry any id, or a member that
|
|
111
|
+
could not be listed), and no schedule has its id. That is decided from the
|
|
112
|
+
snapshot as it was last saved: reconcile and doctor refresh nothing, and
|
|
113
|
+
both name the snapshot's time. A workspace schedule that is disabled,
|
|
114
|
+
untrusted or placed on another host still has its entry there: it is not
|
|
115
|
+
gone, and reconcile refuses it as before (`E_AUTOMATION_NOT_HERE`). Without a
|
|
116
|
+
snapshot nothing is gone.
|
|
117
|
+
|
|
118
|
+
No tick reads the slot of a schedule that is gone, and every tick counts it
|
|
119
|
+
against `maxConcurrent` until it is released. `oats schedule reconcile <id>`
|
|
120
|
+
answers `{schedule: null, reconciled: "unknown", remedy}` with what it found
|
|
121
|
+
(the slot, how the schedule is known to be gone, and the run its record
|
|
122
|
+
names: its due minute and, for a wake, the home of its instance; a spawn's or
|
|
123
|
+
a command's record names no instance) and changes nothing. Once you have
|
|
124
|
+
checked `oats status`, `reconcile <id> --clear` releases the slot, resolves a
|
|
125
|
+
retained launch attempt as cleared (as for a defined job) and removes the
|
|
126
|
+
job's state: `{schedule: null, reconciled: "cleared", cleared: [...]}`, which
|
|
127
|
+
lists `"slot"`, `"attempt"` and `"state"` as each was there. A schedule that is
|
|
128
|
+
gone with retained state and no slot is reconciled the same way: reconcile
|
|
129
|
+
answers that it has retained state (and a launch attempt with no recorded
|
|
130
|
+
result, when there is one) and points to `--clear`, which answers `cleared:
|
|
131
|
+
["attempt", "state"]`. `oats doctor` lists the slot as a
|
|
132
|
+
`schedule-slot-orphaned` problem, and the `schedule-unresolved` row of a
|
|
133
|
+
retained attempt names the same `reconcile <id> --clear`.
|
|
134
|
+
|
|
135
|
+
A workspace schedule that is absent from the snapshot but cannot be shown gone
|
|
136
|
+
stays refused (`E_SCHEDULE_UNKNOWN`), and doctor lists its slot as
|
|
137
|
+
`schedule-slot-orphaned` with the step that applies: when its member is not
|
|
138
|
+
in the snapshot (removed from the workspace, or not read), check `oats
|
|
139
|
+
status` and remove the slot by hand, at the path doctor names; when its
|
|
140
|
+
member has a schedule file that could not be read, fix that file and run
|
|
141
|
+
`oats automations refresh`.
|
|
50
142
|
|
|
51
143
|
## Kinds
|
|
52
144
|
|
|
@@ -610,6 +702,7 @@ oats schedule host install # register this deployment and install the one
|
|
|
610
702
|
oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
|
|
611
703
|
oats schedule host install --max-concurrent default --triggers-max-concurrent none
|
|
612
704
|
oats schedule host install --print [--os darwin|linux] # what install would write; changes nothing
|
|
705
|
+
oats schedule host install --register-only # register this deployment and install no timer (oats host run ticks)
|
|
613
706
|
oats schedule host status | uninstall
|
|
614
707
|
oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?" # or --wake-file spec.json
|
|
615
708
|
```
|
|
@@ -663,6 +756,25 @@ five. Correct it with `oats schedule host install --max-concurrent N` (or
|
|
|
663
756
|
An absent value still means five. Set caps through the CLI; do not edit the
|
|
664
757
|
registry by hand.
|
|
665
758
|
|
|
759
|
+
### Without a host timer
|
|
760
|
+
|
|
761
|
+
`oats schedule host install --register-only` records the deployment in the
|
|
762
|
+
host registry, with any caps given, and installs no unit. It asks neither
|
|
763
|
+
launchd nor systemd for anything, so it works where neither exists. It does
|
|
764
|
+
not go with `--print` (`E_BAD_ARGS`). Its answer is install's: `scheduler`
|
|
765
|
+
with `registered: true` and `installed: false`, and no warnings.
|
|
766
|
+
|
|
767
|
+
On such a host `oats host run` is the ticker
|
|
768
|
+
([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)): each minute it
|
|
769
|
+
runs `oats schedule tick --host` for the scopes the registry lists, and with
|
|
770
|
+
none it ticks nothing and says so. It refuses to start while a host timer is
|
|
771
|
+
active (`E_HOST_RUN_TIMER_ACTIVE`), so a host has one ticker, never two.
|
|
772
|
+
With `--server`, `--register-only` is sent only to a destination that
|
|
773
|
+
advertises `schedule` and `schedule-host-register-only`. Any other is
|
|
774
|
+
refused with `E_REMOTE_INCOMPATIBLE` before anything is sent, because a
|
|
775
|
+
destination that does not know the option ignores it and installs a timer.
|
|
776
|
+
Upgrade OATS on the destination.
|
|
777
|
+
|
|
666
778
|
### The host timer's unit
|
|
667
779
|
|
|
668
780
|
The unit is a launchd user agent (`~/Library/LaunchAgents/ai.oats.schedule-tick.plist`,
|
|
@@ -819,9 +931,51 @@ schedule whose saved state supports reconciliation, `remedy` names
|
|
|
819
931
|
`oats schedule reconcile <id>`, with `--clear` for unproven command/operation
|
|
820
932
|
effects (check the roster and host by hand first), and `--dir <scope>` for
|
|
821
933
|
another deployment. Invalid or unsupported saved inputs instead receive a
|
|
822
|
-
warning to preserve state and inspect effects with the deployment owner.
|
|
934
|
+
warning to preserve state and inspect effects with the deployment owner. A
|
|
935
|
+
job whose slot has no readable record gets the slot's remedy below.
|
|
823
936
|
A warning never changes doctor's exit status.
|
|
824
937
|
|
|
938
|
+
`oats doctor` also lists each slot whose record cannot be read, in the same
|
|
939
|
+
deployments, as its own problem. The text form is `! schedule-slot-unreadable:
|
|
940
|
+
<message>` with the remedy on the next line; in `--json` it is a `problems[]`
|
|
941
|
+
item:
|
|
942
|
+
|
|
943
|
+
```text
|
|
944
|
+
{ code: "schedule-slot-unreadable", severity: "warning", scope, id, message, remedy }
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
`message` names the job and the slot's path; `remedy` is `check oats schedule
|
|
948
|
+
show <id>; once its last run is not running, run oats schedule reconcile <id>
|
|
949
|
+
--clear to release the slot`, with `--dir <scope>` on both commands for
|
|
950
|
+
another deployment. A workspace schedule that this host does not run
|
|
951
|
+
(disabled, untrusted, placed on another host, as the saved snapshot and
|
|
952
|
+
`oats-local.yaml` say offline), or that it cannot tell it runs, is refused by
|
|
953
|
+
reconcile here: its message says why, and its remedy is `once oats status
|
|
954
|
+
shows no run of schedule <id> here, remove the slot by hand: rm -r --
|
|
955
|
+
'<path>'`. No doctor row names a `--clear` that reconcile would refuse.
|
|
956
|
+
Doctor reads the slot as the tick does and changes nothing. A readable slot of a defined job, and no slot, are not listed.
|
|
957
|
+
|
|
958
|
+
A slot whose schedule is gone, readable or not, is listed as a
|
|
959
|
+
`schedule-slot-orphaned` problem instead, of the same shape (`! schedule-slot-orphaned:
|
|
960
|
+
<message>`, the remedy on the next line). Its message says how the schedule
|
|
961
|
+
is known gone (`which is not defined`, or `which as of <takenAt> is not in
|
|
962
|
+
the workspace (run oats automations refresh if that is stale)`) and what the
|
|
963
|
+
slot's record names (`has no readable record`, or `holds the run due
|
|
964
|
+
<minute> of the instance at <home>`, or `… of an instance its record does
|
|
965
|
+
not name`). Its remedy is `once oats status shows the instance at <home> is
|
|
966
|
+
not running, run oats schedule reconcile <id> --clear to release the slot`,
|
|
967
|
+
or, when the record names no instance, `once no run of schedule <id> is
|
|
968
|
+
running (oats status lists the instances it started), run oats schedule
|
|
969
|
+
reconcile <id> --clear to release the slot`. The `schedule-unresolved` row of
|
|
970
|
+
a gone workspace schedule's retained attempt names the same remedy. A
|
|
971
|
+
workspace schedule absent from the snapshot that cannot be shown gone is
|
|
972
|
+
listed as `schedule-slot-orphaned` too, with `which is not in the
|
|
973
|
+
workspace's snapshot of <takenAt>`, why, and its step: `check oats status for
|
|
974
|
+
a run of schedule <id>; once none is running, remove the slot by hand: rm -r
|
|
975
|
+
-- '<path>'` for a member not in the snapshot, `fix <file> in member
|
|
976
|
+
<member> and run oats automations refresh; doctor then says whether
|
|
977
|
+
schedule <id> is gone` for a file that could not be read.
|
|
978
|
+
|
|
825
979
|
Workspace guidance uses only validated local settings and the saved automation
|
|
826
980
|
snapshot. A known opt-out, missing saved definition, different assigned host or
|
|
827
981
|
absent trust explains why retained-state reconciliation is currently unavailable.
|
package/docs/servers.md
CHANGED
|
@@ -18,6 +18,39 @@ oats server remove build
|
|
|
18
18
|
To put a workspace on a machine that has no deployment yet, use
|
|
19
19
|
[`oats server connect`](#connect-a-machine) instead of `server add`.
|
|
20
20
|
|
|
21
|
+
`server add` and `server connect` also accept `--operator-ssh <alias>`.
|
|
22
|
+
It records the optional operator route separately in
|
|
23
|
+
`~/.oats/server-operator-routes.json`:
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{ "build": { "operatorSshHost": "build-operator" } }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`server list` (text and JSON) and connect's `registration` join that route
|
|
30
|
+
with the server registration. The alias follows the same rules as `--ssh`:
|
|
31
|
+
letters, digits, dot, underscore and dash, beginning with a letter or digit;
|
|
32
|
+
no `user@host`, spaces or SSH options. Put the user and forced-command key in
|
|
33
|
+
OpenSSH configuration under that alias. Registrations without it remain valid.
|
|
34
|
+
Older kernels never read this separate file; `servers.json` retains the field
|
|
35
|
+
set they accept.
|
|
36
|
+
|
|
37
|
+
The operator alias is reserved for credential provisioning. Registering it
|
|
38
|
+
runs no operator command: every existing remote operation continues to use
|
|
39
|
+
`sshHost`, and saved instance targets contain no operator route. To change an
|
|
40
|
+
existing registration, pass `--replace`; connect keeps an existing value
|
|
41
|
+
without it. With `--replace`, the operator route is kept unless you give
|
|
42
|
+
`--operator-ssh <alias>` to change it or `--no-operator-ssh` to clear it.
|
|
43
|
+
The two flags cannot be combined. `server remove` deletes the operator route
|
|
44
|
+
too. Both files are changed under the same `~/.oats/servers.lock`.
|
|
45
|
+
A fresh add or connect starts with no operator route unless `--operator-ssh`
|
|
46
|
+
is given; a route left behind by an older kernel is discarded for that new
|
|
47
|
+
registration.
|
|
48
|
+
For example:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
oats server add build --ssh build-host --operator-ssh build-operator --workspace /srv/team
|
|
52
|
+
```
|
|
53
|
+
|
|
21
54
|
- `--ssh` is an OpenSSH host alias or host name, never `user@host` or an
|
|
22
55
|
option. Users, keys and host verification belong in `~/.ssh/config`.
|
|
23
56
|
Connections are non-interactive (`BatchMode=yes`): a prompt fails fast.
|
|
@@ -36,10 +69,14 @@ To put a workspace on a machine that has no deployment yet, use
|
|
|
36
69
|
- Registrations live in `~/.oats/servers.json` on this machine, never in a
|
|
37
70
|
repository. Every change to the file (add, remove, a learned workspace key,
|
|
38
71
|
connect) is a short read-modify-write of the file as it is then, under the
|
|
39
|
-
lock
|
|
40
|
-
other's registrations.
|
|
41
|
-
that
|
|
42
|
-
|
|
72
|
+
lock `~/.oats/servers.lock`, so concurrent commands never lose each
|
|
73
|
+
other's registrations. The lock is a file that names the process holding it.
|
|
74
|
+
One left by a command that was killed is taken over by the next command. One
|
|
75
|
+
whose holder is still running after 5 s is refused with `E_SERVERS_BUSY`. So
|
|
76
|
+
are a lock file whose record is unreadable, a holder that cannot be told to
|
|
77
|
+
be running or gone, and a lock directory written by an earlier kernel: the
|
|
78
|
+
message says which it found and names the path to remove once no oats
|
|
79
|
+
process is changing the registry.
|
|
43
80
|
|
|
44
81
|
**Which workspace a server serves.** A registration records `workspaceKey`:
|
|
45
82
|
the canonical key of the workspace its host deployment realizes, as the
|
|
@@ -54,7 +91,8 @@ never typed:
|
|
|
54
91
|
- A key is recorded only on the registration that was asked: if the
|
|
55
92
|
registration is removed or pointed elsewhere while the host is being asked,
|
|
56
93
|
the answer is dropped (`server add` warns), never written onto the new
|
|
57
|
-
entry or used to bring a removed one back.
|
|
94
|
+
entry or used to bring a removed one back. The add result reports no
|
|
95
|
+
workspace key when the registration changed during the request.
|
|
58
96
|
- A host reporting a different key than the recorded one is
|
|
59
97
|
`E_SERVER_WORKSPACE_MISMATCH` (`details: {recorded, reported}`) and the
|
|
60
98
|
registration is not rewritten. If the host now serves another workspace,
|
|
@@ -68,6 +106,143 @@ never typed:
|
|
|
68
106
|
(`workspaceReadable`; the host's [`onboard --check`](#what-connect-runs-on-the-host)),
|
|
69
107
|
which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
|
|
70
108
|
|
|
109
|
+
## Harness credentials
|
|
110
|
+
|
|
111
|
+
Install, inspect or remove a harness credential through the operator route:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
credential-source | oats harness token set claude --server build --name team --stdin
|
|
115
|
+
oats harness token status claude --server build --name team
|
|
116
|
+
oats harness token remove claude --server build --name team
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Here `credential-source` stands for a command that supplies an existing
|
|
120
|
+
credential on stdout without putting it in arguments, files or terminal
|
|
121
|
+
output elsewhere. OATS never accepts the credential as an argument or writes
|
|
122
|
+
it on this machine. `--stdin` refuses a terminal, whose normal echo would
|
|
123
|
+
show the value.
|
|
124
|
+
|
|
125
|
+
The harness is `claude`, `codex`, `pi` or `opencode`. `--name` is the
|
|
126
|
+
receiver's configured team name: lowercase letters, digits and dashes,
|
|
127
|
+
starting with a letter or digit, at most 63 characters. When omitted, the
|
|
128
|
+
server label is used only if it already matches that grammar; otherwise
|
|
129
|
+
give `--name`. OATS never guesses a slug from a display label.
|
|
130
|
+
|
|
131
|
+
These commands use the separate operator SSH alias and its forced-command
|
|
132
|
+
receiver, with the usual noninteractive SSH options and `ControlPath=none`.
|
|
133
|
+
They never reuse the agent connection or fall back to the agent alias.
|
|
134
|
+
An unknown server id refuses before SSH, even if an orphan operator route exists.
|
|
135
|
+
Without an operator route, OATS refuses with `E_HARNESS_TOKEN_ROUTE` and
|
|
136
|
+
prints a complete `oats server add <id> --ssh <agent-alias> --workspace <path>
|
|
137
|
+
--operator-ssh <alias> --replace` remedy, preserving the registration's
|
|
138
|
+
existing `--label`, `--oats` and `--path` values. Replace `<alias>` with the
|
|
139
|
+
operator alias; `oats server list --json` shows the current registration.
|
|
140
|
+
The receiver answers only a fingerprint and replacement time; it never
|
|
141
|
+
returns a credential. Removal deletes the delivered credential file; revoke
|
|
142
|
+
the original credential with its provider too.
|
|
143
|
+
|
|
144
|
+
The forced command is `oats-login-receive`, installed root-owned
|
|
145
|
+
and bound to a dedicated key. It accepts `install|status|remove <harness> <name>`
|
|
146
|
+
through `SSH_ORIGINAL_COMMAND`; the destination is the receiver's root-owned
|
|
147
|
+
configuration, never a client-supplied path. See the
|
|
148
|
+
[CLI JSON contract](desktop-cli-api.md#harness-token) and
|
|
149
|
+
[receiver installation](#install-the-credential-receiver).
|
|
150
|
+
|
|
151
|
+
`set` maps to the receiver's `install`, with the credential on stdin. The
|
|
152
|
+
receiver writes atomically to its configured root-owned file, normally
|
|
153
|
+
`/srv/oats-team/<name>/login/<harness>-token`, readable by the agent group
|
|
154
|
+
and not writable by it. OATS validates the returned fingerprint against the
|
|
155
|
+
bytes it sent. Re-running `set` rotates the file; sessions keep their
|
|
156
|
+
current credential until their next start. The output lists instances of the
|
|
157
|
+
same harness on that server whose last start predates or falls within the
|
|
158
|
+
reported replacement second. The receiver records whole seconds, so sessions
|
|
159
|
+
started during that second may still have read the previous credential.
|
|
160
|
+
It never restarts them. If listing fails after installation, the command
|
|
161
|
+
still succeeds, with a warning and an unknown older-session list.
|
|
162
|
+
|
|
163
|
+
Input is at most 65,536 bytes of strict UTF-8. Leading and trailing ASCII
|
|
164
|
+
whitespace is stripped as the receiver strips it; the result must be one
|
|
165
|
+
non-empty line, contain no NUL, and fit in 65,535 bytes so the installed final
|
|
166
|
+
newline fits the 64 KiB file-reference cap. Claude tokens must begin
|
|
167
|
+
`sk-ant-oat` and fit in 512 bytes, matching the receiver's check. Other
|
|
168
|
+
harness inputs are opaque provider API keys.
|
|
169
|
+
|
|
170
|
+
| Harness | Credential supplied through stdin | Agent launch binding | Login and revocation |
|
|
171
|
+
|---|---|---|---|
|
|
172
|
+
| Claude | inference-only setup-token | `CLAUDE_CODE_OAUTH_TOKEN` with `fromFile` | Created on the person's machine; revoke by signing the session out in claude.ai settings |
|
|
173
|
+
| Codex | non-refreshing OpenAI API key | `OPENAI_API_KEY` with `fromFile` | Obtain and revoke on the provider's key page |
|
|
174
|
+
| pi | non-refreshing provider API key | the provider's env variable, such as `ANTHROPIC_API_KEY`, with `fromFile` | Provider-specific key page |
|
|
175
|
+
| opencode | opaque provider API key | provider binding must be configured separately; OATS does not choose one | Provider-specific key page |
|
|
176
|
+
|
|
177
|
+
OATS runs no harness login for this stdin path. Claude interactive capture
|
|
178
|
+
is unavailable. Codex ChatGPT sign-in and pi OAuth are refused: their credentials
|
|
179
|
+
refresh on the agent host and rewrite an auth file, which does not fit a
|
|
180
|
+
read-only operator-delivered credential. No interactive opencode adapter is
|
|
181
|
+
available. For pi, `--name` is the team, not a provider selection. Configure
|
|
182
|
+
the provider's launch environment yourself; these commands never edit launch
|
|
183
|
+
configurations. See [file references](configuration.md#launch-configurations).
|
|
184
|
+
|
|
185
|
+
`--debug` prints SSH exit and known transport error codes on stderr.
|
|
186
|
+
It never forwards receiver stdout or raw diagnostics: an unexpected peer
|
|
187
|
+
could echo all or part of its stdin. Public failures distinguish an unreachable
|
|
188
|
+
server, a receiver refusal and an unexpected reply without exposing a value.
|
|
189
|
+
|
|
190
|
+
### Install the credential receiver
|
|
191
|
+
|
|
192
|
+
The npm package ships `share/oats-login-receive`. On the receiving server,
|
|
193
|
+
its installed path is
|
|
194
|
+
`$(npm root -g)/@awebai/oats/share/oats-login-receive`. The receiver requires
|
|
195
|
+
Python 3 at `/usr/bin/python3`; its shebang runs Python in isolated mode (`-I`).
|
|
196
|
+
After installing OATS on that server, install the receiver as root, mode 0755:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
sudo install -d -o root -g root -m 0755 /usr/local/sbin /etc/oats-login
|
|
200
|
+
sudo install -o root -g root -m 0755 \
|
|
201
|
+
"$(npm root -g)/@awebai/oats/share/oats-login-receive" \
|
|
202
|
+
/usr/local/sbin/oats-login-receive
|
|
203
|
+
sudoedit /etc/oats-login/receiver.json
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The root-owned `/etc/oats-login/receiver.json` selects the allowed teams,
|
|
207
|
+
read groups, harnesses and destinations. This is the format from the
|
|
208
|
+
receiver's docstring, with a concrete team and group:
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{
|
|
212
|
+
"teams": {
|
|
213
|
+
"team": {
|
|
214
|
+
"group": "oats-team",
|
|
215
|
+
"harnesses": ["claude", "codex", "pi", "opencode"],
|
|
216
|
+
"path": "/srv/oats-team/{name}/login/{harness}-token"
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Replace `team` and `oats-team` with the receiver's configured team name and
|
|
223
|
+
an existing group whose members may read its credentials. `path` is optional;
|
|
224
|
+
the default is `/srv/oats-team/{name}/login/{harness}-token`. Keep both the
|
|
225
|
+
configuration file and `/etc/oats-login` root-owned and not writable by group
|
|
226
|
+
or others:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
sudo chown root:root /etc/oats-login/receiver.json
|
|
230
|
+
sudo chmod 0644 /etc/oats-login/receiver.json
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Add the dedicated operator public key to root's `authorized_keys` with this
|
|
234
|
+
forced command, replacing `<key>` with that public key:
|
|
235
|
+
|
|
236
|
+
```text
|
|
237
|
+
restrict,command="/usr/local/sbin/oats-login-receive" <key>
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The operator SSH alias selects that key and the root account. The agent SSH
|
|
241
|
+
alias uses its separate account and key. The receiver creates credential
|
|
242
|
+
files root-owned, group-readable and mode 0440; the login directory is mode
|
|
243
|
+
0750, and its parents must be root-owned, not writable by others and not
|
|
244
|
+
symlinks. Neither the caller's command nor stdin chooses a destination path.
|
|
245
|
+
|
|
71
246
|
## Connect a machine
|
|
72
247
|
|
|
73
248
|
```bash
|
|
@@ -84,6 +259,7 @@ missing, so after a human step you run the same command again.
|
|
|
84
259
|
| `--dir <path>` | none, inside a deployment too: the folder on the host for this deployment, absolute or `~/…` (resolved by the host). Without it: `E_BAD_ARGS` "--dir <path on the host> is required: the folder on `<host>` for this deployment (absolute, or ~/… resolved there)". A registration made before it was required is unchanged |
|
|
85
260
|
| `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
|
|
86
261
|
| `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses. Without it, connect uses the PATH of the host user's [login shell](#the-hosts-login-shell-path) |
|
|
262
|
+
| `--operator-ssh <alias>`, `--no-operator-ssh` | set or clear the separate operator route; with `--replace`, omitting both keeps it. Same alias validation as `--ssh` |
|
|
87
263
|
| `--install-oats` | off: a missing or older OATS is a human step |
|
|
88
264
|
| `--replace` | off: an id registered for another host or directory is refused |
|
|
89
265
|
|
|
@@ -249,7 +425,9 @@ Every routed ssh call carries these options, before `--` and the host:
|
|
|
249
425
|
failed: …`). When ssh never started on this machine, the `--json` envelope
|
|
250
426
|
says so with `error.details: {"sshStarted": false}`; without details, ssh
|
|
251
427
|
ran and the link failed
|
|
252
|
-
([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)).
|
|
428
|
+
([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)). A link that
|
|
429
|
+
fails under a routed spawn carries the decision and the key to run it
|
|
430
|
+
again with ([Run there](#run-there)).
|
|
253
431
|
|
|
254
432
|
## Run there
|
|
255
433
|
|
|
@@ -264,9 +442,27 @@ Arguments are quoted for the remote shell. Local files (`--task-file`,
|
|
|
264
442
|
`--wake-file`, a schedule or launch-configuration `--file`) are read here and
|
|
265
443
|
sent as text or on stdin, never as paths.
|
|
266
444
|
|
|
445
|
+
<a id="a-routed-spawns-task"></a>
|
|
446
|
+
**A routed spawn's task is on no command line, for a server that advertises
|
|
447
|
+
`spawn-task-stdin`.** The text of `--task` or of `--task-file` goes to such a
|
|
448
|
+
server on the standard input of the ssh session, to the server's preview and
|
|
449
|
+
to its spawn alike, and the remote command carries `--task-file -` in its
|
|
450
|
+
place: the text is in the arguments of neither the local `ssh` process nor
|
|
451
|
+
the server's `oats`, where every user of either machine could read it in the
|
|
452
|
+
process list. A server that does not advertise `spawn-task-stdin` cannot read
|
|
453
|
+
it there, and gets it as an argument of the remote command: the spawn
|
|
454
|
+
succeeds, the task is readable in both process lists while it runs (this
|
|
455
|
+
machine's, in the `ssh` command, and the server's), and the answer carries
|
|
456
|
+
one warning that says so: `remote oats <version> at <host> does not
|
|
457
|
+
advertise spawn-task-stdin, so the task was passed as an argument, visible
|
|
458
|
+
in this machine's process list (the ssh command) and the host's while the
|
|
459
|
+
spawn runs; upgrade the host`. Upgrade OATS on the server to keep tasks off
|
|
460
|
+
both command lines. A `--wake-message` and a
|
|
461
|
+
schedule's spec still travel as arguments.
|
|
462
|
+
|
|
267
463
|
| Command | Where it runs | The server must advertise |
|
|
268
464
|
|---|---|---|
|
|
269
|
-
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
|
|
465
|
+
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
|
|
270
466
|
| `status` | registered workspace | |
|
|
271
467
|
| `retire` | the instance's home | `retire-home` to retire by exact home |
|
|
272
468
|
| `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
|
|
@@ -296,6 +492,44 @@ checked against the harness it would use (the flag, or the soul's default as
|
|
|
296
492
|
the remote roster reports it). A host that advertises no harness list is
|
|
297
493
|
assumed to run only pi and claude, on tmux, with no launch options.
|
|
298
494
|
|
|
495
|
+
**A routed spawn.** `oats spawn <soul> --server <id>` runs the spawn's checks
|
|
496
|
+
here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and options), then
|
|
497
|
+
asks the server's kernel in two calls:
|
|
498
|
+
|
|
499
|
+
1. its preview (`spawn … --preview`), which decides the name and everything
|
|
500
|
+
else and creates nothing;
|
|
501
|
+
2. the spawn itself, bound to that decision and to a key made for this
|
|
502
|
+
request (`--expect-decision <revision> --idempotency-key <key>`).
|
|
503
|
+
|
|
504
|
+
The answer is the server's keyed answer (`decision`, `replayed`, `wake`
|
|
505
|
+
beside the rest) plus `server`, `target` and `snapshot`, and the route is
|
|
506
|
+
saved. With `--suggest-name` the preview chooses the name and the spawn
|
|
507
|
+
carries it as `--name`; the answer keeps the preview's `naming`. This needs
|
|
508
|
+
the server's `spawn-suggest-name` and `spawn-name` too.
|
|
509
|
+
|
|
510
|
+
- **A link that fails under the second call** (a lost connection, a
|
|
511
|
+
timeout) is `E_SSH`, and the server may have started the spawn. The
|
|
512
|
+
message ends with the fix, and `--json` carries it:
|
|
513
|
+
`error.details: {decision, idempotencyKey, fix}`. Run the same spawn again
|
|
514
|
+
with `--expect-decision <decision.revision> --idempotency-key
|
|
515
|
+
<idempotencyKey>` (and `--name <decision.instance>` in place of
|
|
516
|
+
`--suggest-name`): the server answers the instance the first attempt
|
|
517
|
+
created (`replayed: true`), or creates it, and the route is saved. An
|
|
518
|
+
attempt still running there answers `E_SPAWN_INCOMPLETE`, naming the
|
|
519
|
+
instance. Run again without the two flags, the spawn is a separate request
|
|
520
|
+
and may create a second instance.
|
|
521
|
+
- **A name taken between the two calls** (another spawn on the server took
|
|
522
|
+
it) is `E_DECISION_STALE`; nothing was created. Run the spawn again.
|
|
523
|
+
- **A spawn that brings `--expect-decision` or `--idempotency-key`** travels
|
|
524
|
+
as given, in one call: the caller previewed (`--server <id> --preview`) and
|
|
525
|
+
holds the key.
|
|
526
|
+
- **A server that does not advertise `spawn-preview-2`, `spawn-apply-2` and
|
|
527
|
+
`spawn-idempotency-2`** gets the spawn in one call, as given, and the
|
|
528
|
+
answer carries a warning: if the link drops while it spawns, the spawn
|
|
529
|
+
cannot be retried safely, since the instance may exist there and a second
|
|
530
|
+
run would create another. Check `oats status --server <id>` before running
|
|
531
|
+
it again, or upgrade OATS there.
|
|
532
|
+
|
|
299
533
|
**A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
|
|
300
534
|
spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
|
|
301
535
|
options), then asks the server's kernel for its preview. It prints the local
|