@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.
Files changed (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -1,50 +1,55 @@
1
- # Qualified post-answer completion
1
+ # Launch completion after the development-channel Enter
2
2
 
3
3
  ## Boundary and accepted risk
4
4
 
5
- Only after exactly one recorded **submitted** development-channel Enter, under the existing qualified executable/version/platform/argv, exact-home consent, original home identity, pane/PID and 110x35 checks, may structural recognition complete observation. It never authorizes input. Existing exact completion families remain available, subject to the marker precedence below. No structural recognition before an answer, after any terminal outcome, or after failed/uncertain input.
6
-
7
- An unknown dialog can retain the composer and footer and evade this finite marker list. The contract explicitly accepts that completion-reporting risk. Completion closes input authority permanently; it does not establish absence of every dialog, idle state, account admission, channel readiness, or task success. The observed spinner is an in-progress task turn, not an idle prompt. No spinner word, glyph or timing grammar is introduced.
8
-
9
- ## Source provenance
10
-
11
- Read-only pinned Claude Code 2.1.289 darwin-arm64 binary SHA256 `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`. [the source manifest](../lib/launch-prompt-fixtures/structural-completion.json) records exact byte intervals and SHA256s for every reference below. No extracted module enters the repository. These are source-derived rules, not additional observed captures.
12
-
13
- ## Qualified input/footer rule — non-flag footer layout
14
-
15
- This qualifies the non-Jt footer layout (`tengu_copper_thistle` false) in the pinned source. The flag-enabled layout chooses a single hint instead of this list; it is not separately qualified. A remote flag change can alter the footer without changing the binary and reduce matches; only exact listed shapes match, never additional shapes.
16
-
17
- Input is the same compared text object, exactly 35 newline-terminated rows at 110x35, bounded to 64 KiB. No whitespace normalization, cropping, ANSI stripping, case folding or transcript rewrite. Reject embedded CR, ESC and other C0 controls except LF. All rows after the footer must be empty. The footer must be the last nonempty row, with this immediately preceding contiguous region:
18
-
19
- 1. Exactly 110 U+2500 horizontal-line characters.
20
- 2. Exactly U+276F followed by U+00A0 (`❯` plus NBSP), and nothing else: the actual empty composer row, not a prompt-like substring in prose.
21
- 3. Exactly 110 U+2500 horizontal-line characters.
22
- 4. The finite footer below.
23
-
24
- This accepts the region at any row where all four rows fit, not a fixed transcript height. It refuses nonempty/multiline editor drafts, shell or screen-reader selectors, annotated borders, wrapped footers, notifications between editor and footer, status rows below the footer, and footer-less states. It deliberately does not cover every normal renderer configuration.
25
-
26
- Source: `prompt-selector` s0/qK renders Z.pointer+NBSP for the ordinary non-screen-reader input; `prompt-symbol` pins Z.pointer to U+276F. `round-border-glyphs` pins top/bottom to U+2500; `prompt-border` BA and `editor-layout` HWe give top/bottom borders with left/right borders absent. The existing raw API captures and the actual retained Max frame corroborate the exact three input rows at 110 columns. `footer-layout` YHe/Oie gives paddingX=2, row width=110, gap=1, right status marginLeft=auto. The sanitized regression frame's input region is rows 11–14; its home-only sanitized derivative is regression input, not an exact spinner matcher.
27
-
28
- ### Modes (complete list)
29
-
30
- | Native mode | Exact left label | Allowed cycle suffix |
31
- |---|---|---|
32
- | default | `⏸ manual mode on` | absent only |
33
- | plan | `⏸ plan mode on` | absent or ` (shift+tab to cycle)` |
34
- | acceptEdits | `⏵⏵ accept edits on` | absent or same cycle suffix |
35
- | bypassPermissions | `⏵⏵ bypass permissions on` | absent or same cycle suffix |
36
- | dontAsk | `⏵⏵ don't ask on` | absent or same cycle suffix |
37
- | auto | `⏵⏵ auto mode on` | absent or same cycle suffix |
38
-
39
- `mode-map` Sr/DL/bie/qQo enumerates all six; `mode-symbols` pins the symbols; `footer-mode` kx adds literal ` on` when bare is absent. `footer-branches` dHe calls kx without bare and gates the default-keybinding cycle hint on non-default mode and ks. Unknown modes, custom keybindings and bare labels are unsupported.
40
-
41
- After the mode/cycle label, accept only these exact suffixes, each independently enumerated: empty; ` · ← for agents`; ` · esc to interrupt`; ` · esc to interrupt · ← for agents`. For **default mode only**, also ` · ? for shortcuts` or ` · ? for shortcuts · ← for agents`. Sources: `footer-branches` dHe/EFt (escape interrupt, shortcut hint, ordering), `agent-hint` Cze (left-arrow for agents). No return-to-team-lead, task counter, voice, custom status or arbitrary suffix. The normal hints are not negative markers anywhere in the visible frame; an unsupported footer remains unsupported for structural reasons rather than because it contains a question mark or Esc.
42
-
43
- The footer is exactly two ASCII spaces + left text + ASCII space gap + one right label from this complete list: `○ low · /effort`, `◐ medium · /effort`, `● high · /effort`, `◉ xhigh · /effort`, `◈ max · /effort`. `effort` bW/y8 and `mode-symbols` define these glyphs and labels. The right label ends at column 108 (two columns right padding are absent in tmux text); gap is exactly `108 - 2 - leftDisplayWidth - rightDisplayWidth`, and at least one. All enumerated glyphs are single-column in the qualified captured geometry. No `effort:` prefix, ultracode, missing effort, altered punctuation, or other effort value. Existing medium-only exact families remain exact; the additional finite effort rules are source-qualified here, not prior capture qualification.
44
-
45
- ## Qualified negative marker table
46
-
47
- ONLY after exactly one recorded submitted answer, each listed string is matched **case-sensitively as exact contiguous text anywhere in the visible frame**, before either exact or structural positive completion. It can conservatively block a transcript quoting a known question. No regex/question-word heuristic, case folding, line joining, general `?`, general `Esc`, or exemption for an unknown question. Wrapped or customized unknown questions remain within the explicitly accepted risk. Input prompt matching itself is unchanged: the initial qualified channel question must still be answerable before a submitted answer exists.
5
+ This is still reporting only, never input authority. After OATS sends its one
6
+ Enter to Claude's development-channel confirmation (see
7
+ [configuration](configuration.md#the-development-channel-confirmation) and the
8
+ [tolerance list](../lib/launch-prompt-fixtures/README.md)), the controller keeps
9
+ observing the same pane, within the same 30 s bound at 100 ms, only to report
10
+ how the start ended. No second key is ever sent, whatever it sees.
11
+
12
+ An unknown dialog that shows none of the markers below can be reported as
13
+ completed. The contract accepts that reporting risk. Completion closes input
14
+ authority permanently; it does not establish the absence of every dialog, idle
15
+ state, account admission, channel readiness or task success.
16
+
17
+ ## The rule
18
+
19
+ Before the Enter, an unknown screen is a verdict only once it has held
20
+ unchanged for the settle window, `SETTLE` (2 s, in `lib/launch-prompts.mjs`),
21
+ because Claude paints transient frames while it starts: then it is `blocked:
22
+ unexpected prompt`. A screen still changing at the 30 s bound never settled, and
23
+ is `blocked: observation timeout`, never a prompt; see
24
+ [configuration](configuration.md#the-development-channel-confirmation). After
25
+ the Enter, completion takes the same `SETTLE`:
26
+
27
+ - **completed:** `SETTLE` (2 s) of consecutive clean captures. A clean capture
28
+ is non-blank, carries no question marker and equals no tolerance entry after
29
+ normalization. The screen is free to change: a working session repaints all
30
+ the time (a spinner, a counter). The last capture is retained as private
31
+ evidence (recognition `stable-screen`).
32
+ - **blocked:** a capture inside the window that carries a question marker
33
+ (`blocked: unexpected prompt`). A marker never restarts the window. Also
34
+ blocked: the confirmation coming back (`blocked: repeated or unsupported
35
+ prompt`), after another screen was shown, or still showing 2 s after the
36
+ Enter. Until then it may still be painted, and observation goes on. The
37
+ blocked capture is retained as private evidence (recognition `unmatched`), and
38
+ the receipt row says what `differed` against the nearest entry.
39
+ - **blocked: observation timeout:** no complete clean window by the 30 s bound.
40
+ The answers record the one Enter that was sent, and the error and readiness
41
+ remedy say so; no other key is ever sent.
42
+
43
+ A blank capture restarts the window and never blocks. The rule does not depend
44
+ on pane geometry, Claude's footer, mode, model, billing or effort.
45
+
46
+ **The remaining limit:** a question first painted more than 2 s after the
47
+ session is working is the session's own question, not a launch prompt, and the
48
+ start has already completed.
49
+
50
+ ## Question markers
51
+
52
+ Only after the one submitted Enter, each listed string is matched **case-sensitively as exact contiguous text anywhere in the visible capture** (`CLAUDE_QUESTION_MARKERS` in `lib/launch-prompt-completion.mjs`, the single list). It can conservatively block a transcript quoting a known question. No regex/question-word heuristic, case folding, line joining, general `?`, general `Esc`, or exemption for an unknown question. Wrapped or customized unknown questions remain within the explicitly accepted risk. The confirmation itself carries markers; before the Enter they do not apply, and the confirmation is answered only by equality with a tolerance entry. The source references are to Claude Code 2.1.289.
48
53
 
49
54
  | Exact forms (each independently tested) | Pinned source reference |
50
55
  |---|---|
@@ -61,10 +66,7 @@ ONLY after exactly one recorded submitted answer, each listed string is matched
61
66
  | `Enter to select` | selection-dialog literal |
62
67
  | `Esc to exit` | managed-settings + key-hint B |
63
68
 
64
- The historical local-JSX confirmation is not claimed covered by this list; its marker composition was not separately verified and remains an example of the accepted unknown-dialog risk. Real #712 child screens with missing effort and update/focus notices below the footer remain unqualified; the retained A2 frame has the required effort and no trailing notices.
65
-
66
- This is the whole v1 marker set, **not a claim that these are all possible native questions**. Generic custom title/confirm labels can evade it. `? for shortcuts` and `esc to interrupt` are explicitly normal UI, never markers. No case-insensitive expansion to `enter to confirm`, `esc to exit`, etc. without another qualified table update.
67
-
69
+ This is the whole marker set, **not a claim that these are all possible native questions**. Generic custom title/confirm labels can evade it. `? for shortcuts` and `esc to interrupt` are explicitly normal UI, never markers. No case-insensitive expansion to `enter to confirm`, `esc to exit`, etc. without another reviewed table update.
68
70
 
69
71
  Private retention and receipt-v2 collection rules are documented in
70
72
  [execution targets](execution-targets.md#private-unmatched-launch-evidence).
@@ -0,0 +1,246 @@
1
+ # macOS test runs
2
+
3
+ Pull-request CI runs the tests on Linux only. Some tests rest on what only
4
+ macOS does: a file system that ignores case, `/var` and `/tmp` as links, long
5
+ temporary paths, the BSD tools. The workflow
6
+ [`macos-tests.yml`](../.github/workflows/macos-tests.yml) runs named test files
7
+ of a named ref on a macOS runner. A person starts it by hand; no push and no
8
+ pull request ever does. The link of its run goes on a pull request as that
9
+ pull request's macOS evidence.
10
+
11
+ It is not a second CI. It runs the files you name, each alone, and nothing
12
+ else: not `npm test`, not a shard.
13
+
14
+ ## Starting a run
15
+
16
+ You need write access to the repository. From a checkout:
17
+
18
+ ```bash
19
+ gh workflow run macos-tests.yml --ref main \
20
+ -f ref=my-branch \
21
+ -f files='test/tui-terminal.test.mjs test/fixture-isolation.test.mjs' \
22
+ -f tmux=true
23
+ gh run list --workflow=macos-tests.yml --limit 1
24
+ ```
25
+
26
+ Or on the repository's Actions page: choose **macOS tests**, then **Run
27
+ workflow**. Leave the workflow's own branch at `main` (see
28
+ [What counts as evidence](#what-counts-as-evidence)).
29
+
30
+ | input | what it is |
31
+ |---|---|
32
+ | `ref` | The commit to test: a branch name, a tag name or a full commit id (40 characters) of this repository. |
33
+ | `files` | The test files, separated by spaces, commas or newlines. |
34
+ | `tmux` | `true` installs tmux first (`brew install tmux`). Off by default. Tests that need tmux skip without it. |
35
+
36
+ ## What a run accepts
37
+
38
+ The script [`scripts/macos-tests.mjs`](../scripts/macos-tests.mjs) checks the
39
+ whole request before anything of the ref is checked out, installed or run. A
40
+ refusal names every entry it refuses and why, and the run fails having run
41
+ nothing.
42
+
43
+ **The ref** must be a commit of this repository: one reachable from a branch
44
+ or a tag of `origin`.
45
+
46
+ - A name is made of `A-Z a-z 0-9 . _ / -`, does not start with `-` and has no
47
+ `..`. A branch whose name has another character is given by its full commit
48
+ id. The text is taken as typed: a space before or after it is refused too.
49
+ - A shortened commit id is refused: give all 40 characters.
50
+ - **A pull request's number is not accepted.** A pull request from a fork has
51
+ a head that is not this repository's commit, and nothing is ever fetched by
52
+ what you typed. Name the branch, or give the commit id, of a pull request
53
+ whose branch is in this repository.
54
+ - A name that is both a branch and a tag is accepted when both are the same
55
+ commit. Otherwise give the commit id of the one you mean.
56
+
57
+ **Each file** must match `test/**/*.test.mjs` or
58
+ `packages/<name>/test/**/*.test.mjs`, with path segments made of
59
+ `A-Z a-z 0-9 . _ -`, none starting with a dot. It must be a regular file at
60
+ that commit, not a symbolic link. A file named twice runs once.
61
+
62
+ ## What a run does and prints
63
+
64
+ The job checks out two trees. `runner/` is the workflow's own commit, and the
65
+ script runs from it. `tested/` is the ref. Two trees are for two things: a
66
+ ref older than the workflow can be tested, and an honest branch cannot change
67
+ the runner by accident. They are not a defence against a commit that sets out
68
+ to forge its result (see [What a run does not protect](#what-a-run-does-not-protect)).
69
+
70
+ After the validation the job installs as pull-request CI does (`npm ci` at
71
+ the root, then in `packages/desktop` without the Electron binary). Then it
72
+ runs each file alone, one after another, as a developer does: `node --test
73
+ <file>` from the root of the ref's tree.
74
+
75
+ The step **Validate the request and check out its commit** prints a header,
76
+ before any code of the ref has run:
77
+
78
+ - the commit under test (full id) and the ref that was asked for;
79
+ - the workflow's own ref and commit, as the script reads them (where a run
80
+ really ran from is GitHub's record of it, not this line: see
81
+ [What counts as evidence](#what-counts-as-evidence));
82
+ - the macOS version, the runner image and the architecture;
83
+ - the Node version;
84
+ - whether the file system is case-sensitive, measured there (a file is made,
85
+ then looked for by another case);
86
+ - whether `tmux` is on `PATH`, and its version;
87
+ - whether a socket is at tmux's default place for the server named `oats`.
88
+
89
+ Its last line says so: `Everything above this line was printed before any code
90
+ of the ref ran.` The step **Run each file alone** prints the header again
91
+ before the first file, read after the installs, and says that it is the second
92
+ reading.
93
+
94
+ For each file the log has its output, then its counts (tests, passed, failed,
95
+ skipped, cancelled, todo), its exit status and its duration. One table of all
96
+ files ends the log, and the job's summary page repeats it.
97
+
98
+ **What fails a run:**
99
+
100
+ - A file fails when its exit status is not 0. A file that ends with status 0
101
+ and prints no summary, or whose summary counts a failed test, fails too. The
102
+ files after a failing one still run.
103
+ - A file that has not ended after its time is killed with its whole process
104
+ group and reported as timed out. The run goes on.
105
+ - **A tmux server left on the default socket.** A fixture that fails to
106
+ isolate its tmux server starts one at tmux's default place
107
+ (`<dir>/tmux-<uid>/oats`, where `<dir>` is `TMUX_TMPDIR`, else `/tmp`). On a
108
+ clean runner nothing fails because of it. So the script looks at that place
109
+ before the first file and after each file. The file after which a socket
110
+ first exists is marked in the table, and the run fails. Nothing is killed or
111
+ removed. If a socket is there before the first file, the header says so and
112
+ the check is skipped for that run.
113
+
114
+ A file in which no test passed (every test skipped, for example without tmux)
115
+ is marked `no test passed`. It does not fail the run.
116
+
117
+ ## What counts as evidence
118
+
119
+ **A run is evidence for a commit whose diff has been reviewed.** A run of a
120
+ commit that nobody has read proves nothing about it: from its first install
121
+ step on, the commit's own code runs on the runner and can change what the run
122
+ prints (see [What a run does not protect](#what-a-run-does-not-protect)).
123
+
124
+ The pull request gives **the run's link**. From it, a run is macOS evidence
125
+ when all of this holds. The first condition comes first because the others
126
+ rest on it.
127
+
128
+ 1. **The workflow ran from `main`, by GitHub's own record of the run.** Not
129
+ by the log. A run started from another branch uses that branch's workflow
130
+ file and that branch's script, so every line of its log, the header
131
+ included, is text that branch wrote. Ask GitHub about the run instead:
132
+
133
+ ```bash
134
+ gh run view <run id> --json event,headSha,workflowName
135
+ git fetch origin
136
+ git merge-base --is-ancestor <headSha> origin/main; echo $?
137
+ ```
138
+
139
+ `event` must be `workflow_dispatch` and `workflowName` must be `macOS
140
+ tests`. The last command must print `0`: the workflow's commit is a commit
141
+ of `main`. Anything else is not a pass: `1` means the commit is not on
142
+ `main`, and an error means your clone does not have it. Check the commit,
143
+ not the run's branch name: a tag can carry a branch's name.
144
+ 2. The `commit under test` in the validation step's header **equals the head
145
+ under review**. A run of an earlier head is evidence for that head only.
146
+ 3. The run passed, and no file the pull request relies on is marked `no test
147
+ passed`. **A run of only skips is not evidence.**
148
+
149
+ The header also prints a `workflow ref` line. It is a convenience for
150
+ reading a run, and it is not proof of where the workflow ran from: the
151
+ workflow prints it.
152
+
153
+ With the first condition met, the log is the evidence. The job's summary page
154
+ is a convenience.
155
+
156
+ ## Bounds
157
+
158
+ These are constants of the script, not inputs:
159
+
160
+ | bound | value |
161
+ |---|---|
162
+ | files in one run | at most 10 files |
163
+ | time for one file | 5 minutes, then its process group is killed |
164
+ | time for the job | 60 minutes |
165
+ | runner | `macos-14` (arm64), Node 22 |
166
+
167
+ The workflow's steps upload no artifact and save or restore no cache: the log
168
+ and the summary are all they leave. The token can read the repository's
169
+ contents and do nothing more, and the workflow names no secret. The code a run
170
+ executes can reach more than the workflow's own steps do: see
171
+ [What a run does not protect](#what-a-run-does-not-protect).
172
+
173
+ ## What a run does not show
174
+
175
+ - **A clean machine, not yours.** The runner is a fresh image for each run.
176
+ It has no person's `PATH`, shell profile or login environment, and nothing
177
+ of an earlier run.
178
+ - **No real terminal.** No terminal emulator is attached to the tests.
179
+ - **One macOS version and one architecture**: the image's, printed in the
180
+ header.
181
+ - **A killed file's leftovers.** The script kills the process group of a file
182
+ that timed out. A tmux server has left that group by design, so a tmux
183
+ server of a killed file stays, and it is that test's to explain.
184
+ - **Nothing about `main`.** A run started from `main` is listed among the
185
+ runs of main's head commit (`gh run list --commit <sha>`) and among that
186
+ commit's check runs, as `Named test files on macOS`. Its result is about
187
+ the ref under test. It says nothing about `main`, a failed run included.
188
+ The commit's status rollup does not hold these runs. A macOS run can be the
189
+ newest run on `main`, so whoever checks `main` after a merge lists the runs
190
+ by workflow (`gh run list --workflow CI --branch main`) or reads the
191
+ commit's status rollup.
192
+
193
+ So a pull request that asks for a person's run on a Mac still gets one.
194
+
195
+ ## What a run does not protect
196
+
197
+ After the validation, the ref's own code runs on the runner as the runner's
198
+ user: its install scripts, then its tests. Pull-request CI does the same for
199
+ every branch.
200
+
201
+ **Protected, in a run whose workflow commit is `main`'s: the validation and
202
+ the header.** They are printed from the workflow's own commit, before any
203
+ code of the ref has run. A commit under test cannot change which commit the
204
+ header names, or get a refused request past it. In a run started from another
205
+ branch nothing is protected: the workflow and the script are that branch's
206
+ (see [What counts as evidence](#what-counts-as-evidence)).
207
+
208
+ **Not protected: everything after the first install step**, the per-file
209
+ results and the table included. From there on, the ref's code can change
210
+ anything the runner's user can, and so what the later steps print. The result
211
+ is as honest as the commit.
212
+
213
+ **Where the check is.** A forgery has to be in the commit's own tree, its lock
214
+ file included. The evidence names that exact commit, and the reviewer of the
215
+ pull request reads its diff. Pull-request CI has the same property.
216
+
217
+ **The cache scope of the default branch.** A run started from the default
218
+ branch belongs to it, and executes another branch's code. Such code can reach
219
+ that run's Actions cache scope, which every branch reads. Only somebody with
220
+ write access can do it, by pushing the branch and starting the run. In the
221
+ maintainers' words: a run of this workflow can write the default branch's
222
+ cache scope; nothing reads it; a workflow that starts to restore a cache
223
+ reopens this. No workflow of this repository restores an Actions cache, and
224
+ the repository's tests keep it so.
225
+
226
+ **The job's token.** It is within reach of the code a run executes. It can
227
+ read this repository's contents and nothing else, and that is why this
228
+ workflow's `permissions` never grows.
229
+
230
+ ## The terms
231
+
232
+ The maintainers agreed these terms. `test/macos-tests-workflow.test.mjs`
233
+ reads the workflow file and pins each one:
234
+
235
+ - `workflow_dispatch` is the only trigger;
236
+ - `permissions` is exactly `contents: read`; no secret is named; no artifact
237
+ is uploaded; no step saves or restores a cache;
238
+ - no input is written into a shell line: the ref and the file list reach the
239
+ script as environment variables;
240
+ - the checkout is the workflow's own commit, without its token left in the
241
+ checkout's configuration;
242
+ - the job has a timeout, and its concurrency group is its own and one per
243
+ run, so no later run cancels an earlier one.
244
+
245
+ Change a bound or a term with the maintainers' decision, and change this page
246
+ and that test in the same commit.
@@ -36,13 +36,14 @@
36
36
  "type": "object",
37
37
  "additionalProperties": false,
38
38
  "properties": {
39
- "awebDevelopmentChannel": { "type": "boolean" }
39
+ "awebDevelopmentChannel": { "type": "boolean" },
40
+ "workspaceTrust": { "type": "boolean" }
40
41
  }
41
42
  },
42
- "description": "Exact absolute canonical instance-home paths only; no wildcard or ancestor inheritance. Runtime validation resolves existing ancestors for homes not yet created."
43
+ "description": "Instance-home paths. An entry awebDevelopmentChannel: false is refused (removed-key); every other entry is ignored."
43
44
  }
44
45
  },
45
- "description": "Host-only consent to the bounded exact aweb development-channel confirmation. Missing awebDevelopmentChannel is false; provider settings and captured recipes do not grant consent."
46
+ "description": "Ignored, kept so it can be judged: OATS confirms Claude's development-channel prompt whenever it launches Claude with --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace. A home entry awebDevelopmentChannel: false is refused; remove the block."
46
47
  },
47
48
  "settings": {
48
49
  "type": "object",
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.9.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.24.1` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.9.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.27.1` | `oats.aweb` (messaging) | |
15
+ | `oats.engineering` | `v1.9.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.1`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.0.3`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.1 # bare version → the official catalog
47
+ oats.okf: v5.0.3 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.1`, `5.0.1`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.0.3`, `5.0.3`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.0.1` or `oats-framework/v1.9.1`) and the payload path. An id
54
+ convention (`v5.0.3` or `oats-framework/v1.9.4`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.9.1
78
- oats.okf: v5.0.1
79
- oats.aweb: v1.24.1
77
+ oats.framework: v1.9.4
78
+ oats.okf: v5.0.3
79
+ oats.aweb: v1.27.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.1 ✓ (@ 96b28d5c)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.3 ✓ (@ e687a94a)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.24.1 # a catalog version
137
+ oats package add oats.aweb v1.27.1 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.1",
164
- "commit": "96b28d5cd4f01e48ed50d8e999e8715749a99e87",
163
+ "version": "5.0.3",
164
+ "commit": "e687a94a40494521a671979dd168e3d62b11bcde",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.1", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.3", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.4", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.9.1`
362
- resolves to tag `oats-framework/v1.9.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.9.4`
362
+ resolves to tag `oats-framework/v1.9.4`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.