@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.
Files changed (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. 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 lock directory per running job. |
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, reconcile and remove. It is never
48
- reclaimed by another process: a lock whose owner is gone is reported with the
49
- directory to remove.
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 directory `~/.oats/servers.lock`, so concurrent commands never lose each
40
- other's registrations. A lock still held after 5 s, or left by a process
41
- that died, is refused with `E_SERVERS_BUSY`, naming the directory to remove
42
- once no oats process is changing the registry.
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