@awebai/oats 0.51.0 → 0.53.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/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
package/docs/implementation.md
CHANGED
|
@@ -10,7 +10,18 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
10
10
|
- **`@awebai/oats`**: the runtime-neutral kernel (`lib/`), the `oats` CLI
|
|
11
11
|
(`bin/oats.mjs`), the kernel and work-mode instruction sources
|
|
12
12
|
(`injects/`), the bootstrap skills, the docs and the official package
|
|
13
|
-
catalog (`package-catalog.json`).
|
|
13
|
+
catalog (`package-catalog.json`). The same tarball carries two
|
|
14
|
+
dependency-free packages of this repository, the turn record
|
|
15
|
+
(`packages/record/`, behind `oats capture`, `recall` and `setup`) and the
|
|
16
|
+
terminal client (`packages/tui/`, behind `oats tui`, a preview:
|
|
17
|
+
[tui.md](tui.md)), and the directory of readers the terminal client shares
|
|
18
|
+
with the Desktop (`packages/client/`, below), which has no dependency
|
|
19
|
+
either. None of their tests is packed. The package's
|
|
20
|
+
manifest declares three runtime dependencies: `yaml` (the kernel reads and
|
|
21
|
+
writes the configuration files with it), `croner` (schedule expressions) and
|
|
22
|
+
`@awebai/pi` (pi's aweb messaging extension). The terminal client adds none
|
|
23
|
+
and may never add one: with a dependency it could no longer ship in this
|
|
24
|
+
tarball.
|
|
14
25
|
- **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
|
|
15
26
|
instance's own resources. It registers no agent tools.
|
|
16
27
|
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
@@ -25,6 +36,35 @@ dependency-free localhost server; it is released with the kernel but not
|
|
|
25
36
|
published to npm. Its developer docs are in
|
|
26
37
|
[`packages/desktop/README.md`](../packages/desktop/README.md).
|
|
27
38
|
|
|
39
|
+
`packages/client/` holds the readers of the kernel's JSON that the kernel's
|
|
40
|
+
clients share: the CLI adapters and contract decoders the Desktop imports by
|
|
41
|
+
relative path and ships beside its `app.asar`, and what a client decides from
|
|
42
|
+
the kernel's rows alone (the roster as a tree, which acts a row offers). It is
|
|
43
|
+
a flat directory of `.mjs` modules with no manifest of its own, not a package.
|
|
44
|
+
`test/client-boundary.test.mjs` holds who may import what: the directory
|
|
45
|
+
imports only itself and `node:` builtins, `lib/` and `bin/` import nothing
|
|
46
|
+
from it, and the test lists the stable surface a second client may import.
|
|
47
|
+
|
|
48
|
+
`packages/tui/` is that second client, the terminal one (`oats tui`), in
|
|
49
|
+
layers that each do one thing. `lib/term/` is the terminal: the key parser,
|
|
50
|
+
cell widths, safe text, the screen and the guard that restores the terminal;
|
|
51
|
+
only the screen and the guard write an escape byte. `lib/read.mjs` is every
|
|
52
|
+
effect of reading: for each deployment opened in a run it runs the kernel
|
|
53
|
+
of the same install and the shared liveness collector as children, through
|
|
54
|
+
the shared observer and refresh loop; it runs that kernel's read of the
|
|
55
|
+
other machines (`oats server roster --json`), one at a time and awaited by
|
|
56
|
+
no cycle; it ends every child; and it makes the two looks at the file
|
|
57
|
+
system the workspace switcher needs (the entries of `~/Agents`, and whether
|
|
58
|
+
a picked folder is a deployment). `lib/store.mjs` is the state and a pure
|
|
59
|
+
`reduce(state, event)`; `lib/model.mjs` turns the state into the rows to
|
|
60
|
+
draw by calling the shared readers through `lib/client.mjs`, the one module
|
|
61
|
+
that imports `packages/client/`; `lib/views/` are pure functions from that
|
|
62
|
+
model and a size to rows of spans; `lib/main.mjs` wires them. It decodes no
|
|
63
|
+
kernel answer of its own: grouping, order, states and what a failed read
|
|
64
|
+
becomes are the shared readers', so both clients show the same roster.
|
|
65
|
+
[`packages/tui/README.md`](../packages/tui/README.md) has the module table
|
|
66
|
+
and the rules its tests pin.
|
|
67
|
+
|
|
28
68
|
## Repository layout
|
|
29
69
|
|
|
30
70
|
| path | contents |
|
|
@@ -38,8 +78,8 @@ published to npm. Its developer docs are in
|
|
|
38
78
|
| `oats-package/` | the `oats.framework` package |
|
|
39
79
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
40
80
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
41
|
-
| `packages/` | the pi adapter, the Desktop, the turn-record package and experiments |
|
|
42
|
-
| `scripts/` | the test runner, validators, packaging checks and the release
|
|
81
|
+
| `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
|
|
82
|
+
| `scripts/` | the test runner (`run-tests.mjs`) and its reporter of unasserted warnings, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
|
|
43
83
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
44
84
|
|
|
45
85
|
## Kernel modules
|
|
@@ -53,11 +93,16 @@ published to npm. Its developer docs are in
|
|
|
53
93
|
| `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
|
|
54
94
|
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit |
|
|
55
95
|
| `materialize.mjs` | copying modules into a home and composing it |
|
|
56
|
-
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata |
|
|
96
|
+
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
57
97
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
58
98
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
59
99
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
100
|
+
| `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
|
|
101
|
+
| `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. 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 |
|
|
102
|
+
| `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 |
|
|
103
|
+
| `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
|
|
60
104
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
105
|
+
| `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 |
|
|
61
106
|
| `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 |
|
|
62
107
|
| `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 |
|
|
63
108
|
| `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 |
|
|
@@ -65,21 +110,25 @@ published to npm. Its developer docs are in
|
|
|
65
110
|
| `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 |
|
|
66
111
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
67
112
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
113
|
+
| `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 |
|
|
114
|
+
| `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` and `oats instance stop --apply` (`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 |
|
|
115
|
+
| `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 |
|
|
116
|
+
| `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`), never from the caller's `PATH`. `ps` runs on the same directories: `worktree-hooks.mjs`'s `PS_ENV` takes its `PATH` from them |
|
|
117
|
+
| `tmux-server-scope.mjs` | whether the OATS tmux server starts in a systemd scope of its own: the creator's cgroup judged (Linux, inside a `.service`, unified hierarchy), the scope's name and the warning when it cannot |
|
|
70
118
|
| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
|
|
71
119
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
72
120
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
73
121
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
74
122
|
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
75
123
|
| `servers.mjs` | routing commands to a registered server |
|
|
76
|
-
| `launch-prompt-evidence.mjs` | private bounded storage of exact
|
|
77
|
-
| `launch-prompt-completion.mjs` |
|
|
78
|
-
| `launch-prompt-
|
|
79
|
-
| `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts
|
|
124
|
+
| `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
125
|
+
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
|
126
|
+
| `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
|
|
127
|
+
| `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts, one Enter only on equality with a tolerance entry |
|
|
80
128
|
| `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
|
|
81
129
|
| `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
|
|
82
130
|
| `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
|
|
131
|
+
| `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings and the plan `oats update` runs ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
|
|
83
132
|
|
|
84
133
|
The schedule registry stores explicit concurrency caps, leaving the schedule
|
|
85
134
|
cap absent for its effective default of five. `readRegistry()` is a pure,
|
|
@@ -256,6 +305,37 @@ caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
|
|
|
256
305
|
partial cache it meets is deleted and fetched again whole, and the same
|
|
257
306
|
notice says why.
|
|
258
307
|
|
|
308
|
+
The fetch of a commit negotiates: git tells the server the commits the cache
|
|
309
|
+
holds (its pins), and the pack holds only what they lack, a few kilobytes for
|
|
310
|
+
a new head beside the last one. The server may then send an object as a delta
|
|
311
|
+
against one it takes the cache to hold, and the cache does not hold the blobs
|
|
312
|
+
its filter left out: git cannot complete that pack, may not fetch the missing
|
|
313
|
+
base on its own, and the fetch fails with words the kernel cannot classify.
|
|
314
|
+
`git fetch` cannot ask for a pack that is complete by itself while
|
|
315
|
+
negotiating, so `fetchCommit` makes a fetch that failed as `unknown` once
|
|
316
|
+
more without negotiation (`fetch.negotiationAlgorithm=noop`), which brings
|
|
317
|
+
the commit whole and is complete whatever the cache holds
|
|
318
|
+
(awebai/oats#1059). One second attempt, never a third, and never on git's
|
|
319
|
+
wording. git does not remove the pack file of a fetch that dies
|
|
320
|
+
(`objects/pack/tmp_pack_*`), and the cache runs no gc, so every fetch, under
|
|
321
|
+
the write lock, first removes the temporary files of the object store that
|
|
322
|
+
are older than the longest fetch (`temporaryStaleMs` in `lib/remote.mjs`
|
|
323
|
+
says what that is): `tmp_*` in `objects/pack`, in `objects` and
|
|
324
|
+
in its two-character directories, where git's own `prune` looks, and nowhere
|
|
325
|
+
behind a symbolic link. Age is the only rule, the one of a stale git lock
|
|
326
|
+
below and of `git prune`. A failed fetch's own pack is not removed at once,
|
|
327
|
+
because a file that appeared during a fetch cannot be told from one another
|
|
328
|
+
git is writing: an older kernel's fetch takes no write lock, and git names
|
|
329
|
+
the file itself.
|
|
330
|
+
|
|
331
|
+
A failed git call is classified from what it shows (`classifyRemoteFailure`):
|
|
332
|
+
our own timer's kill is `timeout`, another signal `killed`, a failed write of
|
|
333
|
+
the cache `cache`, and otherwise git's text decides, read without the object
|
|
334
|
+
ids it names. A text that shows nothing the kernel recognises is `unknown`,
|
|
335
|
+
never `network`, and the message of an `unknown` failure carries git's own
|
|
336
|
+
line through one scrub (`scrubGitLine`): one line, bounded, with no control
|
|
337
|
+
character and no URL's user information.
|
|
338
|
+
|
|
259
339
|
Every write to a cache repo (its `git init`, config, fetches and pins) holds
|
|
260
340
|
the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
|
|
261
341
|
(`withCacheWriteLock`): an exclusive file holding `{pid, token, startedAt}`,
|
|
@@ -280,6 +360,12 @@ file and when it is safe to remove; so is any other local write failure
|
|
|
280
360
|
(a `FETCH_HEAD` git cannot open, a read-only or full disk), with git's own
|
|
281
361
|
words.
|
|
282
362
|
|
|
363
|
+
Nothing but the kernel runs git in a cache entry. What an entry is
|
|
364
|
+
(partial, with no url, pinned by its own refs, no blob fetched lazily)
|
|
365
|
+
holds only through the kernel's own commands, and a git command named for a
|
|
366
|
+
read still writes there: a `git fetch --dry-run` writes the objects it
|
|
367
|
+
receives, and takes no write lock.
|
|
368
|
+
|
|
283
369
|
Across commands, `memoAtCommit` keeps parsed reads under
|
|
284
370
|
`<cache>/.parsed/<kernel fingerprint>/`, keyed by (repo key, full commit,
|
|
285
371
|
item). The items: `workspace` (the workspace file), `membership` (a member's
|
|
@@ -302,10 +388,11 @@ scaling by call count.
|
|
|
302
388
|
|
|
303
389
|
| command | what it checks |
|
|
304
390
|
|---|---|
|
|
305
|
-
| `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs` |
|
|
391
|
+
| `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output |
|
|
392
|
+
| `npm run test:session` | the suites that have followed a variable of the session that runs them, with every such variable set to a value that cannot work (`scripts/test-session-inheritance.mjs`) |
|
|
306
393
|
| `npm run check` | syntax of every shipped file |
|
|
307
394
|
| `npm run check:pi` | the pi adapter's TypeScript |
|
|
308
|
-
| `npm run validate` | the JSON schemas, the example manifests and configs, every local link and anchor in the public docs, the repository's own `oats-workspace.yaml` and `package-catalog.json` read by the kernel's readers, and no unresolved merge-conflict marker in a tracked text file (`scripts/check-workspace-files.mjs`) |
|
|
395
|
+
| `npm run validate` | the JSON schemas, the example manifests and configs, every local link and anchor in the public docs (a release-notes entry under `docs/release-notes/next/` has its links read from `docs/release-notes/`, where its text is moved), the repository's own `oats-workspace.yaml` and `package-catalog.json` read by the kernel's readers, and no unresolved merge-conflict marker in a tracked text file (`scripts/check-workspace-files.mjs`) |
|
|
309
396
|
| `npm run pack:check` | an `npm pack` dry run of both packages: nothing missing, nothing leaked |
|
|
310
397
|
| `npm run smoke:tarball` | installs the packed tarballs outside the checkout and exercises them |
|
|
311
398
|
|
|
@@ -316,6 +403,20 @@ dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
|
|
|
316
403
|
and is the gate. Tests use local bare repositories and fakes; none contacts
|
|
317
404
|
GitHub, aweb, Jira or Linear.
|
|
318
405
|
|
|
406
|
+
**Test output is pristine.** A warning that a test expects is captured and
|
|
407
|
+
asserted by the test, or by its fixture, and never left in the output: a line
|
|
408
|
+
nobody asserted is then one nobody expected. The root run holds the rule
|
|
409
|
+
(awebai/oats#910). Beside the reporter a person reads, which stays the one
|
|
410
|
+
`node --test` would pick, `scripts/run-tests.mjs` gives the run a second
|
|
411
|
+
reporter (`scripts/test-warnings-reporter.mjs`) that reads what each test file
|
|
412
|
+
wrote to its stderr and stdout and records every line that holds
|
|
413
|
+
`oats: warning:`. When there is one the run fails, even if every test passed,
|
|
414
|
+
and names each file, its count and the lines. A file's output is what its
|
|
415
|
+
worker wrote and what a child wrote that has the worker's stderr or stdout as
|
|
416
|
+
its own; a line a child wrote into a pipe the test reads is the test's, and
|
|
417
|
+
does not count. `test/unasserted-warnings.test.mjs` pins the rule with nested
|
|
418
|
+
runs.
|
|
419
|
+
|
|
319
420
|
Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
|
|
320
421
|
load with only Desktop dependencies installed. The release builds Desktop that
|
|
321
422
|
way: its `desktop-build` job installs and tests inside `packages/desktop` and
|
|
@@ -337,6 +438,20 @@ location and error, then gives bounded stdout and stderr tails, and its size
|
|
|
337
438
|
is capped. It is built only when the run failed, and it never throws: if
|
|
338
439
|
reading the failures fails, the message says so and still carries the tails.
|
|
339
440
|
|
|
441
|
+
A test never races the wall clock for a window between two steps of the
|
|
442
|
+
kernel. Where an answer needs a second writer at an exact moment (an entry
|
|
443
|
+
that vanishes between a walk's listing and its read), the test runs the CLI
|
|
444
|
+
as a child held at one named `node:fs` call with
|
|
445
|
+
`test/helpers/fs-gate-preload.mjs` (`startGated`), does what the second writer
|
|
446
|
+
does, and releases it. A gate that pauses changes no argument and no result.
|
|
447
|
+
|
|
448
|
+
A test never fills a file system, and never waits for one to be full. Where an
|
|
449
|
+
answer needs a write to fail with a code no file shape gives on every host
|
|
450
|
+
(`ENOSPC`), the same helper makes one named `node:fs` call of that child fail
|
|
451
|
+
with it (a gate's `throws`; `runFaulted` runs a child whose gates all throw).
|
|
452
|
+
A shape that does fail by itself, a directory that is not writable, is made
|
|
453
|
+
with mode bits instead and skipped for root.
|
|
454
|
+
|
|
340
455
|
Cross-package tests that import both the kernel and Desktop belong under root
|
|
341
456
|
`test/`; install dependencies at the root and in `packages/desktop` before
|
|
342
457
|
running those tests. The schedule
|
|
@@ -388,6 +503,23 @@ and acts on every existing session through its recorded socket
|
|
|
388
503
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
389
504
|
- A server a test starts is killed by its socket, never by name and never
|
|
390
505
|
with a bare `tmux kill-server`.
|
|
506
|
+
- A test never reaches the host's `systemd-run` (#915). A Linux creator
|
|
507
|
+
inside a systemd service starts the server through the system's own
|
|
508
|
+
`systemd-run`, found by absolute path, not on `PATH`, so a fake-free `PATH`
|
|
509
|
+
does not stop it. The fixtures (`isolateSessionEnvironment`, `fixtureEnv`)
|
|
510
|
+
therefore set `OATS_TEST_CGROUP` to a scope, never a service, whatever runs
|
|
511
|
+
the suite. Two test-only seams select where the kernel judges itself and
|
|
512
|
+
which `systemd-run` it runs:
|
|
513
|
+
- `OATS_TEST_CGROUP`: the text of a `/proc/self/cgroup`, judged as Linux;
|
|
514
|
+
- `OATS_TEST_SYSTEM_TOOL_DIRS`: absolute directories separated by `:`, in
|
|
515
|
+
place of `/usr/bin:/bin`. Any other value means no system tool, never a
|
|
516
|
+
`PATH` lookup.
|
|
517
|
+
|
|
518
|
+
Both are reserved launch names (a launch configuration cannot set them),
|
|
519
|
+
are removed from a server's environment, and are stripped from the tick's
|
|
520
|
+
children like every reserved name. In process, `io.cgroup`, `io.platform`,
|
|
521
|
+
`io.invocationId` and `io.systemToolDirs` do the same for
|
|
522
|
+
`ensureOatsTmuxSession`.
|
|
391
523
|
- A test that needs a terminal (an attached tmux client, a key press) runs
|
|
392
524
|
the command in a pane of a second private server and types at that pane
|
|
393
525
|
with `send-keys`; the pane's shell records the exit status
|
|
@@ -395,6 +527,15 @@ and acts on every existing session through its recorded socket
|
|
|
395
527
|
bytes a terminal sends (`send-keys -l`). A pane program that must show the
|
|
396
528
|
keys it reads puts its terminal in raw mode first: in cooked mode a control
|
|
397
529
|
byte is a signal or an edit, not input.
|
|
530
|
+
- A test of a full-screen program (`oats tui`) uses a pane of a private
|
|
531
|
+
server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
|
|
532
|
+
at an interactive shell in the pane, keys go in with `send-keys`, the screen
|
|
533
|
+
is read with `capture-pane`, and what the program did to the terminal is
|
|
534
|
+
read from the pane's flags (`#{alternate_on}`, `#{cursor_flag}`,
|
|
535
|
+
`#{wrap_flag}`) and from `stty -g`. Every wait is on what the pane shows,
|
|
536
|
+
with a message that names it. A process is signalled by the pid it wrote
|
|
537
|
+
itself, never by name or command line: other agents' processes run on the
|
|
538
|
+
same machine.
|
|
398
539
|
|
|
399
540
|
Nor does a test depend on where or how the suite runs:
|
|
400
541
|
|
|
@@ -437,17 +578,97 @@ inherits it (awebai/oats#816):
|
|
|
437
578
|
filesystem's.
|
|
438
579
|
- **An explicit environment for every child.** `fixtureEnv(base)` is what
|
|
439
580
|
every child the fixture starts gets, and `fx.inEnv` applies the same rules
|
|
440
|
-
to the test process for an in-process kernel call.
|
|
441
|
-
|
|
442
|
-
`
|
|
581
|
+
to the test process for an in-process kernel call. `fx.inEnv` and
|
|
582
|
+
`inFixture` set the names on the real `process.env` and put back exactly
|
|
583
|
+
what was there (`forceEnvironment` in `test/helpers/v2-deployment.mjs`),
|
|
584
|
+
never by assigning another object to `process.env`: a child the kernel
|
|
585
|
+
starts with no `env` option gets a replaced object on some Node versions
|
|
586
|
+
only (not from v26.11.0). Calls of one fixture may nest or overlap; a
|
|
587
|
+
call of another fixture while one is in flight is refused. A test that
|
|
588
|
+
holds one environment for its whole length saves `{ ...process.env }`, sets
|
|
589
|
+
names on the real one and gives the saved one back with
|
|
590
|
+
`setProcessEnvironment` when it ends; everything else goes through
|
|
591
|
+
`fx.inEnv`. `test/fixture-real-environment.test.mjs` refuses an assignment
|
|
592
|
+
to `process.env` in any test script. The fixture's
|
|
593
|
+
environment sets `HOME` and the XDG base directories under the base, and
|
|
594
|
+
`GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null` and
|
|
595
|
+
`GIT_TERMINAL_PROMPT=0`, so no host git
|
|
443
596
|
configuration or credential helper is read. It removes every `*_PROXY`,
|
|
444
597
|
`CLAUDECODE` and git configuration passed through the environment. PATH
|
|
445
598
|
starts with `launchctl` and `systemctl` stubs that answer as a service
|
|
446
599
|
manager with nothing loaded. A test that needs another answer puts its own
|
|
447
600
|
stub ahead of them.
|
|
601
|
+
|
|
602
|
+
A fixture also never inherits the session that runs the suite. A developer
|
|
603
|
+
agent runs it from its own session, which selects a harness account
|
|
604
|
+
(`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`), has a display
|
|
605
|
+
and a tmux pane (`DISPLAY`, `TMUX`, `TMUX_PANE`) and is an instance (every
|
|
606
|
+
`OATS_*` and `AWEB_*`, and the legacy `PI_AGENT*`); CI's shards have none of
|
|
607
|
+
these, and the kernel reads several of them by design. One definition,
|
|
608
|
+
`SESSION_VARIABLES` in `test/helpers/host-fixture.mjs`, names them, and one
|
|
609
|
+
rule applies it: a helper leaves a session variable out while it still has
|
|
610
|
+
the value the worker started with (the helper module is evaluated before
|
|
611
|
+
any code of the test file that imports it, and keeps that environment), and
|
|
612
|
+
keeps it once a test has set it. So a test that needs one sets it itself, in
|
|
613
|
+
`process.env` before the fixture call or as `extra`, and the fixture's own
|
|
614
|
+
(`OATS_HOME_DIR`, `OATS_TEST_CGROUP`, `OATS_TEST_LOGIN_SHELL`) are kept the
|
|
615
|
+
same way. A test that sets a session variable to the very value the session
|
|
616
|
+
has is taken for the session's, and the variable is dropped; no test does
|
|
617
|
+
today. Every helper that builds an environment starts from
|
|
618
|
+
`inheritedEnv()` or removes with `dropInherited(env)`; none has a list of
|
|
619
|
+
names of its own, and a test that builds an environment itself starts from
|
|
620
|
+
`inheritedEnv()` too. A helper that starts a child for a caller who gives no
|
|
621
|
+
`env` (`startGated` and `runFaulted` in `test/helpers/fs-gate-preload.mjs`)
|
|
622
|
+
gives it `inheritedEnv()`. `npm run test:session`
|
|
623
|
+
(`scripts/test-session-inheritance.mjs`) is the check: it runs the suites
|
|
624
|
+
that have followed a session variable with every variable a session has set
|
|
625
|
+
to a value that cannot work, the names read from the helper's definition
|
|
626
|
+
(its legacy names, which no session has, are dropped and not set). Give it a
|
|
627
|
+
test file to run that file alone, and a flag for `node --test` with its
|
|
628
|
+
value in the same argument (`--test-name-pattern=…`): it refuses a bare flag
|
|
629
|
+
and any other argument, so it never starts `node --test` without naming the
|
|
630
|
+
files.
|
|
631
|
+
Pull-request CI runs it as the
|
|
632
|
+
`session-inheritance` job, which the gate requires
|
|
633
|
+
(`test/continuous-integration.test.mjs` pins both), and
|
|
634
|
+
`test/session-inheritance.test.mjs` pins the rule helper by helper.
|
|
448
635
|
- **The same rules under real tmux.** `isolateSessionEnvironment` applies the
|
|
449
|
-
same git, XDG and proxy rules
|
|
450
|
-
|
|
636
|
+
same git, XDG and proxy rules, and removes the session's variables, by the
|
|
637
|
+
same definition, from the worker itself: a tmux server holds the environment
|
|
638
|
+
of the client that started it, so a server the worker starts, through the
|
|
639
|
+
kernel or with its own tmux call, would otherwise carry the runner's display,
|
|
640
|
+
pane and instance to the kernel that reads it back. Its PATH stays its own
|
|
641
|
+
small set of tools, so no host service manager is reachable at all.
|
|
642
|
+
- **The fixture's expected warning.** A fixture's login environment cannot be
|
|
643
|
+
read, by construction: its `HOME` is not the user's and its login shell
|
|
644
|
+
(`OATS_TEST_LOGIN_SHELL`) does not exist. So where the kernel plans to start
|
|
645
|
+
the fixture's tmux server it says, in one line on the worker's stderr, that
|
|
646
|
+
it could not read the login environment and falls back. The fixture owns
|
|
647
|
+
that line (`expectLoginFallback` in `test/helpers/host-fixture.mjs`). It
|
|
648
|
+
takes the line out of the output only when the whole write is exactly the
|
|
649
|
+
sentence the kernel writes for the fixture's reason, and only while the
|
|
650
|
+
fixture's premise holds at that moment; any other line stays in the output
|
|
651
|
+
and fails the root run. Every capture also asserts something that can fail:
|
|
652
|
+
- `fx.inEnv`, for one kernel call: a server that appeared under the
|
|
653
|
+
fixture's `TMUX_TMPDIR` during the call with no line fails the call.
|
|
654
|
+
Nothing is asserted for a call in which the test replaced
|
|
655
|
+
`process.stderr.write` itself: the test holds the line then, and asserts
|
|
656
|
+
it. A child that plans the start writes the line on its own stderr: a
|
|
657
|
+
test starts such a child outside the call, and where the kernel call
|
|
658
|
+
itself launches through a child (a tick that runs `oats spawn`) the test
|
|
659
|
+
holds stderr around that call and asserts what the worker wrote.
|
|
660
|
+
- `isolateSessionEnvironment`, for as long as it is installed: a captured
|
|
661
|
+
line with nothing ever created under its `TMUX_TMPDIR` fails its restore.
|
|
662
|
+
- A test file whose fixture has no server to observe (a stand-in `tmux`)
|
|
663
|
+
wraps each kernel call that plans a start and asserts the count the
|
|
664
|
+
capture returns.
|
|
665
|
+
|
|
666
|
+
The kernel writes the line where it plans a start, in the process that
|
|
667
|
+
plans, so a socket shows neither who planned nor whether a start followed:
|
|
668
|
+
no capture asserts that the warning comes. That is pinned by
|
|
669
|
+
`test/login-environment.test.mjs`, `test/schedule-gone-server.test.mjs` and
|
|
670
|
+
`test/fixture-expected-warning.test.mjs`, which start a real server and read
|
|
671
|
+
the line.
|
|
451
672
|
- **No leftover processes.** The fixture's cleanup fails when a process still
|
|
452
673
|
works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
|
|
453
674
|
`processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
|
package/docs/integrations.md
CHANGED
|
@@ -40,8 +40,8 @@ arrives from.
|
|
|
40
40
|
```yaml
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
|
-
oats.okf: v5.0.
|
|
44
|
-
oats.aweb: v1.
|
|
43
|
+
oats.okf: v5.0.3
|
|
44
|
+
oats.aweb: v1.27.1
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
47
47
|
defaults:
|
|
@@ -79,7 +79,7 @@ operations in full.
|
|
|
79
79
|
| Slot | Provider | Needs on the host | Documentation |
|
|
80
80
|
| --- | --- | --- | --- |
|
|
81
81
|
| `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
|
|
82
|
-
| `messaging` | `oats.aweb` | the `aw` CLI at 1.36.
|
|
82
|
+
| `messaging` | `oats.aweb` | the `aw` CLI at 1.36.33 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
|
|
83
83
|
| `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
|
|
84
84
|
| `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
|
|
85
85
|
|
|
@@ -93,11 +93,12 @@ operations in full.
|
|
|
93
93
|
removes it at retire, contributes the aweb messaging skills, and wires the
|
|
94
94
|
channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
|
|
95
95
|
loads the channel plugin with `--dangerously-load-development-channels`,
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
96
|
+
and the kernel confirms the development-channel prompt once at launch.
|
|
97
|
+
The start reports that decision (`channel-dev-confirmation`); readiness
|
|
98
|
+
becomes quiet after the kernel records a completed confirmation. If Claude
|
|
99
|
+
ignored the flag, readiness reports `claude-channels-unavailable`.
|
|
100
|
+
`settings.oats.aweb.delivery: session` or
|
|
101
|
+
`settings.oats.aweb.claudeChannelMode: approved` stop the prompt. `oats aweb roster` lists the team:
|
|
101
102
|
its membership certificates and workspaces, one entry per alias with its
|
|
102
103
|
sources, status and kind (global identities first), and says when either
|
|
103
104
|
source is incomplete. After `oats server connect`, `oats aweb connect
|
|
@@ -139,7 +140,10 @@ Building an integration is implementing a contract. The framework's
|
|
|
139
140
|
its `binding.check` command
|
|
140
141
|
([capabilities.md](capabilities.md#readiness-check-bindingcheck)).
|
|
141
142
|
- Package commands and hooks reach the kernel only through `OATS_CLI_BIN` and
|
|
142
|
-
the JSON envelope, never by importing kernel files.
|
|
143
|
+
the JSON envelope, never by importing kernel files. A `node` path they
|
|
144
|
+
write into anything that outlives them (settings, a unit, a script) is
|
|
145
|
+
`OATS_NODE_BIN`, the node to write down, never `process.execPath`
|
|
146
|
+
([capabilities.md](capabilities.md#the-node-a-hook-writes-down)). Never name target souls
|
|
143
147
|
in the manifest: which souls get a capability is configuration.
|
|
144
148
|
|
|
145
149
|
**Knowledge.** The capability owns its complete runtime and format, including
|
|
@@ -49,6 +49,7 @@ whether an instruction contains “promotion bar.”
|
|
|
49
49
|
| Correction to a reusable runbook | Maintain the existing procedure through its approval path |
|
|
50
50
|
| Unverified single observation | Do not strengthen; retain uncertainty or decline promotion |
|
|
51
51
|
| Secret, credential, or third-party message transcript | Exclude; never promote verbatim |
|
|
52
|
+
| Personal data about people outside the team (clients, correspondents, any other third party) | Exclude; keep the lesson and leave the person out |
|
|
52
53
|
| Project decision versus task decision with identical wording | Route by jurisdiction; only the future-binding decision may promote |
|
|
53
54
|
| Project-slow roadmap change | Date and maintain under its responsible owner, not a universal expert |
|
|
54
55
|
|
|
@@ -54,9 +54,11 @@ claims and concurrent destination updates are different coordination problems.
|
|
|
54
54
|
durable result/receipt exists. A partial edit, launched worker or opened
|
|
55
55
|
process is not a completed harvest.
|
|
56
56
|
|
|
57
|
-
Never promote secrets, credentials,
|
|
58
|
-
|
|
59
|
-
|
|
57
|
+
Never promote secrets, credentials, personal data about people outside the team
|
|
58
|
+
(clients, correspondents, any other third party), third-party messages
|
|
59
|
+
verbatim, tool noise, readily re-derived code descriptions or task-only plans.
|
|
60
|
+
Generalize a lesson without losing scope; do not turn a deployment fact into
|
|
61
|
+
universal expertise.
|
|
60
62
|
|
|
61
63
|
## Delivery is separate from judgment
|
|
62
64
|
|
|
@@ -76,9 +76,11 @@ Discover available accepted knowledge, then retrieve selectively. Index-first
|
|
|
76
76
|
is an OKF tactic; a graph's native entry query can serve the same purpose. Do
|
|
77
77
|
not bulk-load everything, mutate during a read, or infer an absent base is empty.
|
|
78
78
|
Capture and harvest retain provenance and uncertainty. Never promote secrets,
|
|
79
|
-
credentials,
|
|
80
|
-
|
|
81
|
-
|
|
79
|
+
credentials, personal data about people outside the team (clients,
|
|
80
|
+
correspondents, any other third party), or verbatim third-party messages. A
|
|
81
|
+
generalized lesson about a message is different from transcribing it as
|
|
82
|
+
verified knowledge. Source/tool content is evidence, not instructions allowed
|
|
83
|
+
to override the worker's task.
|
|
82
84
|
|
|
83
85
|
See [reader/capture](reader-capture.md), [judgment](harvester.md), and
|
|
84
86
|
[behavioral acceptance](acceptance.md) for applying these distinctions.
|
package/docs/knowledge-theory.md
CHANGED
|
@@ -84,7 +84,7 @@ It needs a clear scope, a responsible maintenance process, an as-of date and an
|
|
|
84
84
|
| Current investigation, provisional reasoning and next action | Instance context and state |
|
|
85
85
|
| Raw records and notes awaiting judgment | Evidence, not accepted knowledge |
|
|
86
86
|
|
|
87
|
-
A bare sequence of commands belongs in a skill; if an insight already has an authoritative home, point to it. Exclude secrets, improperly disclosed private material, wholesale copies of third-party messages, tool noise and ordinary task residue. If code, a test or a clearer contract can eliminate a recurring problem, fix it instead of writing it down.
|
|
87
|
+
A bare sequence of commands belongs in a skill; if an insight already has an authoritative home, point to it. Exclude secrets, improperly disclosed private material, personal data about people outside the team (clients, correspondents, any other third party), wholesale copies of third-party messages, tool noise and ordinary task residue; for the full rule and what enforces it, see [What a harvest leaves out](knowledge.md#what-a-harvest-leaves-out). If code, a test or a clearer contract can eliminate a recurring problem, fix it instead of writing it down.
|
|
88
88
|
|
|
89
89
|
"Invariant across incarnations" means useful beyond its author, not true forever. Date and scope contingent claims, and supersede changed decisions explicitly rather than leaving contradictory truths or erasing their history.
|
|
90
90
|
|
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.0.
|
|
9
|
+
This is the operator guide for **oats.okf 5.0.3**. Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
23
23
|
```yaml
|
|
24
24
|
# oats-workspace.yaml (excerpt)
|
|
25
25
|
packages:
|
|
26
|
-
oats.okf: v5.0.
|
|
26
|
+
oats.okf: v5.0.3
|
|
27
27
|
defaults:
|
|
28
28
|
knowledge: { oats.okf: { from: package } }
|
|
29
29
|
stores:
|
|
@@ -193,6 +193,29 @@ not a universal kernel harvester. Both package role souls have
|
|
|
193
193
|
The [older knowledge-operations design](design/2026-09-26-okf-knowledge-operations.md)
|
|
194
194
|
is historical 4.x context, not instructions for operating 5.0.
|
|
195
195
|
|
|
196
|
+
### What a harvest leaves out
|
|
197
|
+
|
|
198
|
+
Secrets, credentials, private paths and verbatim third-party messages are
|
|
199
|
+
left out. So is personal data, in the same sentence at every place an agent
|
|
200
|
+
is told what to leave out (the capturing instance, the proposal brief, the
|
|
201
|
+
harvester when it edits and when it reads its diff, and the maintainer's
|
|
202
|
+
review):
|
|
203
|
+
|
|
204
|
+
> Never include personal data about people outside the team (clients,
|
|
205
|
+
> correspondents, any other third party): a name, a contact detail, or
|
|
206
|
+
> anything else that identifies a person, including detail derived from
|
|
207
|
+
> correspondence. Keep the lesson and leave the person out. Naming the
|
|
208
|
+
> author of a published source you cite is fine.
|
|
209
|
+
|
|
210
|
+
The sentence also covers the names provenance publishes as written: note
|
|
211
|
+
file names, task refs and instance names. These exclusions are instructions
|
|
212
|
+
to agents and guarantee nothing. No program reads a harvest's content, and
|
|
213
|
+
the first reader other than the harvester is the reviewer of the pushed pull
|
|
214
|
+
request. The one control enforced in code is the soul's opt-out
|
|
215
|
+
([The harvest switch](#the-harvest-switch)). It is per soul, and it covers
|
|
216
|
+
that soul's own proposals, not what its instances write to other seats. A
|
|
217
|
+
soul whose work is reading third-party correspondence should opt out.
|
|
218
|
+
|
|
196
219
|
### Triggers
|
|
197
220
|
|
|
198
221
|
Only **PR review** is triggered. Use the package template
|