@awebai/oats 0.68.1 → 0.69.2

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 (99) hide show
  1. package/bin/oats.mjs +180 -36
  2. package/docs/capabilities.md +73 -10
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/configuration.md +68 -2
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  6. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  7. package/docs/desktop-cli-api.md +600 -25
  8. package/docs/desktop-instance-start.md +59 -3
  9. package/docs/desktop.md +175 -10
  10. package/docs/execution-targets.md +536 -62
  11. package/docs/harness-trust.md +3 -1
  12. package/docs/implementation.md +33 -15
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge.md +25 -16
  15. package/docs/oats-local.schema.json +2 -2
  16. package/docs/official-catalog.md +6 -5
  17. package/docs/packages.md +14 -14
  18. package/docs/release-notes/v0.69.0.md +658 -0
  19. package/docs/release-notes/v0.69.1.md +25 -0
  20. package/docs/release-notes/v0.69.2.md +259 -0
  21. package/docs/servers.md +51 -7
  22. package/docs/soul.schema.json +1 -0
  23. package/docs/souls-and-instances.md +46 -9
  24. package/docs/tui.md +177 -21
  25. package/docs/upgrading.md +16 -7
  26. package/docs/workspaces.md +2 -2
  27. package/injects/instance-boundary.md +19 -33
  28. package/injects/work-attached.md +8 -13
  29. package/injects/work-checkout.md +16 -30
  30. package/injects/work-directory.md +9 -15
  31. package/injects/work-workspace.md +8 -19
  32. package/injects/work-worktree.md +18 -33
  33. package/lib/capability-contract.mjs +2 -2
  34. package/lib/core.mjs +496 -127
  35. package/lib/file-pieces.mjs +49 -0
  36. package/lib/instance-background.mjs +54 -0
  37. package/lib/instance-events.mjs +25 -4
  38. package/lib/instance-inspect.mjs +3 -0
  39. package/lib/instance-lifecycle.mjs +35 -0
  40. package/lib/instance-resolution.mjs +3 -2
  41. package/lib/instance-same-work.mjs +67 -0
  42. package/lib/instance-upgrade.mjs +18 -0
  43. package/lib/launch-prompt-fixtures/README.md +62 -0
  44. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  45. package/lib/launch-prompt-fixtures.mjs +49 -0
  46. package/lib/launch-prompt-resume.mjs +55 -0
  47. package/lib/login-environment.mjs +27 -9
  48. package/lib/materialize.mjs +23 -2
  49. package/lib/resolve.mjs +32 -5
  50. package/lib/schedule.mjs +3 -3
  51. package/lib/servers.mjs +136 -27
  52. package/lib/session-end.mjs +82 -0
  53. package/lib/session-input.mjs +43 -9
  54. package/lib/session-resume-contract.mjs +33 -0
  55. package/lib/session-resume.mjs +337 -0
  56. package/lib/session-seen.mjs +163 -0
  57. package/lib/session-viewer.mjs +147 -44
  58. package/lib/soul-composition.mjs +15 -11
  59. package/lib/start-env.mjs +110 -0
  60. package/lib/tmux-server-scope.mjs +139 -14
  61. package/lib/workspace.mjs +41 -6
  62. package/package-catalog.json +11 -5
  63. package/package.json +1 -1
  64. package/packages/client/cli-adapter.mjs +39 -8
  65. package/packages/client/cli-locator.mjs +3 -2
  66. package/packages/client/deployment-data.mjs +16 -0
  67. package/packages/client/deployment-panel.mjs +7 -0
  68. package/packages/client/file-output-exec.mjs +98 -0
  69. package/packages/client/instance-tree.mjs +64 -14
  70. package/packages/client/launch-prompt-outcome.mjs +25 -13
  71. package/packages/client/own-codes.mjs +2 -0
  72. package/packages/client/panel-views.mjs +11 -3
  73. package/packages/client/remote-roster.mjs +5 -1
  74. package/packages/client/roster-sections.mjs +50 -6
  75. package/packages/client/same-work.mjs +49 -0
  76. package/packages/client/session-attach.mjs +35 -5
  77. package/packages/client/session-resume-cli.mjs +64 -0
  78. package/packages/client/session-resume-trigger.mjs +167 -0
  79. package/packages/client/session-resume.mjs +332 -0
  80. package/packages/client/soul-rows.mjs +2 -0
  81. package/packages/client/spawn-apply-contract.mjs +2 -1
  82. package/packages/client/spawn-decision.mjs +4 -1
  83. package/packages/client/spawn-preview-contract.mjs +12 -1
  84. package/packages/client/spawn-preview.mjs +2 -0
  85. package/packages/client/tmux-status.mjs +30 -7
  86. package/packages/client/waiting-on-you.mjs +11 -4
  87. package/packages/client/workspace-step.mjs +17 -5
  88. package/packages/record/lib/last-conversation.mjs +123 -0
  89. package/packages/record/lib/session-roots.mjs +10 -1
  90. package/packages/tui/README.md +2 -2
  91. package/packages/tui/lib/client.mjs +7 -3
  92. package/packages/tui/lib/main.mjs +49 -14
  93. package/packages/tui/lib/model.mjs +146 -55
  94. package/packages/tui/lib/store.mjs +84 -27
  95. package/packages/tui/lib/term/text.mjs +12 -9
  96. package/packages/tui/lib/views/frame.mjs +74 -7
  97. package/packages/tui/lib/views/help.mjs +10 -3
  98. package/packages/tui/lib/views/instances.mjs +41 -3
  99. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -35,7 +35,9 @@ reads. The targets of each selected harness are:
35
35
  session's or server's `HOME`. It is not the operator's own shell's when
36
36
  the server holds another account;
37
37
  - one file for each launch configuration (`launch-configs:` in the
38
- deployment's `oats-local.yaml`) of that harness whose `env` sets
38
+ deployment's `oats-local.yaml`, or in this machine's
39
+ [`~/.oats/config/launch-configs.yaml`](configuration.md#this-machines-launch-configurations))
40
+ of that harness whose `env` sets
39
41
  `CLAUDE_CONFIG_DIR` (claude) or `CODEX_HOME` (codex), as a literal or a
40
42
  `{fromEnv: NAME}` reference resolved from the environment the command runs
41
43
  in;
@@ -53,10 +53,11 @@ effect of reading: for each deployment opened in a run it runs the kernel
53
53
  of the same install and the shared liveness collector as children, through
54
54
  the shared observer and refresh loop; it runs that kernel's read of the
55
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 one look at the file
56
+ no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
57
57
  system the workspace switcher needs (whether a picked row is a deployment).
58
58
  This computer's list of deployments is the kernel's: `lib/main.mjs` reads
59
- and changes it through the shared `cliDeploymentList`. `lib/store.mjs` is the state and a pure
59
+ and changes it through the shared `cliDeploymentList`, and runs the kernel's
60
+ machine sweep of lost sessions when the shared resume trigger says, as a change. `lib/store.mjs` is the state and a pure
60
61
  `reduce(state, event)`; `lib/model.mjs` turns the state into the rows to
61
62
  draw by calling the shared readers through `lib/client.mjs`, the one module
62
63
  that imports `packages/client/`; `lib/views/` are pure functions from that
@@ -107,20 +108,21 @@ and the rules its tests pin.
107
108
  | `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 |
108
109
  | `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
109
110
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
111
+ | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: one producer, `listInstances`; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` values (`start-env.mjs`: a keyed digest per variable, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
110
112
  | `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 |
111
113
  | `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 |
112
114
  | `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 |
113
115
  | `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 |
114
116
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
115
117
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
116
- | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through |
118
+ | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
117
119
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
118
120
  | `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 |
119
- | `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 |
121
+ | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade` and `oats session start --resume` (`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 |
120
122
  | `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, an exact mode, a failed removal reported, a sync) keeps its own code |
121
123
  | `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 |
122
124
  | `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 |
123
- | `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 |
125
+ | `tmux-server-scope.mjs` | where sessions run on a systemd host: whether the OATS tmux server starts in a scope of its own (the creator's cgroup judged: Linux, unified hierarchy, inside a `.service` or a scope of the user manager), and whether each agent's harness is launched in one (`agentScope`: the probe, run with the pane's bus variables and cached per process, and the wrapper `nativeRecordCommand` renders); the scopes' names and the warnings when they cannot |
124
126
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
125
127
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
126
128
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
@@ -128,13 +130,15 @@ and the rules its tests pin.
128
130
  | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
129
131
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
130
132
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
131
- | `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
133
+ | `file-pieces.mjs` | a regular file's bytes read in pieces of 1 MiB (`readFilePieces`, `hashFile`, and `readFileUpTo` for a home's `instance.json`, read whole up to 16 MiB for its neutral form), for every digest of the retire path: what a digest holds of a file is bounded whatever its size (Node reads no file over 2 GiB whole), and a file is read for the size it had when it was opened. One that ends before that size refuses with `E_WORK_INSPECTION_FAILED` |
134
+ | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
132
135
  | `servers.mjs` | routing commands to a registered server |
133
136
  | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
134
137
  | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
135
138
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
136
139
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
137
140
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
141
+ | `launch-prompt-resume.mjs` | the report-only watch of a resumed Claude pane for its resume-cost dialog (`resume-confirmation` entries in `launch-prompt-fixtures/resume-confirmation.json`, matched by whole option labels): at most 20 s, never a key |
138
142
  | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts, one Enter only on equality with a tolerance entry |
139
143
  | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches; the table of the variable that moves each harness's folder (`HARNESS_FOLDER_VAR`) and the one reader of a launch configuration's (`launchConfigFolder`), used by the trust code, `pi-bridge.mjs` and `core.mjs`: it reads only files and imports none of them. What a launch's pane will have for those variables, `PATH` and `HOME` is `launchEnvironment` in `core.mjs`, the one answer every check of a launch reads ([execution-targets.md](execution-targets.md#the-checks-read-the-pane)); it carries the names the launch removes (`removedLaunchEnv`: declared by its capabilities, not in their payload), which `launchEffectiveEnv` leaves out and the window command (`paneCommand`) unsets ([capabilities.md](capabilities.md#a-declared-name-is-the-providers)) |
140
144
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
@@ -710,22 +714,36 @@ and acts on every existing session through its recorded socket
710
714
  - A server a test starts is killed by its socket, never by name and never
711
715
  with a bare `tmux kill-server`.
712
716
  - A test never reaches the host's `systemd-run` (#915). A Linux creator
713
- inside a systemd service starts the server through the system's own
714
- `systemd-run`, found by absolute path, not on `PATH`, so a fake-free `PATH`
715
- does not stop it. The fixtures (`isolateSessionEnvironment`, `fixtureEnv`)
716
- therefore set `OATS_TEST_CGROUP` to a scope, never a service, whatever runs
717
- the suite. Two test-only seams select where the kernel judges itself and
717
+ inside a systemd service or a user-manager scope starts the server through
718
+ the system's own `systemd-run`, and every launch on the unified hierarchy
719
+ probes it for the agent's scope, found by absolute path, not on `PATH`, so
720
+ a fake-free `PATH` does not stop it. The fixtures (`isolateSessionEnvironment`,
721
+ `fixtureEnv`) therefore set `OATS_TEST_CGROUP` to a scope outside the user
722
+ manager, never a service, whatever runs the suite, and
723
+ `OATS_TEST_SYSTEM_TOOL_DIRS` to the fixture's own `fixture-system-tools`:
724
+ the host's `env` and `true`, and a `systemd-run` that runs what follows
725
+ `--` in its own process. So every fixture launch is wrapped, and passes
726
+ through that fake, never the host's user manager. A test of a scope sets
727
+ its own. Three test-only seams select where the kernel judges itself and
718
728
  which `systemd-run` it runs:
719
- - `OATS_TEST_CGROUP`: the text of a `/proc/self/cgroup`, judged as Linux;
729
+ - `OATS_TEST_CGROUP`: the text of a `/proc/self/cgroup`, judged as Linux
730
+ booted with systemd;
731
+ - `OATS_TEST_SYSTEMD_BOOTED`: `1` or `0`, in place of whether
732
+ `/run/systemd/system` is a directory (sd_booted): `0` is a Linux host
733
+ without systemd, where no agent scope is judged;
720
734
  - `OATS_TEST_SYSTEM_TOOL_DIRS`: absolute directories separated by `:`, in
721
735
  place of `/usr/bin:/bin`. Any other value means no system tool, never a
722
736
  `PATH` lookup.
723
737
 
724
- Both are reserved launch names (a launch configuration cannot set them),
738
+ All three are reserved launch names (a launch configuration cannot set them),
725
739
  are removed from a server's environment, and are stripped from the tick's
726
740
  children like every reserved name. In process, `io.cgroup`, `io.platform`,
727
- `io.invocationId` and `io.systemToolDirs` do the same for
728
- `ensureOatsTmuxSession`.
741
+ `io.invocationId`, `io.systemdBooted` and `io.systemToolDirs` do the same for
742
+ `ensureOatsTmuxSession`, and `agentScope` takes `io.scopeProbe` in place
743
+ of the real probe. A start given an `io` with no `scopeProbe` judges no
744
+ agent scope at all (its tmux is a test's). The one test that reaches the
745
+ host's user manager (`test/tmux-server-scope.test.mjs`, "for real") runs
746
+ only where the real probe passes, and says why it skipped otherwise.
729
747
  - A test that needs a terminal (an attached tmux client, a key press) runs
730
748
  the command in a pane of a second private server and types at that pane
731
749
  with `send-keys`; the pane's shell records the exit status
@@ -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.3.0
44
- oats.aweb: v1.31.0
43
+ oats.okf: v5.5.0
44
+ oats.aweb: v1.32.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
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.3.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.5.0** (OATS **>=0.49.0**). 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 |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.3.0
28
+ oats.okf: v5.5.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,18 +50,22 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.3.0, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.5.0, OATS >=0.49.0 remains required:
54
54
  that kernel first supports the public source-event lookup after retirement.
55
55
 
56
- **Upgrade:** pin `oats.okf: v5.3.0` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.5.0` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
- homes keep their copied provider even after a session restart. Deployments
59
- whose briefings never mentioned harvesting now get knowledge proposals at
60
- the harvest checkpoints; souls not ready for this must declare
61
- `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
62
- From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the checkpoint
63
- line in `log.md`, drops the available-memory gate, and has the proposer name
64
- each harvester (`--name`, below).
58
+ homes keep their copied provider even after a session restart; from 5.4.0, a
59
+ stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
60
+ later), and a home spawned under 4.x is refused with the remedy to retire and
61
+ respawn it. Deployments whose briefings never mentioned harvesting now get
62
+ knowledge proposals at the harvest checkpoints; souls not ready for this must
63
+ declare `knowledge: { harvest: off }`. Consultation and instance-memory upkeep
64
+ remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
65
+ checkpoint line in `log.md`, drops the available-memory gate, and has the
66
+ proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
67
+ the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
68
+ that line, so run `oats sync` to 5.5.0 before instances on 5.5.0 propose.
65
69
 
66
70
  ### Bindings document
67
71
 
@@ -191,8 +195,9 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
191
195
  home: What (one claim per concept), Why, Evidence (observations, dates,
192
196
  limits and accepted concepts cited), and optional `## Backing notes` with
193
197
  one `- notes/<file>.md` entry per note. It has exactly one line
194
- `Source: instance <name>, home <path>, soul <name>` naming the actual
195
- source, a pointer to verify rather than authority. Claim only for owned
198
+ `Source: instance <name>, home <path>, soul <name>, incarnation <createdAt>`
199
+ naming the actual source, with `createdAt` copied from its `instance.json`:
200
+ a pointer to verify rather than authority. Claim only for owned
196
201
  nodes; a lesson for a node the soul only reads is named in one line in its
197
202
  hand-back for that node's owner.
198
203
 
@@ -239,9 +244,13 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
239
244
  <harvester>`).
240
245
  3. **Capture, judge and submit.** Before the model starts, the required spawn
241
246
  hook checks the source's live record or the completed recovery named by
242
- its public retirement event. Source identity, single-incarnation history,
243
- recovery manifest and soul opt-out must agree; guessed copies and reused
244
- or ambiguous identities refuse. It atomically captures the proposal,
247
+ its public retirement event. Source identity, the named incarnation,
248
+ recovery manifest and soul opt-out must agree; guessed copies and
249
+ ambiguous identities refuse. A live source whose name was used before is
250
+ matched by its incarnation; a `Source:` line without one still works for an
251
+ unambiguous source, and on a reused name it refuses with the remedy to
252
+ propose again with the incarnation. A retired source is captured only when
253
+ it had a single known incarnation. It atomically captures the proposal,
245
254
  verified source declarations/bindings and only named notes into the
246
255
  harvester's own `harvest-source/`. The model uses that snapshot, not a later
247
256
  live-source read: retirement or recovery disposal after capture cannot
@@ -56,7 +56,7 @@
56
56
  },
57
57
  "launch-configs": {
58
58
  "type": "object",
59
- "description": "Named ways to start a harness on this host, independent of any soul (a spawn-time host choice). Selected by name at spawn or session start/restart; explicit flags override its fields. Written by `oats launch-config set|remove`.",
59
+ "description": "Named ways to start a harness on this host, independent of any soul (a spawn-time host choice). Selected by name at spawn or session start/restart; explicit flags override its fields. Written by `oats launch-config set|remove`. This machine's ~/.oats/config/launch-configs.yaml holds the same block as its one key (docs/configuration.md, This machine's launch configurations); an entry here replaces the machine's entry of the same name whole.",
60
60
  "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
61
61
  "additionalProperties": {
62
62
  "type": "object",
@@ -65,7 +65,7 @@
65
65
  "properties": {
66
66
  "harness": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness this configuration starts; it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
67
67
  "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "deprecated": true, "description": "The old name of `harness`, still read (a deprecation warning); both, disagreeing, are refused. `oats launch-config set` writes `harness`." },
68
- "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the harness's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved against the deployment directory (where this oats-local.yaml lives) when relative. Checked to exist and be executable before any start; never executed just to probe it." },
68
+ "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the harness's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved, when relative, against the directory of the file that declares it (the deployment directory, where this oats-local.yaml lives, or ~/.oats/config for this machine's file). Checked to exist and be executable before any start; never executed just to probe it." },
69
69
  "args": { "type": "array", "items": { "type": "string" }, "description": "Extra arguments, each passed literally (no shell interpretation): native configuration files or profiles go here as ordinary arguments." },
70
70
  "env": {
71
71
  "type": "object",
@@ -9,15 +9,16 @@ 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.14.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.31.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.13.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.16.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.15.0` | `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) | |
19
19
  | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
20
20
  | `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
21
+ | `oats.machine` | `v0.1.1` | `oats.machine-care` | `steward`, `technician` |
21
22
 
22
23
  Each package lives in its own `awebai/oats-*` repository except
23
24
  `oats.framework`, whose payload root is `oats-package/` here. A capability id
@@ -29,7 +30,7 @@ no lock and adds nothing to an existing workspace.
29
30
  ## Find and use packages
30
31
 
31
32
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.3.0`); `oats sync` resolves it through the
33
+ `packages:` map (`oats.okf: v5.5.0`); `oats sync` resolves it through the
33
34
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
35
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
36
  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.3.0 # bare version → the official catalog
47
+ oats.okf: v5.5.0 # 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.3.0`, `5.3.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.5.0`, `5.5.0`, `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.3.0` or `oats-framework/v1.14.1`) and the payload path. An id
54
+ convention (`v5.5.0` or `oats-framework/v1.16.1`) 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.14.1
78
- oats.okf: v5.3.0
79
- oats.aweb: v1.31.0
77
+ oats.framework: v1.16.1
78
+ oats.okf: v5.5.0
79
+ oats.aweb: v1.32.0
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.3.0 ✓ (@ 79befeaf)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.5.0 ✓ (@ 4817c74e)
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.31.0 # a catalog version
137
+ oats package add oats.aweb v1.32.0 # 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.3.0",
164
- "commit": "79befeaf98e04a5a46896ddad8ac3333ee90bce3",
163
+ "version": "5.5.0",
164
+ "commit": "4817c74ede1e1b578e5a78759862964ea077ded1",
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.3.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.14.1", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.14.1`
362
- resolves to tag `oats-framework/v1.14.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.1`
362
+ resolves to tag `oats-framework/v1.16.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.