@awebai/oats 0.68.0 → 0.69.1

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 (72) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +147 -13
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.68.1.md +102 -0
  15. package/docs/release-notes/v0.69.0.md +658 -0
  16. package/docs/release-notes/v0.69.1.md +25 -0
  17. package/docs/servers.md +44 -5
  18. package/docs/souls-and-instances.md +11 -7
  19. package/docs/tui.md +114 -31
  20. package/docs/upgrading.md +14 -5
  21. package/docs/workspaces.md +1 -1
  22. package/lib/core.mjs +345 -89
  23. package/lib/file-pieces.mjs +49 -0
  24. package/lib/instance-events.mjs +25 -4
  25. package/lib/launch-prompt-fixtures/README.md +62 -0
  26. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  27. package/lib/launch-prompt-fixtures.mjs +49 -0
  28. package/lib/launch-prompt-resume.mjs +55 -0
  29. package/lib/login-environment.mjs +27 -9
  30. package/lib/schedule.mjs +3 -3
  31. package/lib/servers.mjs +117 -23
  32. package/lib/session-end.mjs +82 -0
  33. package/lib/session-input.mjs +43 -9
  34. package/lib/session-resume-contract.mjs +32 -0
  35. package/lib/session-resume.mjs +310 -0
  36. package/lib/session-seen.mjs +163 -0
  37. package/lib/session-viewer.mjs +147 -44
  38. package/lib/soul-composition.mjs +2 -1
  39. package/lib/start-env.mjs +110 -0
  40. package/lib/tmux-server-scope.mjs +139 -14
  41. package/lib/workspace.mjs +38 -4
  42. package/package-catalog.json +10 -4
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +9 -0
  45. package/packages/client/cli-locator.mjs +3 -2
  46. package/packages/client/deployment-data.mjs +7 -0
  47. package/packages/client/deployment-panel.mjs +3 -0
  48. package/packages/client/file-output-exec.mjs +98 -0
  49. package/packages/client/instance-display-name.mjs +18 -0
  50. package/packages/client/launch-prompt-outcome.mjs +25 -13
  51. package/packages/client/own-codes.mjs +2 -0
  52. package/packages/client/session-attach.mjs +35 -5
  53. package/packages/client/session-resume-cli.mjs +64 -0
  54. package/packages/client/session-resume-trigger.mjs +167 -0
  55. package/packages/client/session-resume.mjs +332 -0
  56. package/packages/client/tmux-status.mjs +30 -7
  57. package/packages/client/waiting-on-you.mjs +11 -4
  58. package/packages/client/workspace-step.mjs +17 -5
  59. package/packages/record/lib/last-conversation.mjs +123 -0
  60. package/packages/record/lib/session-roots.mjs +10 -1
  61. package/packages/tui/README.md +1 -1
  62. package/packages/tui/lib/client.mjs +2 -1
  63. package/packages/tui/lib/main.mjs +5 -3
  64. package/packages/tui/lib/model.mjs +57 -15
  65. package/packages/tui/lib/store.mjs +8 -7
  66. package/packages/tui/lib/term/text.mjs +12 -9
  67. package/packages/tui/lib/views/capabilities.mjs +6 -6
  68. package/packages/tui/lib/views/frame.mjs +72 -7
  69. package/packages/tui/lib/views/help.mjs +9 -4
  70. package/packages/tui/lib/views/instances.mjs +46 -29
  71. package/packages/tui/lib/views/souls.mjs +9 -8
  72. 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;
@@ -107,6 +107,7 @@ and the rules its tests pin.
107
107
  | `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
108
  | `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
109
109
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
110
+ | `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); 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
111
  | `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
112
  | `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
113
  | `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 |
@@ -120,7 +121,7 @@ and the rules its tests pin.
120
121
  | `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
122
  | `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
123
  | `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 |
124
+ | `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
125
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
125
126
  | `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
127
  | `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 +129,15 @@ and the rules its tests pin.
128
129
  | `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
130
  | `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
131
  | `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 |
132
+ | `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` |
133
+ | `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
134
  | `servers.mjs` | routing commands to a registered server |
133
135
  | `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
136
  | `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
137
  | `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
138
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
137
139
  | `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 |
140
+ | `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
141
  | `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
142
  | `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
143
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
@@ -710,22 +713,36 @@ and acts on every existing session through its recorded socket
710
713
  - A server a test starts is killed by its socket, never by name and never
711
714
  with a bare `tmux kill-server`.
712
715
  - 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
716
+ inside a systemd service or a user-manager scope starts the server through
717
+ the system's own `systemd-run`, and every launch on the unified hierarchy
718
+ probes it for the agent's scope, found by absolute path, not on `PATH`, so
719
+ a fake-free `PATH` does not stop it. The fixtures (`isolateSessionEnvironment`,
720
+ `fixtureEnv`) therefore set `OATS_TEST_CGROUP` to a scope outside the user
721
+ manager, never a service, whatever runs the suite, and
722
+ `OATS_TEST_SYSTEM_TOOL_DIRS` to the fixture's own `fixture-system-tools`:
723
+ the host's `env` and `true`, and a `systemd-run` that runs what follows
724
+ `--` in its own process. So every fixture launch is wrapped, and passes
725
+ through that fake, never the host's user manager. A test of a scope sets
726
+ its own. Three test-only seams select where the kernel judges itself and
718
727
  which `systemd-run` it runs:
719
- - `OATS_TEST_CGROUP`: the text of a `/proc/self/cgroup`, judged as Linux;
728
+ - `OATS_TEST_CGROUP`: the text of a `/proc/self/cgroup`, judged as Linux
729
+ booted with systemd;
730
+ - `OATS_TEST_SYSTEMD_BOOTED`: `1` or `0`, in place of whether
731
+ `/run/systemd/system` is a directory (sd_booted): `0` is a Linux host
732
+ without systemd, where no agent scope is judged;
720
733
  - `OATS_TEST_SYSTEM_TOOL_DIRS`: absolute directories separated by `:`, in
721
734
  place of `/usr/bin:/bin`. Any other value means no system tool, never a
722
735
  `PATH` lookup.
723
736
 
724
- Both are reserved launch names (a launch configuration cannot set them),
737
+ All three are reserved launch names (a launch configuration cannot set them),
725
738
  are removed from a server's environment, and are stripped from the tick's
726
739
  children like every reserved name. In process, `io.cgroup`, `io.platform`,
727
- `io.invocationId` and `io.systemToolDirs` do the same for
728
- `ensureOatsTmuxSession`.
740
+ `io.invocationId`, `io.systemdBooted` and `io.systemToolDirs` do the same for
741
+ `ensureOatsTmuxSession`, and `agentScope` takes `io.scopeProbe` in place
742
+ of the real probe. A start given an `io` with no `scopeProbe` judges no
743
+ agent scope at all (its tmux is a test's). The one test that reaches the
744
+ host's user manager (`test/tmux-server-scope.test.mjs`, "for real") runs
745
+ only where the real probe passes, and says why it skipped otherwise.
729
746
  - A test that needs a terminal (an attached tmux client, a key press) runs
730
747
  the command in a pane of a second private server and types at that pane
731
748
  with `send-keys`; the pane's shell records the exit status
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.3.0
44
- oats.aweb: v1.31.0
44
+ oats.aweb: v1.32.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -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` |
12
+ | `oats.framework` | `oats-framework/v1.15.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
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.11.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
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
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.3.0`, `5.3.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.3.0` or `oats-framework/v1.15.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
77
+ oats.framework: v1.15.1
78
78
  oats.okf: v5.3.0
79
- oats.aweb: v1.31.0
79
+ oats.aweb: v1.32.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -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
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
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" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.15.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.15.1`
362
+ resolves to tag `oats-framework/v1.15.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,102 @@
1
+ # OATS 0.68.1
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **From 0.68.0:** [the steps](../upgrading.md#the-steps), the Desktop
8
+ first and the CLI second. The 0.68.1 Desktop accepts OATS CLIs
9
+ `>=0.26.0 <0.69.0`. The official catalog pins oats.engineering 1.13.0
10
+ (Provider updates, below) in place of 0.68.0's 1.11.0.
11
+
12
+ - **From 0.67 or earlier:** do [0.68.0's Upgrade steps](v0.68.0.md#upgrade)
13
+ first: a 0.67 Desktop refuses a 0.68 CLI. From 0.66 or earlier, do 0.67.0's
14
+ too, and the older ones [Upgrading](../upgrading.md#coming-from-an-older-version)
15
+ names.
16
+
17
+ ## Added
18
+
19
+ - **Desktop: a resizable sidebar, a little wider by default.** The sidebar
20
+ is 288px wide (it was 264px), and its right edge is a handle: drag it
21
+ between 240px and 480px (at most 45% of the window, so the terminals keep
22
+ the rest), or Tab to it and use ← and → (Shift for bigger steps), Home and
23
+ End. A double-click on it, Enter, or the palette's **Sidebar: reset width**
24
+ put it back to 288px. The width is remembered on this computer and kept
25
+ while the sidebar is hidden. Terminals refit as it moves and tell their
26
+ programs the new size once, at the end.
27
+ ([desktop.md](../desktop.md#workspaces),
28
+ [desktop-keyboard.md](../../packages/desktop/docs/desktop-keyboard.md#keyboard-audit))
29
+
30
+ ## Changed
31
+
32
+ - **Desktop: the sidebar shows an instance's name as words.** Each `-` is a
33
+ space, and the first letter is a capital: `oats-expert-maintainer-lanes`
34
+ reads "Oats expert maintainer lanes", on nested rows and on a spawn's
35
+ pending row too. Only the row's label changes. The hover card, the command
36
+ palette's search, terminal tabs, a screen reader and the CLI keep the real
37
+ name ([OATS Desktop](../desktop.md#the-sidebars-instance-tree)).
38
+
39
+ - **Desktop: an instance that needs input shows it on its dot.** In the
40
+ sidebar's instance tree, the row's dot becomes the needs-input mark, the
41
+ amber disc with a "!" that the terminal tab and the workspace list already
42
+ show, and the row's "Needs input" label is gone: its second line keeps the
43
+ soul and the repository. A screen reader still hears "Needs input" after the
44
+ name, the hover card keeps the reason and how long it has waited, and a
45
+ collapsed parent still shows "! N below" for the rows it hides
46
+ ([OATS Desktop](../desktop.md#the-sidebars-instance-tree)).
47
+ - **Desktop: yellow now means needs input only.** Unknown state has its own
48
+ look, a grey ring with a small grey centre, in the sidebar, the command
49
+ palette, Quick Open, the overview and a team's member list. The keyboard
50
+ shortcut clash dot, the Workspace page's Setup and Teams attention dot and
51
+ the Automations problem dots are red.
52
+
53
+ - **TUI: an instance's row shows its name as words**, as the Desktop's
54
+ sidebar does: each `-` a space and the first letter upper-case, so
55
+ `oats-expert-lead` reads `Oats expert lead`, nested rows included. Only
56
+ the row changes: the detail, the filter (`oats-expert` still finds the
57
+ row), the palette, the tabs, the confirmations and everything sent to
58
+ OATS keep the instance's name, and a row is cut as before. See
59
+ [What it shows](../tui.md#what-it-shows).
60
+
61
+ - **TUI: an instance that needs input shows it by its mark, not a tag in
62
+ words.** Its row draws `!` in place of its state mark, bold, in reverse
63
+ video in yellow (not reversed on the selected row, a gap in the
64
+ selection's bar), whatever its state and its colour; the row's
65
+ `Needs input` tag is gone, and its name is cut as before. Under
66
+ `NO_COLOR` the reverse video and the `!` carry it, and in ASCII it is the
67
+ same `!`. A folded row keeps its `N below` tag for the waiting instances
68
+ it folds away, whether or not it waits itself. The detail still says it
69
+ in words, with the reason and how long it has waited, and the help lists
70
+ the mark. Yellow now means needs input only: a state unknown (`?`) is
71
+ dim in the terminal's foreground, and the warnings of the Souls and
72
+ Capabilities views (a failed read, `Can't spawn here`, `· N on an older
73
+ version`) are bold red, and a `sand` instance or soul is in the
74
+ terminal's foreground colour.
75
+ ([tui.md](../tui.md#what-it-shows))
76
+
77
+ ## Provider updates
78
+
79
+ - **oats.engineering 1.13.0: one release lane, and one lane per project.**
80
+ The catalog and this workspace pin `oats.engineering: v1.13.0` (floor
81
+ unchanged). It carries 1.12.0 and 1.13.0 together, and supersedes 1.11.0's
82
+ "a maintainer the map doesn't name asks for a lane before it acts":
83
+ - **The release lane** does the final review and the merge of what the
84
+ other lanes hand it, owns and tags every release, and keeps the lane map.
85
+ - **Every other lane is a project lane.** A maintainer defines one, or
86
+ claims one with no active maintainer, when it holds none or its human
87
+ asks, and adds itself to the map; several maintainers may share a lane.
88
+ A project lane reviews its own work and hands each approved PR to the
89
+ release lane. The map may record another arrangement for a lane, agreed
90
+ with the release lane.
91
+ - **A human's high-level picture is the maintainer's intake.** The
92
+ maintainer writes the brief and launches the expert, which writes the
93
+ spec and plan. A lead launched for work in a lane the maintainer holds is
94
+ its child (`--parent`); work for another lane goes to that lane's
95
+ maintainer, or to a maintainer spawned for it, and the human is told who
96
+ has it.
97
+ - Also taught: splitting a lane, the owning lane's second read on a
98
+ cross-lane PR, confirming a relayed human decision directly, cleaning up
99
+ a cancelled effort, and a failed publication (re-run from the same tag).
100
+ - **Upgrade:** `oats sync` locks it; new spawns get it, or a stopped home
101
+ moved with `oats instance upgrade`. Peer maintainers record their lanes,
102
+ and any non-default arrangement, in their lane map.