@awebai/oats 0.55.0 → 0.56.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +78 -62
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +317 -35
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +54 -7
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +54 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +35 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.55.1.md +45 -0
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +8 -4
- package/docs/tui.md +99 -26
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +480 -152
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +47 -30
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +10 -6
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +228 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/record/README.md +4 -0
- package/packages/record/bin/recall.mjs +3 -2
- package/packages/tui/README.md +10 -6
- package/packages/tui/lib/actions.mjs +4 -2
- package/packages/tui/lib/client.mjs +5 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +83 -13
- package/packages/tui/lib/model.mjs +116 -11
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +46 -10
- package/packages/tui/lib/store.mjs +64 -9
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/frame.mjs +115 -33
- package/packages/tui/lib/views/help.mjs +37 -8
- package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/desktop-cli-api.md
CHANGED
|
@@ -45,7 +45,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
|
-
"soul-launch","retire-plan-own-worktree"],
|
|
48
|
+
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"],
|
|
49
49
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
50
50
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
51
51
|
"capabilityShowApi":1}
|
|
@@ -117,6 +117,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
117
117
|
| `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
|
|
118
118
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
119
119
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
120
|
+
| `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
120
121
|
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
121
122
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
122
123
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
@@ -128,6 +129,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
128
129
|
| `launch-prompt-dev-channel` | the kernel confirms Claude's development-channel prompt whenever it launches Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`, with no consent setting; `launchPromptAnswers` gone from previews; `consentSource` gone from `launch-prompt` events, which carry `claudeVersion`, `claudeVersionSource` and, on a miss, `differed`; `launchPrompts.status: "not-engaged"` and `"flag-ignored"`; `launchPrompts` in a launched spawn's answer; the `launch-prompt` readiness warning, OATS 0.52.0 ([Launch prompt results](#launch-prompt-results)) | |
|
|
129
130
|
| `soul-launch` | `oats soul launch set\|remove`, the writer of `oats-local.yaml` `souls.launch`, and `E_LAUNCH_PREFERENCE_UNKNOWN`, OATS 0.53.0 ([`oats soul launch`](#oats-soul-launch)). Gate on the probe: a kernel without it answers `E_USAGE` | `soulLaunchApi: 1` (payload only) |
|
|
130
131
|
| `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
|
|
132
|
+
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
133
|
+
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
131
134
|
|
|
132
135
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
133
136
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -137,6 +140,33 @@ Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
|
137
140
|
**Gate on the probe, never by trying.** An older kernel can ignore an unknown
|
|
138
141
|
flag and act: without `lifecycle-plans`, `retire --plan` retires.
|
|
139
142
|
|
|
143
|
+
## Text output
|
|
144
|
+
|
|
145
|
+
A command's text (without `--json`) is for a person and is not part of this
|
|
146
|
+
contract. Some of its lines hold text the kernel did not write: a path as the
|
|
147
|
+
system or Git names it, a branch name, a hook's or a host's own words. In the
|
|
148
|
+
lines below, each character a terminal would act on, or that hides or
|
|
149
|
+
reorders text (a control character such as an escape or a newline, a bidi
|
|
150
|
+
override: the set the kernel never prints in text it did not write), is
|
|
151
|
+
spelled `\u{<hex>}` (OATS 0.53.0 for the local retire's warnings, #973; the
|
|
152
|
+
rest 0.56.0, #1006), so that such a name cannot clear the screen, write a
|
|
153
|
+
line of its own or reverse what follows it:
|
|
154
|
+
|
|
155
|
+
- the `note:` lines of `oats retire --plan`, `oats instance stop --plan`,
|
|
156
|
+
`oats instance git` and `oats readiness`;
|
|
157
|
+
- the `WARNING:` lines of `oats spawn` (its preview, and with `--server`
|
|
158
|
+
too), of the `oats session` commands (a start's or a restart's launch-hook
|
|
159
|
+
warnings, on stderr) and of `oats doctor` (a pi bridge's version skew);
|
|
160
|
+
- the lines of `oats retire`, local and with `--server`, for the recovery it
|
|
161
|
+
wrote, for the extra trees it handled and for the receipt's warnings. A
|
|
162
|
+
retire with `--server` prints the receipt's warnings as a local one does.
|
|
163
|
+
|
|
164
|
+
A newline in such a value is spelled too, so the value stays on its line.
|
|
165
|
+
Text that already holds the characters of a spelling (`\u{1b}` written out)
|
|
166
|
+
prints as it is: a spelling is not meant to be read back. Every other line of
|
|
167
|
+
text output prints what it holds as it is. The JSON is never changed by
|
|
168
|
+
this: its strings are what they are.
|
|
169
|
+
|
|
140
170
|
## The envelope and dispatch errors
|
|
141
171
|
|
|
142
172
|
Every `--json` command except those below prints exactly one JSON object on
|
|
@@ -390,7 +420,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
390
420
|
### `oats inspect`
|
|
391
421
|
|
|
392
422
|
```text
|
|
393
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions]) [--max-age <s>] --json
|
|
423
|
+
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
|
|
394
424
|
```
|
|
395
425
|
|
|
396
426
|
An instance subject, abridged:
|
|
@@ -475,6 +505,72 @@ travels to the host; a host whose probe does not advertise
|
|
|
475
505
|
`soul-composed-instructions` is refused with `E_REMOTE_INCOMPATIBLE`, and
|
|
476
506
|
nothing is sent.
|
|
477
507
|
|
|
508
|
+
`skills` (feature `soul-skills`) is present only with `--skills`, which takes
|
|
509
|
+
a soul subject (`--home` is `E_BAD_ARGS`) and combines with `--instructions`;
|
|
510
|
+
without the flag the key is absent and no skill file is read. It lists the
|
|
511
|
+
soul's own skills, exactly the ones a spawn of it copies (not its
|
|
512
|
+
capabilities' skills), read from the same soul copy as `instructions`:
|
|
513
|
+
|
|
514
|
+
```json
|
|
515
|
+
"skills":[{"name":"release-checklist","path":"skills/release-checklist","description":"Cutting a release.",
|
|
516
|
+
"files":[{"path":"skills/release-checklist/SKILL.md","bytes":812,"text":"---\nname: release-checklist\n…","binary":false,"truncated":false},
|
|
517
|
+
{"path":"skills/release-checklist/references/notes.md","bytes":2048,"text":null,"binary":false,"truncated":false,"omitted":true}],
|
|
518
|
+
"filesTruncated":false}]
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
- `skills` is the list sorted by `name` in codepoint order; `[]` when the
|
|
522
|
+
soul has no skills of its own (no `skills/` directory, or none with a
|
|
523
|
+
`SKILL.md`); `null` when they could not be listed, with a problem below,
|
|
524
|
+
including a skill directory whose `SKILL.md` could not be examined.
|
|
525
|
+
It is also `null` when the soul's copy failed, and that copy's problem
|
|
526
|
+
explains it.
|
|
527
|
+
- A skill is a child directory of `skills/` holding a regular-file
|
|
528
|
+
`SKILL.md`, or `skills/` itself when it holds one (`name` is then
|
|
529
|
+
`skills`). `path` is POSIX and relative to the soul directory. Its
|
|
530
|
+
`description` is the `SKILL.md` front matter's `description`, by the same
|
|
531
|
+
function as [`oats capabilities show`](#oats-capabilities-show), which reads
|
|
532
|
+
the file up to 4 MiB: `null` when the file is unreadable, a symbolic link,
|
|
533
|
+
binary or over 4 MiB, or has no such string, and cut to 1024 bytes.
|
|
534
|
+
- `files` is every regular file under the skill directory, recursively,
|
|
535
|
+
sorted by `path` in codepoint order, each `path` relative to the soul
|
|
536
|
+
directory. At most 200 are listed; beyond that `filesTruncated` is `true`.
|
|
537
|
+
`files` is `null` (and `filesTruncated` `false`) when the files could not
|
|
538
|
+
be listed: an entry whose name is not a safe path component (`.git` in any
|
|
539
|
+
case, a backslash, a control character), or a listed file that cannot be
|
|
540
|
+
read safely (unreadable, gone, changed type, or refused as below). Could
|
|
541
|
+
not list never reads as listed nothing.
|
|
542
|
+
- A file is `{path, bytes, text, binary, truncated}`, by `oats capabilities
|
|
543
|
+
show`'s rules: `bytes` is its real size; `binary` (a NUL or invalid UTF-8
|
|
544
|
+
in its first 262,147 bytes) has `text: null` and `truncated: false`;
|
|
545
|
+
otherwise `text` is at most 262,144 bytes, cut on a code point boundary,
|
|
546
|
+
and `truncated` says it was cut.
|
|
547
|
+
- The whole field carries at most 1 MiB (1,048,576 bytes) of `text`, as
|
|
548
|
+
UTF-8, summed over its files in answer order. The file whose text would
|
|
549
|
+
pass that, and every file after it, has `text: null, binary: false,
|
|
550
|
+
truncated: false, omitted: true`; no other file has `omitted`, and a binary
|
|
551
|
+
file costs nothing. So `text` is `null` only with `binary: true` or
|
|
552
|
+
`omitted: true`.
|
|
553
|
+
- No symbolic link is followed. A symlinked file or directory inside a skill
|
|
554
|
+
is not listed, a symlinked skill directory is not a skill, and a symlinked
|
|
555
|
+
`skills/` makes `skills` `null` with a problem. FIFOs, sockets and devices
|
|
556
|
+
are not listed and never opened. A directory is listed, and a file read,
|
|
557
|
+
only once its real path lies inside its skill's, and the skill's inside the
|
|
558
|
+
soul's; one that does not makes the skill's `files` `null`. A file is
|
|
559
|
+
opened without following a symbolic link and must be the regular file the
|
|
560
|
+
listing found. One race remains: a parent directory swapped for a symbolic
|
|
561
|
+
link in the instant between that check and the open can redirect a read.
|
|
562
|
+
Only someone who can write the deployment's `agents/` tree can do that, and
|
|
563
|
+
they already control the soul copy and every instance's `AGENTS.md`.
|
|
564
|
+
- Problems are `{code, message}` in `problems[]`, each message starting
|
|
565
|
+
`skills: `: `soul-skills-unreadable` when the list is `null`, and
|
|
566
|
+
`soul-skill-files-unreadable`, naming the skill's `path`, for a skill whose
|
|
567
|
+
`files` is `null`.
|
|
568
|
+
|
|
569
|
+
Routed with `--server <id>`, `--skills` travels to the host; a host whose
|
|
570
|
+
probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
|
|
571
|
+
and nothing is sent. Every text is untrusted repository content: render it as
|
|
572
|
+
plain text or through a sanitising renderer.
|
|
573
|
+
|
|
478
574
|
**Layers.** `id` is the capability filling the slot or `null`. `from`
|
|
479
575
|
(feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
|
|
480
576
|
or a home spawned before it was recorded.
|
|
@@ -507,10 +603,9 @@ message}`.
|
|
|
507
603
|
|
|
508
604
|
A soul whose resolution is refused is an inspect error with the resolver's
|
|
509
605
|
code and details (`E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`,
|
|
510
|
-
`E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `
|
|
511
|
-
`
|
|
512
|
-
|
|
513
|
-
as an item. Soul lookup errors are those of [spawn](#spawn-errors).
|
|
606
|
+
`E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `E_TEAM_UNKNOWN`, and
|
|
607
|
+
`E_WORKSPACE_SCHEMA` reason `local-teams-closed`); readiness reports the same
|
|
608
|
+
condition as an item. Soul lookup errors are those of [spawn](#spawn-errors).
|
|
514
609
|
|
|
515
610
|
<a id="oats-readiness---home-----soul----dir----policy---json--readinessapi-2"></a>
|
|
516
611
|
### `oats readiness`
|
|
@@ -2353,6 +2448,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2353
2448
|
<a id="spawn-errors"></a>
|
|
2354
2449
|
### Spawn errors
|
|
2355
2450
|
|
|
2451
|
+
A spawn answers the kernel's own code, as raised, whatever stage raised it
|
|
2452
|
+
(feature `spawn-kernel-codes`, OATS 0.56.0). Beyond the codes below that is
|
|
2453
|
+
any code of the kernel a spawn reaches: the deployment's files, where the home
|
|
2454
|
+
may be, the composition written into the home, reading a package or member at
|
|
2455
|
+
its commit, the harness's packages, the session, and the work and what a
|
|
2456
|
+
failed spawn leaves. **A code says nothing about how far the spawn got:**
|
|
2457
|
+
`details.unconfirmed` does. `E_SPAWN_FAILED` is for an error with no kernel
|
|
2458
|
+
code; a kernel without `spawn-kernel-codes` answers it for most codes its
|
|
2459
|
+
kernel stage raised as well.
|
|
2460
|
+
|
|
2356
2461
|
| Code | Details | When |
|
|
2357
2462
|
|---|---|---|
|
|
2358
2463
|
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
|
|
@@ -2368,7 +2473,6 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2368
2473
|
| `E_SLOT_CONFLICT`, `E_SKILL_DUPLICATE` | | the composition conflicts |
|
|
2369
2474
|
| `E_WORKSPACE_SCHEMA` | `{path, key, reason}` | a removed key or invalid payload |
|
|
2370
2475
|
| `E_CLONE_MISSING`, `E_CLONE_MISMATCH` | | the member's clone is missing or wrong |
|
|
2371
|
-
| `E_REQUIREMENT_INACTIVE` | `{soul, capabilities, context, remedy}` | a declared requirement is not active |
|
|
2372
2476
|
| `E_CHILD_SPAWNS_DISABLED` | `{parent, policy}` | the parent's policy is off |
|
|
2373
2477
|
| `E_PARENT_NOT_FOUND`, `E_RELATIVE_NOT_FOUND` | | the anchor name matches no instance |
|
|
2374
2478
|
| `E_RELATIVE_AMBIGUOUS` | | the anchor matches several instances (`--relative-root` picks one) or a same-named instance would shadow the edge |
|
|
@@ -2378,12 +2482,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2378
2482
|
| `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
|
|
2379
2483
|
| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
|
|
2380
2484
|
| `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
|
|
2485
|
+
| `E_HARNESS_UNAVAILABLE` | `{harness, from, at, fix}` | the chosen harness has no executable on this machine ([launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) |
|
|
2486
|
+
| `E_CLAUDE_CONFIG_REMOVED` | `{file, executable, fix}` | a new claude launch with an `oats-claude-config` in reach ([configuration.md](configuration.md)) |
|
|
2487
|
+
| `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 |
|
|
2381
2488
|
| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
|
|
2382
2489
|
| `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
|
|
2383
2490
|
| `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 |
|
|
2384
2491
|
| `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` |
|
|
2385
2492
|
| `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 |
|
|
2386
|
-
| `
|
|
2493
|
+
| `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 |
|
|
2494
|
+
| `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish; `cause` for an error with a system code, or a defect | an error with no kernel code |
|
|
2387
2495
|
|
|
2388
2496
|
Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
|
|
2389
2497
|
keyed spawn is incomplete (`E_SPAWN_INCOMPLETE`) or compensation cannot confirm
|
|
@@ -2798,7 +2906,7 @@ messaging identity's `address` (else `alias`), or `null`.
|
|
|
2798
2906
|
### The remote roster (`oats server roster --json`)
|
|
2799
2907
|
|
|
2800
2908
|
```text
|
|
2801
|
-
oats server roster [--server <id>] [--per-target <ms>] [--budget <ms>] --json
|
|
2909
|
+
oats server roster [--server <id>] [--workspace-key <key>]... [--per-target <ms>] [--budget <ms>] --json
|
|
2802
2910
|
```
|
|
2803
2911
|
|
|
2804
2912
|
An envelope; `result` is `{groups, bounds}` (remote `roster`,
|
|
@@ -2883,7 +2991,9 @@ route target:
|
|
|
2883
2991
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
2884
2992
|
name is `E_AMBIGUOUS` with `error.details.candidates: [{agent, home}]`). A
|
|
2885
2993
|
saved-route row the host did not list is addressable only while the host's
|
|
2886
|
-
answer is unknown (`missingRemotely: false`).
|
|
2994
|
+
answer is unknown (`missingRemotely: false`). A row the host was reached
|
|
2995
|
+
for and did not list (`missingRemotely: true`) is the one
|
|
2996
|
+
[`server forget`](#forget-a-saved-route-oats-server-forget---json) is for.
|
|
2887
2997
|
- **`savedRoute`**: the instance was spawned from this machine and has a
|
|
2888
2998
|
saved route here. Information only; no action depends on it.
|
|
2889
2999
|
- `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
|
|
@@ -2896,6 +3006,92 @@ route target:
|
|
|
2896
3006
|
group's probe. Before 0.55.0 `bounds` also carried `skipped`, the number of
|
|
2897
3007
|
groups the budget did not reach; it is gone with `E_ROSTER_BUDGET`.
|
|
2898
3008
|
|
|
3009
|
+
<a id="roster-workspace-key"></a>
|
|
3010
|
+
**`--workspace-key <key>`** (feature `roster-workspace-key`, OATS 0.56.0,
|
|
3011
|
+
#1124) narrows the roster to the groups that can belong to the given
|
|
3012
|
+
workspaces, so a host registered for another workspace, switched off or not,
|
|
3013
|
+
costs a window nothing. The flag is repeatable and every occurrence counts;
|
|
3014
|
+
`--workspace-key=<key>`, one argument per key, is the same (`--workspace-key=`
|
|
3015
|
+
and a value that starts with `--` are `E_BAD_ARGS`).
|
|
3016
|
+
With one or more keys, a group is probed and returned when:
|
|
3017
|
+
|
|
3018
|
+
1. its registration's `workspaceKey` is one of the keys;
|
|
3019
|
+
2. its registration's `workspaceKey` is not known (absent; `oats server
|
|
3020
|
+
check <id>` learns it);
|
|
3021
|
+
3. it has no registration for its target (`registrationPresent: false`:
|
|
3022
|
+
saved routes only, the registration removed or changed to another
|
|
3023
|
+
target). Its workspace is unknown, so it is always probed: it holds the
|
|
3024
|
+
rows the Desktop offers Forget on (#1131), which no window's filter may
|
|
3025
|
+
hide.
|
|
3026
|
+
|
|
3027
|
+
A group whose registration names another workspace is neither probed nor
|
|
3028
|
+
returned, its saved routes under that registration and target with it. A
|
|
3029
|
+
group is judged by its registration when it has one, so a saved route whose
|
|
3030
|
+
target differs from the registration's is a group of its own, kind 3. A key
|
|
3031
|
+
is compared with the registration's `workspaceKey` by exact string equality:
|
|
3032
|
+
it is the canonical key a host's `status --json` reports as `workspace.key`,
|
|
3033
|
+
never parsed as a repository reference. An empty or missing value, or one
|
|
3034
|
+
with whitespace or a control character, is `E_BAD_ARGS`. `--server` and
|
|
3035
|
+
`--workspace-key` both narrow. Without the flag the answer is exactly as
|
|
3036
|
+
above. With it the answer's shape is unchanged (no filter is echoed in it);
|
|
3037
|
+
only which groups appear changes, and a key that matches nothing leaves the
|
|
3038
|
+
kinds 2 and 3. In text mode, keys that leave no group print `no remote groups
|
|
3039
|
+
for the given workspace keys`.
|
|
3040
|
+
|
|
3041
|
+
The Desktop reads one roster for all its windows: it passes the workspace key
|
|
3042
|
+
of every open window's view in one read, member-derived keys included (a
|
|
3043
|
+
registration records the key its host reports, whatever its `keyFrom`). A key
|
|
3044
|
+
that is `null`, or one the kernel would refuse, is no registration's: a view
|
|
3045
|
+
without a usable key adds none. The read is unfiltered when the Desktop has no
|
|
3046
|
+
window set or no roster answer yet, when a window shows the switcher, when a
|
|
3047
|
+
view without a usable key holds another machine's deployment (whose
|
|
3048
|
+
registration cannot then be named), and when no key is usable.
|
|
3049
|
+
|
|
3050
|
+
<a id="forget-a-saved-route-oats-server-forget---json"></a>
|
|
3051
|
+
### Forget a saved route (`oats server forget --json`)
|
|
3052
|
+
|
|
3053
|
+
```text
|
|
3054
|
+
oats server forget <server> --instance <instance> --json
|
|
3055
|
+
```
|
|
3056
|
+
|
|
3057
|
+
It removes this computer's saved route to `<instance>` through `<server>`,
|
|
3058
|
+
the file under `$OATS_HOME_DIR/remote/<server>/`, and nothing else. It runs
|
|
3059
|
+
nothing on the host and does not contact it: the home there, if it still
|
|
3060
|
+
exists, is untouched ([servers.md](servers.md#what-this-machine-keeps)). It
|
|
3061
|
+
shipped in 0.22.3 with the roster's `missingRemotely`, so every kernel that
|
|
3062
|
+
reports a gone row answers it; there is no feature name.
|
|
3063
|
+
|
|
3064
|
+
An envelope; `result` is:
|
|
3065
|
+
|
|
3066
|
+
```json
|
|
3067
|
+
{"server":"build","instance":"dev-a","home":"/srv/team/agents/dev/instances/dev-a",
|
|
3068
|
+
"target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},"forgotten":true}
|
|
3069
|
+
```
|
|
3070
|
+
|
|
3071
|
+
- **`server`** and **`instance`**: the arguments, echoed.
|
|
3072
|
+
- **`home`**: the instance's home on the host, as the route recorded it.
|
|
3073
|
+
- **`target`**: the route's target (`{sshHost, workspace, oatsPath, …}`) as
|
|
3074
|
+
the route file recorded it, less the `herdrPath` a route written before
|
|
3075
|
+
0.31.0 may hold.
|
|
3076
|
+
- **`forgotten`**: always `true` on success.
|
|
3077
|
+
|
|
3078
|
+
A refusal is `ok: false` with `error: {code, message}` only (no `details`,
|
|
3079
|
+
no `fix`), exit 1, and removes nothing:
|
|
3080
|
+
|
|
3081
|
+
- `E_USAGE`: no server id, or no `--instance` value.
|
|
3082
|
+
- `E_SERVER_INVALID`: the server id is not `^[a-z0-9][a-z0-9-]{0,63}$`.
|
|
3083
|
+
- `E_BAD_ARGS`: the instance name is not `^[a-z0-9][a-z0-9-]*$`.
|
|
3084
|
+
- `E_SNAPSHOT_UNKNOWN`: this computer has no saved route for that instance
|
|
3085
|
+
through that server id (a second forget of the same row answers this).
|
|
3086
|
+
- `E_SNAPSHOT_UNREADABLE`: the route file is not valid JSON; the file is
|
|
3087
|
+
kept.
|
|
3088
|
+
|
|
3089
|
+
The Desktop runs it only for a remote roster row with `missingRemotely:
|
|
3090
|
+
true`, after a confirmation, with exactly the row's `server` and `instance`
|
|
3091
|
+
as the arguments. It never shows `home` or `target`, and it reads the remote
|
|
3092
|
+
roster again after every outcome, a refusal and an unknown one included,
|
|
3093
|
+
instead of editing the row.
|
|
3094
|
+
|
|
2899
3095
|
<a id="servers-per-workspace"></a>
|
|
2900
3096
|
### Servers per workspace (feature `servers-per-workspace`)
|
|
2901
3097
|
|
|
@@ -3424,8 +3620,9 @@ that is not an object; OATS 0.52.0) decides only for itself.
|
|
|
3424
3620
|
repair its lineage. Its session may go on running under a parent that was
|
|
3425
3621
|
retired; `oats status` is where it shows.
|
|
3426
3622
|
- A spawn that names such a home as its parent or anchor is refused
|
|
3427
|
-
(`
|
|
3428
|
-
parent's child-spawn policy
|
|
3623
|
+
(`E_UNIDENTIFIED_INSTANCE_HOME`, the same sentence with `nothing was
|
|
3624
|
+
spawned`; `E_SPAWN_FAILED` before 0.56.0): the parent's child-spawn policy
|
|
3625
|
+
and the lineage are in that record.
|
|
3429
3626
|
- `oats session inspect`, `input` and `attach` on that home answer
|
|
3430
3627
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, and `oats instance events` still reads its
|
|
3431
3628
|
logs.
|
|
@@ -4100,13 +4297,76 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4100
4297
|
one Git names for it, <repository>, and does not write it into the
|
|
4101
4298
|
record`. No key of the plan is new.
|
|
4102
4299
|
|
|
4103
|
-
|
|
4104
|
-
|
|
4105
|
-
|
|
4106
|
-
|
|
4107
|
-
|
|
4108
|
-
|
|
4109
|
-
|
|
4300
|
+
<a id="retire-revision-work"></a>**A retire plan's `planRevision` binds
|
|
4301
|
+
everything the plan shows, except the facts that move by themselves**
|
|
4302
|
+
(0.56.0, #1065), which are these:
|
|
4303
|
+
- `at`, the instant of the read;
|
|
4304
|
+
- the counts against the branch's upstream and against the default branch
|
|
4305
|
+
(`facts.work.upstream.ahead` and `.behind`, `facts.work.base.ahead` and
|
|
4306
|
+
`.behind`), and the default branch's name (`facts.work.base.ref`): a
|
|
4307
|
+
fetch by anyone who shares the clone moves the remote's refs, and
|
|
4308
|
+
creates a missing `origin/HEAD`, where that name is read;
|
|
4309
|
+
- a child's session (`facts.children[].session`): a child's process ends
|
|
4310
|
+
when it ends, and a child that will not stop refuses the retire by
|
|
4311
|
+
itself (`E_CHILDREN_RUNNING`).
|
|
4312
|
+
|
|
4313
|
+
Everything else a plan shows is in its revision, in every home:
|
|
4314
|
+
- what the plan reports of the record: its work mode (`facts.workMode`),
|
|
4315
|
+
its repository (`facts.repo`), its branch (`facts.recordedBranch`) and
|
|
4316
|
+
whether it records a launch;
|
|
4317
|
+
- what `work/` is by this reading, with the repository Git names for
|
|
4318
|
+
`work/` wherever it is a registered work tree;
|
|
4319
|
+
- what Git says of `work/`: the commit, the branch and whether `HEAD` is
|
|
4320
|
+
detached, whether that branch is not the one the record names
|
|
4321
|
+
(`facts.work.drift`, as the plan shows it: it comes from a second read
|
|
4322
|
+
of the record, so it is not derived from `facts.recordedBranch`),
|
|
4323
|
+
the counts of changed and untracked files, the branch's upstream by its
|
|
4324
|
+
name (`facts.work.upstream.ref`) and the remote's host and path
|
|
4325
|
+
(`facts.work.remote`); and where Git gives no answer, the reason
|
|
4326
|
+
(`facts.work.reason`);
|
|
4327
|
+
- the session as the plan shows it (`facts.session`, whole: its state,
|
|
4328
|
+
and the `reason` or the `note` of one that is not established), which
|
|
4329
|
+
the record's launch and endpoint decide where the session's receipt
|
|
4330
|
+
does not;
|
|
4331
|
+
- the home's extra trees (`facts.extraWorktrees`, whole);
|
|
4332
|
+
- where a recovery would be written and the declared roots it leaves
|
|
4333
|
+
out, as the spawn's receipt gives them: the roots with their owners,
|
|
4334
|
+
not the note made from them, which is shortened past its budget and
|
|
4335
|
+
then reads alike for two lists of one length. A changed recovery
|
|
4336
|
+
exclusion changes the revision (it did not before 0.56.0);
|
|
4337
|
+
- of other homes: the children as the plan names them (`instance`,
|
|
4338
|
+
`agent`, `home`; a child's agent is the name its soul's file gives),
|
|
4339
|
+
the edges that could not be followed (`facts.ambiguous`, whole) and the
|
|
4340
|
+
children attached to this home's `work/`.
|
|
4341
|
+
|
|
4342
|
+
A key that is derived is bound through what it is derived from:
|
|
4343
|
+
`facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
|
|
4344
|
+
every note and every line of the plan's text.
|
|
4345
|
+
`lifecycleApi`, `action`, `facts.pullRequest` and the defaults
|
|
4346
|
+
`deleteBranch`, `stopChildren` and `retainChildren` have one value in
|
|
4347
|
+
every plan of a kernel.
|
|
4348
|
+
|
|
4349
|
+
So two plans of one home that differ in anything else they show never
|
|
4350
|
+
share a revision, and a guarded apply after one of those things moved (a
|
|
4351
|
+
record's work mode, repository or branch that was rewritten, a receipt
|
|
4352
|
+
that is gone, an own tree that became a directory of the home, a
|
|
4353
|
+
directory of the home that became a work tree of another repository, a
|
|
4354
|
+
file where nothing was at `work/`, a receipt that declares another root)
|
|
4355
|
+
is refused with `E_PLAN_STALE` and the fresh plan, before anything runs.
|
|
4356
|
+
Two reads of a home that nobody touched give one revision.
|
|
4357
|
+
|
|
4358
|
+
Before 0.56.0 the revision held of the record its launch alone, of the
|
|
4359
|
+
session its state alone, and the reading only where its answer was not
|
|
4360
|
+
the one the record's work mode alone gives, or where the retire took the
|
|
4361
|
+
repository from Git because the record named none (0.53.0): a record
|
|
4362
|
+
rewritten between a plan and its apply could leave the plan's revision
|
|
4363
|
+
as it was.
|
|
4364
|
+
**Every retire plan read under an older kernel is stale under this one,
|
|
4365
|
+
once:** its apply is refused with `E_PLAN_STALE` and the fresh plan, and
|
|
4366
|
+
the person confirms again. A repeated apply with the idempotency key of a
|
|
4367
|
+
retire that did run is answered from its stored receipt as before,
|
|
4368
|
+
whatever revision it carries: the receipt is looked for before any plan
|
|
4369
|
+
is read.
|
|
4110
4370
|
- A link at `work/` is never the instance's own tree: the retire removes
|
|
4111
4371
|
the link with the home and does not touch what it leads to, whatever the
|
|
4112
4372
|
record says (0.53.0, #973). The record is a file the instance can write;
|
|
@@ -4142,13 +4402,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4142
4402
|
stored in the link; nothing acts on it. When the link does not resolve,
|
|
4143
4403
|
the string ends `and it led nowhere that could be read`. The receipt holds
|
|
4144
4404
|
the path as the system gave it. The retire's text (without `--json`)
|
|
4145
|
-
prints every warning of the receipt on one line
|
|
4146
|
-
|
|
4147
|
-
|
|
4148
|
-
kernel never prints in text it did not write), as `\u{<hex>}`, so that a
|
|
4149
|
-
name cannot clear the screen or write a line of its own. The JSON is not
|
|
4150
|
-
changed by that: its strings are what they were. No key of the plan or of
|
|
4151
|
-
the receipt is new.
|
|
4405
|
+
prints every warning of the receipt on one line, spelled as
|
|
4406
|
+
[Text output](#text-output) says. The JSON is not changed by that: its
|
|
4407
|
+
strings are what they were. No key of the plan or of the receipt is new.
|
|
4152
4408
|
- A link at `work/` that is no longer a link when the retire inspects the
|
|
4153
4409
|
home again (a retire hook, or anything else, put a directory or a file in
|
|
4154
4410
|
its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
|
|
@@ -4211,7 +4467,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4211
4467
|
case. Read an unknown `state` as not idle.
|
|
4212
4468
|
- `notes` says what a retire would copy to recovery (0.42), in up to two
|
|
4213
4469
|
strings read from the home's retirement baseline and the work mode, without
|
|
4214
|
-
hashing
|
|
4470
|
+
hashing a file of the home:
|
|
4215
4471
|
|
|
4216
4472
|
```text
|
|
4217
4473
|
recovery: the home is copied to /w/agents/dev/instances/.oats-retirement/recovery before the home is removed, when it changed since spawn; not copied: .aw, .aweb-identity, .aweb-identity-*, .oats-aweb (oats.aweb)
|
|
@@ -4233,7 +4489,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
4233
4489
|
The second is the line above in worktree mode, `recovery: work/ is copied
|
|
4234
4490
|
there when it is not empty` in directory mode, and absent in checkout,
|
|
4235
4491
|
attached and workspace modes. They are strings in `notes`: no other key
|
|
4236
|
-
changes
|
|
4492
|
+
changes. From 0.56.0 the declared roots are part of `planRevision`, as
|
|
4493
|
+
the baseline gives them and not as the note says them (#1065,
|
|
4494
|
+
[the plan's revision](#retire-revision-work)); before it they were not.
|
|
4237
4495
|
- `facts.extraWorktrees` (0.42.1) lists the instance's
|
|
4238
4496
|
[extra trees](souls-and-instances.md#extra-trees-at-retire): linked
|
|
4239
4497
|
worktrees at `<home>/.work-*` that Git confirms. It is an array, empty when
|
|
@@ -4898,7 +5156,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
4898
5156
|
`restart`),
|
|
4899
5157
|
`E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
|
|
4900
5158
|
`E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
|
|
4901
|
-
started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
|
|
5159
|
+
started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
|
|
5160
|
+
`E_HARNESS_RESOURCE_MISSING` (a harness package an active capability
|
|
5161
|
+
requires is not installed, disabled, or cannot be verified: nothing was
|
|
5162
|
+
started; `E_HARNESS_PACKAGE` before 0.56.0), `E_SESSION_FAILED`
|
|
4902
5163
|
(any error that is not the kernel's; with
|
|
4903
5164
|
[`details.cause`](#kernel-codes) when it has a code of its own or is a
|
|
4904
5165
|
defect, and without it when it is a refusal without a code).
|
|
@@ -4981,7 +5242,11 @@ accept `--server <id>`.
|
|
|
4981
5242
|
launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
|
|
4982
5243
|
declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
|
|
4983
5244
|
true} | {name, reference: true}], command (redacted), prompt, hooks,
|
|
4984
|
-
preflight: [{check, ok, detail}], ok}`.
|
|
5245
|
+
preflight: [{check, ok, detail, code?}], ok}`. A failed check carries the
|
|
5246
|
+
code a start would refuse with; the `harness-packages` check's is the
|
|
5247
|
+
gate's own, `E_HARNESS_RESOURCE_MISSING` (`E_HARNESS_PACKAGE` before
|
|
5248
|
+
0.56.0). A fault of the gate, which is no verdict on a package, is not a
|
|
5249
|
+
row: the preview fails as a whole.
|
|
4985
5250
|
|
|
4986
5251
|
`launchConfigDefault` (0.32) is `true` when `launchConfig` is this host's
|
|
4987
5252
|
default for the harness rather than a chosen configuration; the spawn preview
|
|
@@ -5454,12 +5719,20 @@ It uses the existing success/error JSON envelope. Result:
|
|
|
5454
5719
|
|
|
5455
5720
|
There is one entry per target file: the ambient file of each selected harness,
|
|
5456
5721
|
then one per launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` or
|
|
5457
|
-
`CODEX_HOME`,
|
|
5458
|
-
|
|
5459
|
-
|
|
5722
|
+
`CODEX_HOME`, or sets `HOME` when its launch has no such variable at all
|
|
5723
|
+
(its default file under that `HOME`), deduplicated by canonical directory. `ambient` says whether the
|
|
5724
|
+
file is the one a launch with no launch configuration reads (by the
|
|
5725
|
+
environment its tmux pane will have, or the operator's own when no OATS tmux
|
|
5726
|
+
server runs, which `warnings` then says:
|
|
5727
|
+
[harness-trust.md](harness-trust.md)); `launchConfigs` names the launch
|
|
5728
|
+
configurations that select it (sorted). A launch configuration whose directory cannot
|
|
5460
5729
|
be resolved (an unset reference, a relative path) or does not exist is a
|
|
5461
5730
|
`refused` entry with a `problem` string naming it; `file` is null when the path
|
|
5462
|
-
is unresolved. The directory is never created.
|
|
5731
|
+
is unresolved. The directory is never created. A file the writer refuses (its
|
|
5732
|
+
type, links, owner, mode bits, `ls` metadata markers, size, encoding or format)
|
|
5733
|
+
is a `refused` entry whose `problem` is the file and the check that refused it,
|
|
5734
|
+
in fixed wording that never includes the file's content; such an entry's
|
|
5735
|
+
`current` and digests do not describe the file's trust.
|
|
5463
5736
|
|
|
5464
5737
|
Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted|skipped`. `skipped` (with `reason`) is a harness whose ambient configuration directory does not exist under `--harness all`; it is never created.
|
|
5465
5738
|
`current` contains only the known trust scalar, or null when missing. Codex's key
|
|
@@ -5472,7 +5745,16 @@ unverifiable observations). The intent retains the candidate digest. Apply's aud
|
|
|
5472
5745
|
in warnings, without native configuration contents.
|
|
5473
5746
|
|
|
5474
5747
|
Preflight failures, including any entry `problem`, use `E_CONFIG_BROKEN` with the
|
|
5475
|
-
result in details; the message names each problem.
|
|
5748
|
+
result in details; the message names each problem. One case has its own code:
|
|
5749
|
+
when the only refused entries are ambient ones whose file could not be
|
|
5750
|
+
established, because a server runs and the environment of its panes cannot be
|
|
5751
|
+
read, or because tmux could not say whether the server runs (its
|
|
5752
|
+
`list-sessions` refused or cut off; with no tmux on the command's `PATH`
|
|
5753
|
+
no read is made, and the operator's own file is the target, said in
|
|
5754
|
+
`warnings`), the code is `E_RUNTIME_ENDPOINT_UNKNOWN` (`Harness trust targets cannot be
|
|
5755
|
+
established; nothing was written: …`), with the same details: the entry is
|
|
5756
|
+
`refused`, `file` null, with its `problem`. With a refused launch
|
|
5757
|
+
configuration's entry beside it, `E_CONFIG_BROKEN` wins. Apply failures
|
|
5476
5758
|
use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
|
|
5477
5759
|
reason is the closed set `locked|changed|audit|write|verify`; the message names the
|
|
5478
5760
|
failed files. Partial writes are
|