@awebai/oats 0.52.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 (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -45,19 +45,32 @@ That start worked, so the dialog closes and the terminal opens as for any
45
45
  start. A notice then says that the instance started and that Claude Code
46
46
  ignored the channel option, so mail and chat will not wake it; with the reason
47
47
  `channels-unavailable` it adds that Claude Code reported channels are not
48
- available. Behind the notice's Details: "OATS says:" and every warning of that
49
- answer, whole and in the order given, each as one display line. No warning is
50
- picked, matched or dropped by its words: the kernel's own sentence is one
51
- string among them, and Desktop does not look for it. The notice is also shown
52
- when the dialog was closed while the start ran, as long as the workspace it was
53
- started from is still on screen.
48
+ available. Behind the notice's Details: "OATS says:" and the warnings of that
49
+ answer, whole and in the order given, each as one display line. It shows at
50
+ most 16 warnings, and at most 4096 characters of them: lines are taken in
51
+ order while both bounds hold, and no line is cut inside. With more, a last
52
+ line says how many are left out ("3 more not shown."). The cut is by
53
+ position. No warning is picked, matched or dropped by its words: the kernel's
54
+ own sentence is one string among them, and Desktop does not look for it. The
55
+ kernel puts that sentence last, so warnings that fill the bound before it
56
+ leave it out: the headline still says what happened, a person then does not
57
+ see OATS's own advice on what to check, and the last line says that something
58
+ was left out. The notice is also shown when the dialog was closed while the
59
+ start ran, as long as the workspace it was started from is still on screen.
54
60
 
55
- The reader is `flagIgnoredNotice` (`packages/client/launch-prompt-outcome.mjs`).
56
- It takes an answer's `launchPrompts` and `warnings`, gives the headline and the
57
- lines, and knows nothing of the act that was answered. It is tolerant: an
58
- answer it cannot read, or any other status, gives no notice, and the start
59
- reads as any start that worked. Only the start dialog calls it: the Desktop
60
- does not yet read `launchPrompts` on a spawn's answer.
61
+ The reader is `launchFlagIgnored` (`packages/client/launch-prompt-outcome.mjs`).
62
+ It takes an answer's `launchPrompts` and `warnings` and gives the fact
63
+ `{reason, warnings, omitted}`: the lines it keeps, bounded by
64
+ `FLAG_IGNORED_WARNINGS` lines and `FLAG_IGNORED_UNITS` UTF-16 units in total,
65
+ and how many lines the cut left out. It knows nothing of the act that was
66
+ answered. `flagIgnoredNotice` makes the headline and the
67
+ detail from that fact, and from nothing else. Both are tolerant: an answer the
68
+ reader cannot read, or any other status, gives no fact and no notice, and the
69
+ start reads as any start that worked. The start dialog calls them for a
70
+ start's and a restart's answer. A launched spawn's answer goes through the same
71
+ reader into its creation receipt, and the notice is the same
72
+ (`packages/desktop/docs/desktop-spawn-preview.md`, A spawn where Claude Code
73
+ ignored the channel option).
61
74
 
62
75
  If an ordinary Start dialog finds the instance already running, its action becomes
63
76
  **Open terminal**. A failed or timed-out start requires **Refresh status** before
@@ -380,6 +380,7 @@ with: `COLORFGBG`, `TMUX`, `TMUX_PANE`; the launch identity and roots
380
380
  (`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `OATS_HOME`, `OATS_AGENT`,
381
381
  `OATS_SOUL`, `OATS_SOUL_ID`, `OATS_ROOT`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
382
382
  `OATS_EVENT`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`,
383
+ `OATS_NODE_BIN` (the node a hook writes into anything that outlives it),
383
384
  `PI_AGENT_INSTANCE`, `PI_AGENT_HOME`, `PI_AGENTS_ROOT`); what a hook, an
384
385
  operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
385
386
  `OATS_LEVEL`, `OATS_META`, `OATS_DEPLOYMENT`, `OATS_RESOLUTION`,
@@ -45,6 +45,26 @@ a flat directory of `.mjs` modules with no manifest of its own, not a package.
45
45
  imports only itself and `node:` builtins, `lib/` and `bin/` import nothing
46
46
  from it, and the test lists the stable surface a second client may import.
47
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
+
48
68
  ## Repository layout
49
69
 
50
70
  | path | contents |
@@ -59,7 +79,7 @@ from it, and the test lists the stable surface a second client may import.
59
79
  | `souls/` | this repository's own souls (a workspace member) |
60
80
  | `docs/` | the reference pages, schemas, design records and release notes |
61
81
  | `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
62
- | `scripts/` | the test runner, validators, packaging checks and the release lane |
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 |
63
83
  | `test/` | the kernel and CLI suites, with their fixtures |
64
84
 
65
85
  ## Kernel modules
@@ -77,7 +97,12 @@ from it, and the test lists the stable surface a second client may import.
77
97
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
78
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` |
79
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` |
80
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 |
81
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 |
82
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 |
83
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 |
@@ -86,7 +111,7 @@ from it, and the test lists the stable surface a second client may import.
86
111
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
87
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 |
88
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 |
89
- | `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) |
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 |
90
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 |
91
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 |
92
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 |
@@ -103,6 +128,7 @@ from it, and the test lists the stable surface a second client may import.
103
128
  | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
104
129
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
105
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 |
106
132
 
107
133
  The schedule registry stores explicit concurrency caps, leaving the schedule
108
134
  cap absent for its effective default of five. `readRegistry()` is a pure,
@@ -279,6 +305,37 @@ caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
279
305
  partial cache it meets is deleted and fetched again whole, and the same
280
306
  notice says why.
281
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
+
282
339
  Every write to a cache repo (its `git init`, config, fetches and pins) holds
283
340
  the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
284
341
  (`withCacheWriteLock`): an exclusive file holding `{pid, token, startedAt}`,
@@ -303,6 +360,12 @@ file and when it is safe to remove; so is any other local write failure
303
360
  (a `FETCH_HEAD` git cannot open, a read-only or full disk), with git's own
304
361
  words.
305
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
+
306
369
  Across commands, `memoAtCommit` keeps parsed reads under
307
370
  `<cache>/.parsed/<kernel fingerprint>/`, keyed by (repo key, full commit,
308
371
  item). The items: `workspace` (the workspace file), `membership` (a member's
@@ -325,10 +388,11 @@ scaling by call count.
325
388
 
326
389
  | command | what it checks |
327
390
  |---|---|
328
- | `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`) |
329
393
  | `npm run check` | syntax of every shipped file |
330
394
  | `npm run check:pi` | the pi adapter's TypeScript |
331
- | `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`) |
332
396
  | `npm run pack:check` | an `npm pack` dry run of both packages: nothing missing, nothing leaked |
333
397
  | `npm run smoke:tarball` | installs the packed tarballs outside the checkout and exercises them |
334
398
 
@@ -339,6 +403,20 @@ dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
339
403
  and is the gate. Tests use local bare repositories and fakes; none contacts
340
404
  GitHub, aweb, Jira or Linear.
341
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
+
342
420
  Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
343
421
  load with only Desktop dependencies installed. The release builds Desktop that
344
422
  way: its `desktop-build` job installs and tests inside `packages/desktop` and
@@ -365,8 +443,14 @@ kernel. Where an answer needs a second writer at an exact moment (an entry
365
443
  that vanishes between a walk's listing and its read), the test runs the CLI
366
444
  as a child held at one named `node:fs` call with
367
445
  `test/helpers/fs-gate-preload.mjs` (`startGated`), does what the second writer
368
- does, and releases it. The helper only pauses: it changes no argument and no
369
- result.
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.
370
454
 
371
455
  Cross-package tests that import both the kernel and Desktop belong under root
372
456
  `test/`; install dependencies at the root and in `packages/desktop` before
@@ -494,17 +578,97 @@ inherits it (awebai/oats#816):
494
578
  filesystem's.
495
579
  - **An explicit environment for every child.** `fixtureEnv(base)` is what
496
580
  every child the fixture starts gets, and `fx.inEnv` applies the same rules
497
- to the test process for an in-process kernel call. It sets `HOME` and the XDG
498
- base directories under the base, and `GIT_CONFIG_NOSYSTEM=1`,
499
- `GIT_CONFIG_GLOBAL=/dev/null` and `GIT_TERMINAL_PROMPT=0`, so no host git
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
500
596
  configuration or credential helper is read. It removes every `*_PROXY`,
501
597
  `CLAUDECODE` and git configuration passed through the environment. PATH
502
598
  starts with `launchctl` and `systemctl` stubs that answer as a service
503
599
  manager with nothing loaded. A test that needs another answer puts its own
504
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.
505
635
  - **The same rules under real tmux.** `isolateSessionEnvironment` applies the
506
- same git, XDG and proxy rules. Its PATH stays its own small set of tools, so
507
- no host service manager is reachable at all.
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.
508
672
  - **No leftover processes.** The fixture's cleanup fails when a process still
509
673
  works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
510
674
  `processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
@@ -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.2
44
- oats.aweb: v1.27.0
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:
@@ -140,7 +140,10 @@ Building an integration is implementing a contract. The framework's
140
140
  its `binding.check` command
141
141
  ([capabilities.md](capabilities.md#readiness-check-bindingcheck)).
142
142
  - Package commands and hooks reach the kernel only through `OATS_CLI_BIN` and
143
- the JSON envelope, never by importing kernel files. Never name target souls
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
144
147
  in the manifest: which souls get a capability is configuration.
145
148
 
146
149
  **Knowledge.** The capability owns its complete runtime and format, including
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.2**. Provider implementation and
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.2
26
+ oats.okf: v5.0.3
27
27
  defaults:
28
28
  knowledge: { oats.okf: { from: package } }
29
29
  stores:
@@ -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.