@awebai/oats 0.69.14 → 0.69.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bin/oats.mjs +79 -18
- package/docs/capabilities.md +57 -14
- package/docs/container.md +111 -17
- package/docs/desktop-cli-api.md +215 -19
- package/docs/desktop.md +3 -3
- package/docs/execution-targets.md +15 -3
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +19 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-and-learning.md +2 -2
- package/docs/knowledge-theory.md +17 -15
- package/docs/knowledge.md +202 -179
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/release-notes/v0.69.16.md +169 -0
- package/docs/schedules.md +168 -34
- package/docs/servers.md +64 -3
- package/docs/souls-and-instances.md +100 -19
- package/docs/upgrading.md +26 -6
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +2 -3
- package/lib/command-flags.mjs +4 -2
- package/lib/core.mjs +215 -72
- package/lib/dir-lock.mjs +17 -0
- package/lib/errors.mjs +2 -1
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/instance-git.mjs +32 -6
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +35 -6
- package/lib/kernel-features.mjs +4 -1
- package/lib/read-call.mjs +1 -1
- package/lib/remote.mjs +17 -14
- package/lib/schedule.mjs +237 -20
- package/lib/servers.mjs +83 -5
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +10 -18
- package/lib/session-seen.mjs +4 -64
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +19 -10
- package/package-catalog.json +3 -3
- package/package.json +4 -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/skills/oats-getting-started/SKILL.md +9 -6
package/docs/desktop-cli-api.md
CHANGED
|
@@ -171,6 +171,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
171
171
|
| `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
|
|
172
172
|
| `workspace-tasks-payload` | oats-workspace.yaml may carry a top-level `tasks:` payload, merged for the capability that fills the tasks slot exactly as `messaging:` is for the messaging one; its leaves' `settingsOrigins` are `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}` ([Provider payloads have three homes](workspaces.md#provider-payloads-have-three-homes)). A kernel without it refuses a workspace file that carries `tasks:` (unknown property) | |
|
|
173
173
|
| `settings-committed-only` | a manifest `settings.<key>.committedOnly: true` is enforced: that key in oats-local.yaml `settings.<cap>` or a `--provider <cap>` flag is refused `E_WORKSPACE_SCHEMA` reason `committed-only-key`, with `details.layer`, `details.at` and `details.allowed` ([Commands and hooks](capabilities.md#commands-and-hooks)). A kernel without it ignores the flag and merges the key | |
|
|
174
|
+
| `schedule-host-register-only` | `oats schedule host install --register-only`: the scope is recorded in the host schedule registry and no timer is installed ([`oats schedule`](#oats-schedule)). Routed with `--server`, the option is sent only to a host that lists this and `schedule`; otherwise it is refused here with `E_REMOTE_INCOMPATIBLE` before anything is sent, since a host without it ignores the option and installs a timer | |
|
|
175
|
+
| `spawn-task-stdin` | `oats spawn <soul> --task-file -` reads the task from standard input. A spawn routed with `--server` sends its `--task` or `--task-file` text that way, to the preview and to the apply, to a host that lists this, and not as an argument; a host that does not list it gets the text as an argument, and the answer's `warnings` gains one line that says it was readable in both machines' process lists ([servers.md](servers.md#a-routed-spawns-task)) |
|
|
174
176
|
|
|
175
177
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
176
178
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -337,8 +339,9 @@ for `--no-recursive`) is never ignored.
|
|
|
337
339
|
| `oats schedule disable` | `<id>` | `--dir`, `--server` | `--json` | none | none |
|
|
338
340
|
| `oats schedule reconcile` | `<id>` | `--dir`, `--server` | `--clear`, `--json` | none | none |
|
|
339
341
|
| `oats schedule tick` | none | `--dir`, `--server` | `--dry-run`, `--host`, `--json` | none | none |
|
|
340
|
-
| `oats schedule host install` | none | `--max-concurrent`, `--triggers-max-concurrent`, `--os`, `--dir`, `--server` | `--print`, `--json` | none | none |
|
|
342
|
+
| `oats schedule host install` | none | `--max-concurrent`, `--triggers-max-concurrent`, `--os`, `--dir`, `--server` | `--register-only`, `--print`, `--json` | none | none |
|
|
341
343
|
| `oats schedule host uninstall` | none | `--dir`, `--server` | `--json` | none | none |
|
|
344
|
+
| `oats host run` | none | `--stop-grace` | `--plan`, `--json` | none | none |
|
|
342
345
|
| `oats trigger add` | none | `--file`, `--from`, `--set`, `--id`, `--description`, `--workspace`, `--runs-on`, `--owner`, `--dir` | `--json` | none | none |
|
|
343
346
|
| `oats trigger poll` | `<id>` | `--dir`, `--max-age` | `--run-source`, `--json` | none | none |
|
|
344
347
|
| `oats trigger test` | `<id>` | `--dir` | `--run-source`, `--json` | none | none |
|
|
@@ -433,6 +436,11 @@ failure as `E_SSH`, message `ssh to <host> failed: …`:
|
|
|
433
436
|
retrying cannot help.
|
|
434
437
|
- No `details`: ssh ran and the link failed (unreachable host, refused key,
|
|
435
438
|
lost connection, timeout); a retry may succeed.
|
|
439
|
+
- `error.details` is `{decision, idempotencyKey, fix}` when the link failed
|
|
440
|
+
under the apply of a routed spawn the route bound itself
|
|
441
|
+
([Idempotency](#spawn-idempotency-routed)): the host may have started the
|
|
442
|
+
spawn, and the same spawn with `--expect-decision <decision.revision>
|
|
443
|
+
--idempotency-key <idempotencyKey>` answers that one instance.
|
|
436
444
|
|
|
437
445
|
(0.31.0; before it `E_SSH` never carried details.)
|
|
438
446
|
|
|
@@ -1724,6 +1732,25 @@ person, as one `resume-lock-stuck` problem in `problems[]`, `{code, message,
|
|
|
1724
1732
|
remedy}` ([The machine sweep](#the-machine-sweep-oats-session-resume),
|
|
1725
1733
|
`E_RESUME_LOCK_STUCK`). It is the machine's, the same from every deployment.
|
|
1726
1734
|
|
|
1735
|
+
`oats doctor --json` lists each schedule slot whose record cannot be read, in
|
|
1736
|
+
the deployment and the others the host ticks, as one `schedule-slot-unreadable`
|
|
1737
|
+
problem in `problems[]`, `{code, severity: "warning", scope, id, message,
|
|
1738
|
+
remedy}` (text: `! schedule-slot-unreadable: <message>`, the remedy on the
|
|
1739
|
+
next line). The remedy is to check `oats schedule show <id>`, then run `oats
|
|
1740
|
+
schedule reconcile <id> --clear` ([Schedules](schedules.md#files)); for a
|
|
1741
|
+
workspace schedule this host does not run, or cannot tell it runs, the
|
|
1742
|
+
message says why and the remedy is to remove the slot by hand, at the path it
|
|
1743
|
+
names, once `oats status` shows no run of it here. A slot
|
|
1744
|
+
whose schedule is gone (a local one not in `oats-schedules.json`, a workspace
|
|
1745
|
+
one not in the saved snapshot, whose time it names), readable or not, is one
|
|
1746
|
+
`schedule-slot-orphaned` problem of the same shape, naming the run and the
|
|
1747
|
+
instance its record names; its remedy is to check `oats status`, then run
|
|
1748
|
+
`oats schedule reconcile <id> --clear`. A workspace schedule absent from the
|
|
1749
|
+
snapshot that cannot be shown gone (its member is not in it, or has a schedule
|
|
1750
|
+
file that could not be read) is the same problem, with the step that applies:
|
|
1751
|
+
remove the slot by hand at the path it names, or fix that file and run `oats
|
|
1752
|
+
automations refresh`.
|
|
1753
|
+
|
|
1727
1754
|
### Desktop facts
|
|
1728
1755
|
|
|
1729
1756
|
Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
|
|
@@ -2961,6 +2988,40 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
|
|
|
2961
2988
|
Without `--expect-decision` the flag is `E_BAD_ARGS`
|
|
2962
2989
|
([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
|
|
2963
2990
|
|
|
2991
|
+
<a id="spawn-caller-gone"></a>**A caller that goes away.** A spawn does not
|
|
2992
|
+
depend on its caller to finish: once it has made the home it ends with the
|
|
2993
|
+
home complete or with the home rolled back, whether or not anyone still
|
|
2994
|
+
reads it or its session is still there.
|
|
2995
|
+
- A reader that closes stdout or stderr (an ssh session that ended, a
|
|
2996
|
+
Desktop that quit) only stops reading: the spawn runs to its end, what it
|
|
2997
|
+
could not print is dropped, and its exit status is the spawn's own, `0`
|
|
2998
|
+
for a spawn that completed, as for [`oats worktree add`](#oats-worktree).
|
|
2999
|
+
The answer nobody read is the home's record, and a spawn that brought
|
|
3000
|
+
`--expect-decision` and `--idempotency-key` answers it again when it is
|
|
3001
|
+
repeated (below).
|
|
3002
|
+
- The same holds for the verbs that act under a home's
|
|
3003
|
+
[lifecycle claim](#lifecycle-pairs): `oats retire`, `oats session start`,
|
|
3004
|
+
`oats session restart` and `oats instance stop --apply`. With no reader
|
|
3005
|
+
the act completes, a line it writes on stderr while it acts (a start
|
|
3006
|
+
that starts the OATS tmux server writes one) is dropped with the answer,
|
|
3007
|
+
and the exit status is the act's own, never the `1` of an unhandled
|
|
3008
|
+
`EPIPE`. What was done is on disk: the home is gone, the session runs, or
|
|
3009
|
+
the stop's receipt is stored, and a stop or a guarded retire repeated
|
|
3010
|
+
with its `--idempotency-key` answers the receipt again. Their plans
|
|
3011
|
+
(`--plan`) and every reading command are as before: a reader that goes
|
|
3012
|
+
away ends them.
|
|
3013
|
+
- SIGINT, SIGTERM or SIGHUP never ends the process with a home that has no
|
|
3014
|
+
record. While the capabilities are copied into the new home, and while
|
|
3015
|
+
its `worktree` hooks run, the signal is held and the spawn is rolled back:
|
|
3016
|
+
`E_INTERRUPTED`, exit 128 + the signal number
|
|
3017
|
+
([Spawn errors](#spawn-errors)). At any other moment the signal reaches
|
|
3018
|
+
the process once the spawn has returned: the home is complete, the answer
|
|
3019
|
+
is written, and the process then exits 128 + the signal number. This is
|
|
3020
|
+
the spawn's rule alone: a retire, a start, a restart and a stop apply
|
|
3021
|
+
hold no signal, and one that is signalled ends where it stands, its claim
|
|
3022
|
+
left for the next command of that home to
|
|
3023
|
+
[take over](#lifecycle-pairs).
|
|
3024
|
+
|
|
2964
3025
|
**Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
|
|
2965
3026
|
with `--expect-decision` records the key and decision in `instance.json`.
|
|
2966
3027
|
- Recovery runs right after naming, before placement or preflight. A retry
|
|
@@ -2974,6 +3035,23 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
2974
3035
|
for that intent's retries.
|
|
2975
3036
|
- `wake: {requested, saved, error}` is recorded and replayed; `saved: null`
|
|
2976
3037
|
means the outcome was not recorded.
|
|
3038
|
+
- A replay answers `attach` as the first apply did; its `launch` is `null`
|
|
3039
|
+
(nothing runs again).
|
|
3040
|
+
- <a id="spawn-idempotency-routed"></a>**Routed (`--server`).** A spawn that
|
|
3041
|
+
brings neither `--expect-decision` nor `--idempotency-key` is bound by the
|
|
3042
|
+
route: it asks the host for its preview, then applies with that decision
|
|
3043
|
+
and a key it makes for the request, and relays the host's keyed answer
|
|
3044
|
+
(`decision`, `replayed: false`, `wake`). A link that fails under that apply
|
|
3045
|
+
is `E_SSH` with `error.details: {decision, idempotencyKey, fix}`: `decision`
|
|
3046
|
+
is the previewed decision, `idempotencyKey` the key the apply carried and
|
|
3047
|
+
`fix` the sentence naming the two flags (and `--name <decision.instance>`
|
|
3048
|
+
in place of `--suggest-name`). The same spawn with them is forwarded as
|
|
3049
|
+
given and answers the one instance. A spawn that brings either flag is
|
|
3050
|
+
forwarded as given. A host without `spawn-preview-2`, `spawn-apply-2` and
|
|
3051
|
+
`spawn-idempotency-2` (and, for `--suggest-name`, `spawn-suggest-name` and
|
|
3052
|
+
`spawn-name`) gets one unbound spawn, and the answer's `warnings` say that
|
|
3053
|
+
a dropped link cannot be retried safely there
|
|
3054
|
+
([servers.md](servers.md#run-there)).
|
|
2977
3055
|
|
|
2978
3056
|
**Result** (`oats spawn <soul> … --json`):
|
|
2979
3057
|
|
|
@@ -3264,7 +3342,7 @@ kernel stage raised as well.
|
|
|
3264
3342
|
| `E_HARNESS_RESOURCE_MISSING` | | a harness package a capability requires for the selected harness is not installed, disabled, or cannot be verified ([capabilities.md](capabilities.md)); raised before any home exists, at a preview too, and again by an apply after the home, the work and the hooks when the pane it got differs from the one it checked in a name the probe reads, or selects another program (another creator started the OATS tmux server): then the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start, a restart and a launch plan's `harness-packages` check answer the same code |
|
|
3265
3343
|
| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
|
|
3266
3344
|
| `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
|
|
3267
|
-
| `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
|
|
3345
|
+
| `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number. Also while the capabilities were copied into the new home, before any hook: the signal is held until the copy ends, the home is removed, `hooks` is `[]`, and the exit status is the same ([a caller that goes away](#spawn-caller-gone)) |
|
|
3268
3346
|
| `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
|
|
3269
3347
|
| `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
|
|
3270
3348
|
| `E_RUNTIME_ENDPOINT_UNKNOWN` | | the session cannot be established: the OATS tmux server cannot be read at an apply (before any effect, or after the home, the work and the hooks), or the pane's `PATH`, `HOME` or harness folder cannot be read for the harness package check ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)), before anything is probed or created, or at the apply's second check after the hooks, as for `E_HARNESS_RESOURCE_MISSING`. Once the home exists the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start and a restart answer the same code |
|
|
@@ -3427,7 +3505,7 @@ A failed `add` reports the same facts about its rollback in `details`:
|
|
|
3427
3505
|
| `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
|
|
3428
3506
|
| `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
|
|
3429
3507
|
| `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
|
|
3430
|
-
| `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; the tree is removed |
|
|
3508
|
+
| `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; or a checkout was not run because the repository's configuration defines a filter driver whose name cannot be overridden ([a checkout runs no filter driver](souls-and-instances.md#checkout-filter-drivers)); the tree is removed |
|
|
3431
3509
|
| `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
|
|
3432
3510
|
| `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); a file at the claim's path is no claim this kernel can read or take over (`details.lock`); the claim was taken again, the last time by a process that is gone, each of the five times the command found it without a live holder (`run the command again`); an interrupted add's rollback could not be completed (`details.owed`; the message says what to deal with and to run `oats worktree remove --purpose <purpose>`, which finishes the rollback); or, `add` only (OATS 0.52.0), the home's claim is held by a retire whose liveness cannot be read, or is a file that is no readable claim (`no tree was made`; [Commands that meet on one home](#lifecycle-pairs)). Every one carries [`details.holder`](#busy-holder) |
|
|
3433
3511
|
| `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
|
|
@@ -3599,8 +3677,10 @@ its absence.
|
|
|
3599
3677
|
and no `runtimeState`. What the lifecycle commands answer for such a home:
|
|
3600
3678
|
[below](#unreadable-record).
|
|
3601
3679
|
- **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
|
|
3602
|
-
while a spawn that
|
|
3603
|
-
pid runs with the recorded start time)
|
|
3680
|
+
while a spawn that wrote its in-progress marker is verifiably alive (its
|
|
3681
|
+
pid runs with the recorded start time): one running its `worktree` hooks,
|
|
3682
|
+
or one that has reached its spawn hooks and not yet written its record,
|
|
3683
|
+
when a capability with a spawn hook has a retire hook. Such a home holds the quarantine marker
|
|
3604
3684
|
with an `inProgress` field ([capabilities.md](capabilities.md#manifest)),
|
|
3605
3685
|
and its row carries `spawnInProgress: true` and **no**
|
|
3606
3686
|
`rollbackIncomplete`: a live spawn, not a failed one. Once that process is
|
|
@@ -3626,8 +3706,9 @@ its absence.
|
|
|
3626
3706
|
reading `null` unless a harness runs there.
|
|
3627
3707
|
- <a id="row-session-end"></a>**`sessionEnd`** (feature `session-resume`, OATS
|
|
3628
3708
|
0.69): how the last session of a launched home that does not run ended:
|
|
3629
|
-
`lost` (the host went down, its tmux server died,
|
|
3630
|
-
by a signal
|
|
3709
|
+
`lost` (the host went down, its tmux server died, the harness was killed
|
|
3710
|
+
by a signal, or `oats host run` stopped it because the host was stopping:
|
|
3711
|
+
the sweep brings it back when it can vouch for the loss,
|
|
3631
3712
|
[Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
|
|
3632
3713
|
`oats instance stop`, Desktop's Stop, or an `oats session restart` whose
|
|
3633
3714
|
relaunch did not happen) or `exited` (the harness ended by
|
|
@@ -3685,7 +3766,7 @@ its absence.
|
|
|
3685
3766
|
| the marker, and the result file `.oats-retired-<instance>.json` with `ok: false` | `failed`, with `code` and `message` | `true` | the result's `completedAt`, else the marker's `requestedAt` |
|
|
3686
3767
|
| the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
|
|
3687
3768
|
| the marker, no failed result, the completion's liveness cannot be read, or the marker names no completion process | `unknown` | `true` | the marker's `requestedAt` |
|
|
3688
|
-
| the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
|
|
3769
|
+
| the marker, no failed result, its completion process gone (it ended, its pid runs with another start, or the marker's `completionBoot` is another boot) | `interrupted` | `true` | the marker's `requestedAt` |
|
|
3689
3770
|
| a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
|
|
3690
3771
|
| no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
|
|
3691
3772
|
| no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
|
|
@@ -5007,8 +5088,15 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
|
|
|
5007
5088
|
- `retiring` and `stopPending`, booleans on every target, say who holds the
|
|
5008
5089
|
target's home when the plan is read (OATS 0.52.0, feature
|
|
5009
5090
|
`lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
|
|
5010
|
-
(its pending marker is there
|
|
5011
|
-
|
|
5091
|
+
(its pending marker is there, and the completion the marker names is not
|
|
5092
|
+
gone: it lives, its liveness cannot be read, or the marker names none),
|
|
5093
|
+
or a retire holds its
|
|
5094
|
+
[claim](#retire-one-at-a-time). A marker whose completion is gone (it
|
|
5095
|
+
ended, its pid runs with another start, or the marker was written in
|
|
5096
|
+
another boot) is `retiring: false`, and the apply stops the target: the
|
|
5097
|
+
home is owed its retire and nothing carries it out
|
|
5098
|
+
([a completion that was killed](souls-and-instances.md#self-retire-interrupted)).
|
|
5099
|
+
From 0.53.0 the marker outlasts a
|
|
5012
5100
|
completion that did not complete only when a retire hook was started or
|
|
5013
5101
|
the removal of the home began
|
|
5014
5102
|
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
@@ -5071,7 +5159,8 @@ this order:
|
|
|
5071
5159
|
retired since the plan was shown answers `E_SESSION_UNKNOWN`; one whose
|
|
5072
5160
|
`instance.json` can no longer be read, `E_UNIDENTIFIED_INSTANCE_HOME`; a
|
|
5073
5161
|
child in that state is no longer a target, which is a changed plan.
|
|
5074
|
-
6. It refuses a target for which a self-retire is scheduled
|
|
5162
|
+
6. It refuses a target for which a self-retire is scheduled, unless the
|
|
5163
|
+
completion its marker names is gone
|
|
5075
5164
|
(`E_INSTANCE_RETIRING`, with `details.plan`).
|
|
5076
5165
|
7. It stops each target, writes the receipt and releases the claims.
|
|
5077
5166
|
|
|
@@ -5385,7 +5474,9 @@ answers. The following stop/retire notes describe the original table.
|
|
|
5385
5474
|
([a completion that does not complete](souls-and-instances.md#self-retire-not-completed)).
|
|
5386
5475
|
A retire reads the marker under the claim, while
|
|
5387
5476
|
the completion lives (`E_LIFECYCLE_BUSY`, [below](#retire-one-at-a-time)).
|
|
5388
|
-
A stop apply reads it in the plan it makes under its claims
|
|
5477
|
+
A stop apply reads it in the plan it makes under its claims, and it holds
|
|
5478
|
+
the home against a stop while its completion is not gone
|
|
5479
|
+
([`retiring`](#stop-claim)): a plan that
|
|
5389
5480
|
showed `retiring: true` is answered `E_INSTANCE_RETIRING`, and an apply
|
|
5390
5481
|
whose plan was shown before the retire was scheduled is answered
|
|
5391
5482
|
`E_PLAN_STALE` first, with the fresh plan.
|
|
@@ -6290,7 +6381,19 @@ zombie) has died: its claim is taken over without waiting for that reap
|
|
|
6290
6381
|
(0.52.0, #870; before, the retire was refused as running until the reap). The
|
|
6291
6382
|
claim does not end what the killed retire left running: one of its retire
|
|
6292
6383
|
hooks may still be running when the next retire takes the claim over and
|
|
6293
|
-
runs
|
|
6384
|
+
runs that hook again (#865). <a id="retire-hooks-in-claim"></a>The retire
|
|
6385
|
+
that takes over does not run again a retire hook the killed one had
|
|
6386
|
+
finished: a retire records each hook that ended in its claim, as
|
|
6387
|
+
`retireHooks: [{capability, meta?}]` (the `meta` that hook answered) with
|
|
6388
|
+
`retireHooksFor`, the home's `createdAt`, and the next holder skips those
|
|
6389
|
+
hooks and judges the cleanup, and writes its `retired` row, with their
|
|
6390
|
+
`meta` as if it had run them. A hook that had not ended is run again. Only
|
|
6391
|
+
a take-over reads the list: a retire that returns removes its claim, so
|
|
6392
|
+
the retry of a quarantined home, and each retry a self-retire's completion
|
|
6393
|
+
makes of a cleanup its hooks left incomplete, runs every hook again. A
|
|
6394
|
+
claim without the list, or whose list names another incarnation, skips
|
|
6395
|
+
nothing, and of a list only the entries that name a capability of this
|
|
6396
|
+
home with a retire hook count. Until
|
|
6294
6397
|
that name is retired again its claim file stays where it is, and it is safe
|
|
6295
6398
|
to remove once its pid is gone. A retire that ends removes its claim file;
|
|
6296
6399
|
the `claims/` directory itself stays, empty.
|
|
@@ -6359,8 +6462,9 @@ line and says that nothing was done:
|
|
|
6359
6462
|
Then the command again.
|
|
6360
6463
|
|
|
6361
6464
|
A scheduled self-retire counts from the moment it is scheduled. Its pending
|
|
6362
|
-
marker (`pendingMarker`) records the completion process as `completionPid
|
|
6363
|
-
|
|
6465
|
+
marker (`pendingMarker`) records the completion process as `completionPid`,
|
|
6466
|
+
`completionStart` and `completionBoot`, the boot it runs in (each of the two
|
|
6467
|
+
`null` when it could not be read). While that
|
|
6364
6468
|
process lives, every other retire of the instance is refused the same way,
|
|
6365
6469
|
`--self --keep-dir` included: `a retire of <name> is already scheduled (its
|
|
6366
6470
|
completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
|
|
@@ -6374,7 +6478,10 @@ claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
|
|
|
6374
6478
|
retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
|
|
6375
6479
|
left its outcome at `resultPath` (it failed) or is gone (it died; a
|
|
6376
6480
|
completion that is a zombie, not reaped by its parent, has died: 0.52.0,
|
|
6377
|
-
#870
|
|
6481
|
+
#870; one whose marker names another boot than this one is gone whatever
|
|
6482
|
+
its pid reads as, since a boot ends every process and a pid and a start can
|
|
6483
|
+
both come again in the next; a marker that names no boot is judged by its
|
|
6484
|
+
process alone), nor when
|
|
6378
6485
|
it names no completion (a marker written before 0.51.0): `oats retire
|
|
6379
6486
|
<instance>` then retries the retirement, as before. The completion does not
|
|
6380
6487
|
start its retire while the retire that scheduled it holds the claim: it
|
|
@@ -6443,14 +6550,17 @@ Git reads as the top level of a `work/` whose `core.worktree` names another
|
|
|
6443
6550
|
one),
|
|
6444
6551
|
`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
|
|
6445
6552
|
`E_UNIDENTIFIED_INSTANCE_HOME` (a home with no `instance.json` and no cleanup
|
|
6446
|
-
descriptor, or a rollback marker that cannot drive a retry,
|
|
6553
|
+
descriptor, or a rollback marker that cannot drive a retry, or an
|
|
6554
|
+
`instance.json` that names no repository and does not show that no capability
|
|
6555
|
+
has a retire hook, what a spawn killed before its record leaves
|
|
6556
|
+
([capabilities.md](capabilities.md#manifest)), until `--force`;
|
|
6447
6557
|
a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
|
|
6448
6558
|
and `--force` included),
|
|
6449
6559
|
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
|
|
6450
6560
|
home is running or scheduled, or a stop of it is running, `--force`
|
|
6451
6561
|
included: one retire or stop of a home at a time, above; or, feature
|
|
6452
|
-
`worktree-event`: the home is a spawn still running its `worktree`
|
|
6453
|
-
row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
6562
|
+
`worktree-event`: the home is a spawn still running its spawn or `worktree`
|
|
6563
|
+
hooks, a row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
6454
6564
|
cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
|
|
6455
6565
|
group whose leader's start cannot be read, until `--force`; every one is
|
|
6456
6566
|
answered before any effect and carries [`details.holder`](#busy-holder)). The
|
|
@@ -7103,6 +7213,64 @@ whatever the rows say:
|
|
|
7103
7213
|
`E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
|
|
7104
7214
|
sweep's failure.
|
|
7105
7215
|
|
|
7216
|
+
### The host run (`oats host run`)
|
|
7217
|
+
|
|
7218
|
+
`oats host run [--stop-grace <seconds>] [--plan] [--json]` runs
|
|
7219
|
+
the kernel's periodic work in one foreground process, for a host where no
|
|
7220
|
+
timer can ([container.md](container.md#the-kernels-periodic-work)). It is
|
|
7221
|
+
this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
|
|
7222
|
+
|
|
7223
|
+
- **Refused before any effect**, through the standard failure envelope, exit 1:
|
|
7224
|
+
- `E_USAGE`: `OATS_INSTANCE_HOME` is set (it runs as the host, never inside
|
|
7225
|
+
an instance session);
|
|
7226
|
+
- `E_HOST_RUN_TIMER_ACTIVE`: the host timer is active, so two tickers would
|
|
7227
|
+
run; `error.details` `{unit}`. Unit files that are installed and not
|
|
7228
|
+
active are a warning, not a refusal;
|
|
7229
|
+
- `E_HOST_RUN_BUSY`: another `oats host run` holds this machine's lock
|
|
7230
|
+
(`<OATS_HOME_DIR>/host-run/lock`, a kernel-private file), or the lock
|
|
7231
|
+
cannot be judged; `error.details` `{lock, found}`, `found` as
|
|
7232
|
+
`E_RESUME_LOCK_STUCK` names it, and `running` for a host run that runs.
|
|
7233
|
+
A lock whose holder is gone, or that was taken in another boot (in a
|
|
7234
|
+
container, another run), is taken over;
|
|
7235
|
+
- `E_BAD_ARGS`: a flag it does not define, an argument, a `--stop-grace`
|
|
7236
|
+
that is not 1 to 300 seconds, a verb other than `run`.
|
|
7237
|
+
|
|
7238
|
+
Any other failure of the run itself is `E_HOST_RUN_FAILED`, which says
|
|
7239
|
+
nothing of how far it got. A child that ended without an answer is
|
|
7240
|
+
reported under that code too, in `sweep.error` or on stderr, and does not
|
|
7241
|
+
end the run.
|
|
7242
|
+
- **What it runs, in order.** The resume sweep once (`oats session resume`).
|
|
7243
|
+
Then at second 0 of every minute: `oats schedule tick --host` when the
|
|
7244
|
+
host schedule registry lists a scope, and a listing of every deployment's
|
|
7245
|
+
instances, which records what runs for the next start's sweep. Each is a
|
|
7246
|
+
child process. A minute whose tick still runs is skipped; a minute missed
|
|
7247
|
+
is never replayed. With no scope registered it ticks nothing and says so.
|
|
7248
|
+
- **On SIGTERM or SIGINT.** No further minute starts; a tick or a sweep that
|
|
7249
|
+
runs is waited for; it lists once; then it stops every running home, side
|
|
7250
|
+
by side, each with the stop `oats session restart` uses: SIGTERM to the
|
|
7251
|
+
harness, a wait of `--stop-grace` seconds (default 20), never escalated.
|
|
7252
|
+
Each home's stop record is written before its harness is signalled and
|
|
7253
|
+
says `"resume": true, "reason": "host-stop"`, so the home reads
|
|
7254
|
+
`sessionEnd: "lost"` and the next start's sweep resumes it. It exits 0.
|
|
7255
|
+
- **Progress** is one line per event on stderr (`oats host run: …`), in both
|
|
7256
|
+
modes. **The answer** is written once, when the run ends:
|
|
7257
|
+
`result` `{schemaVersion: 1, plan: false, signal, warnings, sweep, ticks, stopped}`.
|
|
7258
|
+
`signal` is `"SIGTERM"` or `"SIGINT"`; `warnings` an array of strings;
|
|
7259
|
+
`sweep` the sweep's own `result`
|
|
7260
|
+
([The machine sweep](#the-machine-sweep-oats-session-resume)), or
|
|
7261
|
+
`{error: {code, message}}` when it failed (the run goes on); `ticks`
|
|
7262
|
+
`{run, skipped, failed, noScope}`, minutes counted; `stopped` one row per
|
|
7263
|
+
home that ran when it stopped: `{ok: true, home, stopped, alreadyIdle, state}`
|
|
7264
|
+
or `{ok: false, home, code, message, stillRunning}` (`stillRunning`: the
|
|
7265
|
+
pids the stop established as alive, or `null`). A home that did not stop is
|
|
7266
|
+
a row, never the run's failure.
|
|
7267
|
+
- **`--plan`** starts nothing, takes no lock and writes nothing: `result`
|
|
7268
|
+
`{schemaVersion: 1, plan: true, refusals, warnings, scopes, sweep}`.
|
|
7269
|
+
`refusals` is every refusal a run would meet now, in a run's order, each
|
|
7270
|
+
`{code, message, details?}`; `scopes` the registered scopes it would tick;
|
|
7271
|
+
`sweep` the sweep's `--plan` result. It exits 0 also when `refusals` is not
|
|
7272
|
+
empty.
|
|
7273
|
+
|
|
7106
7274
|
### Upload
|
|
7107
7275
|
|
|
7108
7276
|
```text
|
|
@@ -7367,6 +7535,27 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
|
|
|
7367
7535
|
`command` or `operation` attempt with `exited: true` (0.40.0) holds no host
|
|
7368
7536
|
slot (`running: false`) but still blocks its own job; show it as needing
|
|
7369
7537
|
`oats schedule reconcile <id>` (or `--clear`) either way.
|
|
7538
|
+
- **A slot whose record cannot be read** keeps `running: true`. The tick
|
|
7539
|
+
reports its job `invalid` (`E_SCHEDULE_INVALID`) and runs the scope's
|
|
7540
|
+
other jobs; `reconcile <id>` answers `{reconciled: "unknown", remedy}`
|
|
7541
|
+
and `reconcile <id> --clear` releases the slot (`reconciled: "cleared"`).
|
|
7542
|
+
`oats doctor --json` lists it as a `schedule-slot-unreadable` problem,
|
|
7543
|
+
`{code, severity, scope, id, message, remedy}`
|
|
7544
|
+
([Schedules](schedules.md#files)).
|
|
7545
|
+
- **A slot whose schedule is gone** (a local one not in
|
|
7546
|
+
`oats-schedules.json`; a workspace one not in the saved snapshot, decided
|
|
7547
|
+
without refreshing it), readable or not, is counted by every tick until it
|
|
7548
|
+
is released. `reconcile <id>` answers `{schedule: null, reconciled:
|
|
7549
|
+
"unknown", remedy}` naming the run its record names, and `reconcile <id>
|
|
7550
|
+
--clear` releases it, resolves a retained attempt as cleared and removes
|
|
7551
|
+
the job's state: `{schedule: null, reconciled: "cleared", cleared}`,
|
|
7552
|
+
`cleared` listing `"slot"`, `"attempt"` and `"state"` as each was there;
|
|
7553
|
+
a gone schedule with retained state and no slot is reconciled the same
|
|
7554
|
+
way (`cleared: ["attempt", "state"]`).
|
|
7555
|
+
A workspace schedule that is disabled, untrusted or placed elsewhere is
|
|
7556
|
+
not gone (`E_AUTOMATION_NOT_HERE`). `oats doctor --json` lists the slot as
|
|
7557
|
+
a `schedule-slot-orphaned` problem of the same shape
|
|
7558
|
+
([Schedules](schedules.md#files)).
|
|
7370
7559
|
- **Schedule IDs**: local and workspace schedule definition names permit 1–100
|
|
7371
7560
|
lowercase letters, digits and dashes; trigger names retain their 40-character
|
|
7372
7561
|
limit. Desktop accepts these schedule names for creation, editing and row
|
|
@@ -7421,6 +7610,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
|
|
|
7421
7610
|
`disable` → `{schedule}`. `run [--force]`, `remove [--force]`, `reconcile
|
|
7422
7611
|
[--clear]` → the action's receipt. `tick [--dry-run] [--host]` →
|
|
7423
7612
|
`{tickedAt, considered, scheduler}`; `host install` → `{scheduler, warnings}`;
|
|
7613
|
+
`host install --register-only` → the same answer, the scope recorded in the
|
|
7614
|
+
host registry and no unit installed (`scheduler.registered: true`,
|
|
7615
|
+
`installed: false`, `warnings: []`), for a host whose ticker is
|
|
7616
|
+
[`oats host run`](#the-host-run-oats-host-run); it does not go with
|
|
7617
|
+
`--print` (`E_BAD_ARGS`), and with `--server` the host must advertise
|
|
7618
|
+
`schedule` and `schedule-host-register-only` (`E_REMOTE_INCOMPATIBLE`
|
|
7619
|
+
otherwise, before anything is sent: nothing is installed there);
|
|
7424
7620
|
`host uninstall | status` → `{scheduler}`; `host install --print [--os
|
|
7425
7621
|
darwin|linux]` → `{kind, files: {<path>: <content>}, warnings}`, writing
|
|
7426
7622
|
nothing.
|
package/docs/desktop.md
CHANGED
|
@@ -735,7 +735,7 @@ deployment. Details are in
|
|
|
735
735
|
|
|
736
736
|
Open **Automations › Schedules** in the selected workspace (the sidebar's
|
|
737
737
|
**Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
|
|
738
|
-
wake an existing agent with a message, or
|
|
738
|
+
wake an existing agent with a message, or run a provider operation on it. **Schedule…**
|
|
739
739
|
on a Soul roster card preselects that soul. Choose the task or message, repeat
|
|
740
740
|
pattern and time zone; new agent jobs also offer harness, model, permissions
|
|
741
741
|
and session backend. The list shows the next run, last observed outcome and
|
|
@@ -1096,7 +1096,7 @@ their name. It is decorative: the name beside it is authoritative. The letters
|
|
|
1096
1096
|
come from the name without its package qualifier (what follows the last `/`
|
|
1097
1097
|
or `--`), and from three words or more without its first (a namespace word like
|
|
1098
1098
|
`oats`): the initials of the first two words, or a one-word name's first two
|
|
1099
|
-
letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-
|
|
1099
|
+
letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-maintainer` KM and
|
|
1100
1100
|
`oats.aweb` OA. Two names can share a mark (`oats-expert` and
|
|
1101
1101
|
`oats-operator-expert` are both OE); the name and the colour tell them apart.
|
|
1102
1102
|
|
|
@@ -1122,7 +1122,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
1122
1122
|
stop, retire or start as a process in its own session.
|
|
1123
1123
|
- Task text for spawns travels via an owner-only (0600) tempfile, never
|
|
1124
1124
|
argv. A local start or restart launches only in the server-verified
|
|
1125
|
-
instance home. A provider operation on an instance
|
|
1125
|
+
instance home. A provider operation on an instance
|
|
1126
1126
|
is addressed with `--home` to a home the server's roster reports, and one
|
|
1127
1127
|
on a soul to a soul and agents root the server lists, never a path the
|
|
1128
1128
|
caller names.
|
|
@@ -1228,6 +1228,7 @@ for its current start (`startId` in `instance.json`):
|
|
|
1228
1228
|
| What the home holds for its current start | `sessionEnd` | Resumed |
|
|
1229
1229
|
|---|---|---|
|
|
1230
1230
|
| a stop's record that names it (or, a record from before 0.69, written after the start) | `stopped` | no |
|
|
1231
|
+
| a stop's record that names it and says `resume: true`: OATS stopped it with the host (`oats host run`, [desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)), whatever the exit marker says | `lost` | when the sweep can vouch for the loss |
|
|
1231
1232
|
| an exit marker that names it with an exit status below 128 (`/exit`, Ctrl-C handled by the harness, its own error), or the marker of a kernel before 0.69 | `exited` | no: the row offers Start, as before |
|
|
1232
1233
|
| an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
|
|
1233
1234
|
| neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
|
|
@@ -1238,13 +1239,21 @@ without `sessionEnd`, prints `idle`, with one line under it naming the way
|
|
|
1238
1239
|
back: `oats session start --resume --home <home>`, or the next sweep (`oats
|
|
1239
1240
|
session resume`, which OATS Desktop and `oats tui` run when they open) when
|
|
1240
1241
|
it can vouch for the loss. Both act on this machine's homes only, so a row
|
|
1241
|
-
of another host names the host to run them on.
|
|
1242
|
+
of another host names the host to run them on. A local row whose home was
|
|
1243
|
+
stopped with the host says so in that line: `lost (stopped with the host):
|
|
1244
|
+
…`. The reason is read from the home's stop record; `sessionEnd` has no
|
|
1245
|
+
fourth value and the row carries no reason.
|
|
1242
1246
|
|
|
1243
1247
|
The window a spawn or a start makes writes the exit marker,
|
|
1244
1248
|
`.oats-start-exited`, when the harness exits; `oats instance stop` writes its
|
|
1245
1249
|
record, `.oats-stop.json`, and so do a retire, before it ends the window
|
|
1246
1250
|
(0.69.2), and `oats session restart`, before it stops the harness (#1601). Both are kernel-private files of the home, not a
|
|
1247
|
-
contract: read `sessionEnd`.
|
|
1251
|
+
contract: read `sessionEnd`. One part of the stop record is a contract: when
|
|
1252
|
+
`oats host run` stops a home because the host is stopping, the record says
|
|
1253
|
+
`"resume": true` and `"reason": "host-stop"`, and is written before the
|
|
1254
|
+
harness is signalled, so a host that is killed while the harness ends still
|
|
1255
|
+
leaves a home that reads `lost`. Such a home is brought back by the sweep of
|
|
1256
|
+
the host's next start, under the rules below like any other loss. A shutdown kills the window's shell with the
|
|
1248
1257
|
harness, so a lost session leaves no marker. A home spawned before 0.69 and
|
|
1249
1258
|
never restarted since names no start: it reads `stopped` only after a stop,
|
|
1250
1259
|
and otherwise `lost`, also when its harness ended by itself. It comes back only
|
|
@@ -1901,7 +1910,10 @@ conversation (OATS 0.69, #1559). In a fresh conversation the instance resumes
|
|
|
1901
1910
|
its work from its own state files, as its knowledge capability prescribes.
|
|
1902
1911
|
|
|
1903
1912
|
The task's text never travels on a command line, where any local user could
|
|
1904
|
-
read it in the process list
|
|
1913
|
+
read it in the process list. A spawn through a server sends it on the ssh
|
|
1914
|
+
session's standard input to a server that advertises `spawn-task-stdin`; an
|
|
1915
|
+
older server gets it as an argument, and the answer warns
|
|
1916
|
+
([servers.md](servers.md#a-routed-spawns-task)). To the harness:
|
|
1905
1917
|
|
|
1906
1918
|
- pi and Claude Code get `@TASK.md`, which each harness reads as the file.
|
|
1907
1919
|
pi sends it as the session's first prompt and refuses it if another
|
package/docs/first-team.md
CHANGED
|
@@ -20,9 +20,10 @@ declaration and locked to a commit and integrity). Nothing is installed.
|
|
|
20
20
|
|
|
21
21
|
## 0. Prerequisites
|
|
22
22
|
|
|
23
|
-
Node.js 22
|
|
24
|
-
|
|
25
|
-
harness (Pi, Claude or
|
|
23
|
+
Node.js 22.5 or later (the floor `@awebai/oats` declares in `engines`), Git
|
|
24
|
+
with read access to the repositories below (your own credential helpers; the
|
|
25
|
+
kernel never prompts), tmux, and an authenticated harness (Pi, Claude or
|
|
26
|
+
Codex).
|
|
26
27
|
|
|
27
28
|
```bash
|
|
28
29
|
npm install -g @awebai/oats@latest
|
package/docs/implementation.md
CHANGED
|
@@ -84,7 +84,7 @@ and the rules its tests pin.
|
|
|
84
84
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
85
85
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
86
86
|
| `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skills adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
|
|
87
|
-
| `mirrors/` |
|
|
87
|
+
| `mirrors/` | copies of the official packages' capabilities at their pinned tags: release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package. The three OKF mirrors (`oats-okf*`) are generated by `scripts/check-okf-mirror.mjs` and checked byte for byte against `scripts/okf-source-inventory.json`; the other seven (`oats-aweb`, `oats-aweb-tasks`, `oats-folio`, `oats-library`, `oats-jira`, `oats-linear`, `oats-authoring`) are copied from their tags by hand and checked for their version only, until every mirror has that check (oats-project/oats#1848) |
|
|
88
88
|
| `oats-package/` | the `oats.framework` package |
|
|
89
89
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
90
90
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
@@ -96,7 +96,7 @@ and the rules its tests pin.
|
|
|
96
96
|
|
|
97
97
|
| module | owns |
|
|
98
98
|
|---|---|
|
|
99
|
-
| `remote.mjs` | repo refs, reading Git remotes, content digests; `displayRepoRef` and `displayDiagnosticText` select reference-value and kernel-prose contexts for one private renderer, which owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
|
|
99
|
+
| `remote.mjs` | repo refs, reading Git remotes, content digests; `displayRepoRef` and `displayDiagnosticText` select reference-value and kernel-prose contexts for one private renderer, which owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes. The owner of a cache write lock is judged by `identityHolderState` (`packages/record/lib/process-identity.mjs`, below), where the rule for a lock record's holder is composed; `ownerGone` reclaims on `"gone"` alone |
|
|
100
100
|
| `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
|
|
101
101
|
| `workspace.mjs` | workspace, membership and soul files; discovery |
|
|
102
102
|
| `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
|
|
@@ -126,21 +126,24 @@ and the rules its tests pin.
|
|
|
126
126
|
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. The same discipline decides `souls.disabled`: `disabledEntriesUnmatched` in `instance-resolution.mjs` is the one function that decides which entries name no soul, by spawn's own rule (`disabledEntry`) over the offered souls, with `soulsOffered`'s reasons as the proof boundary; both checks share the reason sentences (`uncheckedSentences`, said of a key or an entry) and the ranking of the nearest souls (`nearestSoulKeys`), and `oats doctor` reads this machine's cache once for both (`doctorDiscovery`). What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|
|
127
127
|
| `shell-word.mjs` | `shellWord` and `shq`: one word of a command the kernel prints for a person to paste into a shell. It imports nothing, so `launch-preference.mjs` quotes by the rule `core.mjs` re-exports |
|
|
128
128
|
| `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
|
|
129
|
-
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
129
|
+
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer; a job's slot (`acquireJobLock`, `releaseJobLock`) is taken by renaming a directory that already holds its record into place, and released by renaming it out before it is removed, so it is never there without its record; a slot whose record cannot be read (`unreadableSlot`, over `jobLockInfo`) marks only its job invalid in the tick, is released by `reconcile --clear`, and is doctor's `schedule-slot-unreadable` problem; a slot whose schedule is gone (`scheduleAbsence`: a local one not in `oats-schedules.json`; a workspace one not in the saved snapshot, its member read at a commit and no problem of it that could hide one; never refreshed there) is counted until reconcile --clear releases it with the job's attempt and state (`orphanSlot`, `reconcileOrphanSlot`), and is doctor's `schedule-slot-orphaned` problem, as is a workspace one absent that cannot be shown gone |
|
|
130
130
|
| `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: one producer, `listInstances`; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
|
|
131
131
|
| `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
|
|
132
132
|
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
133
133
|
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
134
|
+
| `host-run.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep once and the tick and the listing each minute, every one an `oats` child (`session-resume.mjs` `kernelAnswer`) so that the loop stays free for the signal, and the stop on SIGTERM: ticking ends, then each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
|
|
134
135
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
135
136
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
136
137
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
137
138
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
|
|
138
139
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
|
|
139
140
|
| `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
|
|
140
|
-
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
|
|
141
|
+
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too A holder may add to its record as it goes (`recordInClaim`), and the next holder reads what a gone one left: a worktree add its running Git step; a retire the retire hooks that ended, `retireHooks: [{capability, meta?}]` with `retireHooksFor` (the home's `createdAt`: the list is bound to the incarnation it ran for, so a claim left by a retire that is gone never skips hooks for another home of the same name), which the retire that takes the claim over does not run again (`core.mjs` `finishedRetireHooks`; `claimHomeFor` hands the gone holder's record over as `tookOver`). A record without them skips nothing. |
|
|
141
142
|
| `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`; `exact` gives the mode whatever the umask, as `core.mjs` `writeHomeRecord`, the kernel's write of a home's record, needs): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, a failed removal reported, a sync) keeps its own code |
|
|
142
|
-
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL. Two questions, two functions: `processStart` says whose a pid is (a zombie still holds its pid and start, which is what proves a recorded process group), `processLiveness` says whether the `oats` command a record names can still act (a zombie cannot: it is gone). Ask `processLiveness` only about an `oats` command's own process, never about a hook's or a harness's pid. `runPs` is the one way the kernel calls `ps` where an identity is read: the program, the fixed environment and how the answer is classified. `isStartToken` says the shape of a start token, once, beside its writer: it decides what of a record may be shown (`claim.mjs` `shownHolder`, `unknownGroupNote`), never whether a process lives |
|
|
143
|
-
| `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`: `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin`, in that order), never from the caller's `PATH`. `ps` runs on the same directories: `
|
|
143
|
+
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time (read in `packages/record/lib/process-identity.mjs`, below, and re-exported here), and the credential-free `origin` URL. Two questions, two functions: `processStart` says whose a pid is (a zombie still holds its pid and start, which is what proves a recorded process group), `processLiveness` says whether the `oats` command a record names can still act (a zombie cannot: it is gone). Ask `processLiveness` only about an `oats` command's own process, never about a hook's or a harness's pid. `runPs` is the one way the kernel calls `ps` where an identity is read: the program, the fixed environment and how the answer is classified. `isStartToken` says the shape of a start token, once, beside its writer: it decides what of a record may be shown (`claim.mjs` `shownHolder`, `unknownGroupNote`), never whether a process lives |
|
|
144
|
+
| `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`: `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin`, in that order), never from the caller's `PATH`. `ps` runs on the same directories: `PS_ENV` takes its `PATH` from them. macOS's boot id (`bootId`) reads `sysctl` from them. The lookup and its one list of directories are `packages/record/lib/process-identity.mjs`'s, re-exported here |
|
|
145
|
+
| `packages/record/lib/process-identity.mjs` | what a lock record names its holder by and how a recorded holder is judged, in one dependency-free module of the turn-record package, so that the kernel and the package's own locks (which import nothing of the kernel) judge by the same code: the start token of a pid (`processStart`, `processStartToken`, `isStartToken`, `runPs`, `PS_ENV`), whether a pid exists (`existence`), whether the process a record names can still act (`processLiveness`), this boot's identity (`bootId`, `thisBoot`), the rule for a record taken in another boot (`takenInAnotherBoot`) and the system-tool lookup they run (`systemTool`, `systemToolDirs`, `SYSTEM_TOOL_DIRS`). `identityHolderState` is the one place the rule for a lock record's holder is composed: `"gone"` when the record was taken in another boot, else what its process says (`"alive"`, `"gone"`, `"unknown"`), and by its pid alone when the record names neither boot nor start (`namesIdentity`). A record whose pid is no process ID (`validPid`), and a pid whose existence cannot be read, are `"unknown"`, decided there and nowhere else; only `"gone"` lets a caller take a lock over. Its callers are `remote.mjs` `ownerGone` (the cache write lock) and `packages/record/lib/lock-holder.mjs`; a claim's holder is read by `claim.mjs` `holderLiveness`, which takes its caller's own `holderGone`. `worktree-hooks.mjs`, `session-seen.mjs` and `system-tools.mjs` re-export the module's names under the ones their callers import |
|
|
146
|
+
| `packages/record/lib/lock-holder.mjs` | the holder a turn-record lock names (the capture lock's owner, worker and reclaim guard, the stream lock's token): what a record names it by (`holderIdentity`) and `holderLiveness`, which is `identityHolderState` in the package's words (`"alive"`, `"dead"`, `"unknown"`) and decides nothing itself ([the package's README](../packages/record/README.md#durability-and-concurrency)) |
|
|
144
147
|
| `tmux-server-scope.mjs` | where sessions run on a systemd host: whether the OATS tmux server starts in a scope of its own (the creator's cgroup judged: Linux, unified hierarchy, inside a `.service` or a scope of the user manager), and whether each agent's harness is launched in one (`agentScope`: the probe, run with the pane's bus variables and cached per process, and the wrapper `nativeRecordCommand` renders); the scopes' names and the warnings when they cannot |
|
|
145
148
|
| `session-*.mjs` | the tmux session backend and terminal input |
|
|
146
149
|
| `launch-env.mjs`, `launch-env-exec.sh` | host-side launch reference resolution and a private per-start 0600 handoff: aliases reach the pane without values in tmux argv; the shell launcher reads and deletes the file before executing the pane command. A later start removes abandoned handoffs before dispatch; retirement recovery excludes them. |
|
|
@@ -506,10 +509,17 @@ the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
|
|
|
506
509
|
lives (bounded by a whole fetch, then `reason: "cache"` naming the pid and
|
|
507
510
|
saying to check whether it is an oats process: once no oats process holds
|
|
508
511
|
it, the lock is safe to remove), reclaimed when the holder is gone, and
|
|
509
|
-
released only by its owner. A holder is judged by its pid, boot and start
|
|
510
|
-
|
|
512
|
+
released only by its owner. A holder is judged by its pid, boot and start
|
|
513
|
+
(`identityHolderState`, `packages/record/lib/process-identity.mjs`), by the
|
|
514
|
+
rules a claim's holder is judged by: a lock taken in another boot, or
|
|
511
515
|
whose pid is gone or runs with another start (a reused pid), is reclaimed
|
|
512
|
-
at once
|
|
516
|
+
at once. An owner whose liveness cannot be judged is never reclaimed: one
|
|
517
|
+
whose start cannot be read, one whose pid cannot be checked (`kill`
|
|
518
|
+
answers neither `ESRCH` nor `EPERM`), and a record whose pid is no process
|
|
519
|
+
ID (zero, a negative number, one above the range). Its lock is waited for
|
|
520
|
+
and refused as a live holder's is; for a pid that is no process ID the
|
|
521
|
+
refusal says that the lock names none and is safe to remove once no oats
|
|
522
|
+
process is running, and carries no `holderPid`. A record that
|
|
513
523
|
names no boot or start, as an earlier kernel writes it, is judged by its
|
|
514
524
|
pid alone, and so is every record by that kernel. Reclaimers take a short guard,
|
|
515
525
|
`<lock>.reclaim`, and check under it that the lock is still the dead
|