@awebai/oats 0.57.1 → 0.59.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 (61) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +2 -1
  3. package/docs/desktop-cli-api.md +105 -17
  4. package/docs/desktop.md +30 -3
  5. package/docs/execution-targets.md +15 -0
  6. package/docs/implementation.md +2 -0
  7. package/docs/integrations.md +2 -2
  8. package/docs/knowledge.md +4 -4
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +14 -14
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/release-notes/v0.59.0.md +288 -0
  13. package/docs/servers.md +4 -1
  14. package/docs/souls-and-instances.md +30 -0
  15. package/docs/tui.md +653 -117
  16. package/docs/workspaces.md +2 -2
  17. package/lib/core.mjs +227 -46
  18. package/lib/read-ahead-worker.mjs +119 -0
  19. package/lib/read-ahead.mjs +115 -0
  20. package/lib/retire-state.mjs +33 -0
  21. package/lib/servers.mjs +9 -1
  22. package/lib/session-input.mjs +14 -4
  23. package/package-catalog.json +3 -3
  24. package/package.json +1 -1
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +3 -0
  28. package/packages/client/instance-acts.mjs +23 -8
  29. package/packages/client/instance-presentation.mjs +3 -2
  30. package/packages/client/instance-tree.mjs +84 -39
  31. package/packages/client/lifecycle-confirmation.mjs +9 -3
  32. package/packages/client/panel-views.mjs +1 -1
  33. package/packages/client/remote-roster.mjs +4 -1
  34. package/packages/client/retire-in-flight.mjs +65 -0
  35. package/packages/client/retire-state.mjs +30 -0
  36. package/packages/client/spawn-apply-cli.mjs +8 -2
  37. package/packages/client/spawn-apply.mjs +20 -7
  38. package/packages/client/spawn-preview-cli.mjs +2 -1
  39. package/packages/client/spawn-preview.mjs +30 -18
  40. package/packages/record/lib/directory-identity.mjs +14 -0
  41. package/packages/record/lib/native-history.mjs +6 -5
  42. package/packages/tui/README.md +23 -10
  43. package/packages/tui/lib/actions.mjs +63 -5
  44. package/packages/tui/lib/client.mjs +12 -1
  45. package/packages/tui/lib/config.mjs +7 -2
  46. package/packages/tui/lib/main.mjs +315 -82
  47. package/packages/tui/lib/model.mjs +523 -56
  48. package/packages/tui/lib/panel.mjs +519 -144
  49. package/packages/tui/lib/read.mjs +52 -26
  50. package/packages/tui/lib/store.mjs +908 -65
  51. package/packages/tui/lib/term/keys.mjs +9 -2
  52. package/packages/tui/lib/term/text.mjs +4 -0
  53. package/packages/tui/lib/term/through.mjs +12 -1
  54. package/packages/tui/lib/views/frame.mjs +394 -95
  55. package/packages/tui/lib/views/help.mjs +54 -13
  56. package/packages/tui/lib/views/instances.mjs +43 -25
  57. package/packages/tui/lib/views/palette.mjs +61 -0
  58. package/packages/tui/lib/views/souls.mjs +268 -0
  59. package/packages/tui/lib/views/spawn.mjs +299 -0
  60. package/packages/tui/lib/views/split.mjs +29 -0
  61. package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs CHANGED
@@ -104,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
104
104
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
105
105
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
106
106
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
107
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key"];
107
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size"];
108
108
  /** Commands `--server <id>` runs on a registered server. */
109
109
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
110
110
  const flag = (name) => {
@@ -1484,16 +1484,24 @@ function sayReadNotices() {
1484
1484
  for (const notice of readSession?.notices.splice(0) ?? []) process.stderr.write(`oats: warning: ${notice}\n`);
1485
1485
  }
1486
1486
  /** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
1487
- * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
1488
- const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, trigger poll, and the read forms of teams and soul teams";
1487
+ * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
1488
+ * Write verbs refuse it: a writer acting on a reused observation could persist a fact the workspace no
1489
+ * longer holds. A preview-bound spawn apply is the exception: its fence (--expect-decision) binds it to
1490
+ * the decision the operator confirmed, so a reused head applies nothing beyond that decision. */
1491
+ const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, spawn --expect-decision <revision>, trigger poll, and the read forms of teams and soul teams";
1489
1492
  function maxAgeRefusal(command, head) {
1490
1493
  const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
1491
- const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
1494
+ const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs and a preview-bound spawn apply reuse observations (${MAX_AGE_READS})`;
1492
1495
  if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
1493
1496
  switch (command) {
1494
1497
  case "status": case "souls": case "capabilities": case "inspect": return null;
1495
- // A preview reads (feature spawn-preview-max-age); an apply always observes live.
1496
- case "spawn": return head.includes("--preview") ? null : refuse("spawn");
1498
+ // A preview reads (feature spawn-preview-max-age); an apply only when a confirmed decision binds it
1499
+ // (feature spawn-apply-max-age), with a value as spawn reads it: a bare --expect-decision binds nothing.
1500
+ case "spawn": {
1501
+ const expected = flag("expect-decision");
1502
+ if (head.includes("--preview") || (expected !== undefined && expected !== true)) return null;
1503
+ return "--max-age is not accepted by `oats spawn` without --expect-decision: a spawn apply reuses observations only with --expect-decision <revision>, which binds it to the decision a preview showed";
1504
+ }
1497
1505
  case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
1498
1506
  case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
1499
1507
  // `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
@@ -2686,8 +2694,8 @@ async function status() {
2686
2694
  const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
2687
2695
  /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
2688
2696
  * `--instance` is refused by a local spawn (with its replacement) but still travels to an older
2689
- * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview: the
2690
- * dispatch allow-list (maxAgeRefusal) refuses it on an apply. */
2697
+ * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2698
+ * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2691
2699
  const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
2692
2700
  const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
2693
2701
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
@@ -4803,7 +4811,8 @@ Usage:
4803
4811
  instance.json providers.<capability>)
4804
4812
  [--preview [--max-age <s>]] decide everything, create nothing; the JSON's
4805
4813
  decision binds an apply (--expect-decision <rev>);
4806
- --max-age reuses recent heads (preview only)
4814
+ --max-age reuses recent heads, on a preview and
4815
+ on an apply bound by --expect-decision only
4807
4816
  oats retire <instance> [--force] retire an instance (window, hooks,
4808
4817
  [--self] worktree, home); --self = retire the
4809
4818
  [--keep-dir] [--json] CALLING instance: the window dies, then
@@ -4981,9 +4990,13 @@ Observation reuse (feature observe-max-age):
4981
4990
  remote again; the JSON
4982
4991
  then carries observation { observedAt (the oldest
4983
4992
  head used), reused, localRevision (a digest of
4984
- the local configuration read) }. Refused
4993
+ the local configuration read) }. A spawn apply
4994
+ bound by --expect-decision takes it too (feature
4995
+ spawn-apply-max-age): its decision fence holds,
4996
+ and its JSON carries no observation. Refused
4985
4997
  (E_BAD_ARGS) by every other command, an edit form,
4986
- a spawn apply, and with --server
4998
+ a spawn apply without --expect-decision, and with
4999
+ --server
4987
5000
 
4988
5001
  Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
4989
5002
  }
@@ -611,5 +611,6 @@ the bounded parsed-read cache and the observations `--max-age` reuses; all of
611
611
  it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
612
612
  catalog file. The read verbs (`status`, `workspace status`, `souls`,
613
613
  `capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
614
- `spawn --preview`) take `--max-age <seconds>` to reuse a remote head observed that recently
614
+ `spawn --preview`), and a spawn apply bound by `--expect-decision`, take
615
+ `--max-age <seconds>` to reuse a remote head observed that recently
615
616
  ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).
@@ -45,7 +45,8 @@ see the [official catalog](official-catalog.md) for current pins.
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
46
  "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
47
  "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
- "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"],
48
+ "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
49
+ "status-retire-state","session-inspect-size"],
49
50
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
50
51
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
51
52
  "capabilityShowApi":1}
@@ -122,6 +123,7 @@ see the [official catalog](official-catalog.md) for current pins.
122
123
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
123
124
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
124
125
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
126
+ | `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
125
127
  | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
126
128
  | `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
127
129
  | `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
@@ -131,6 +133,8 @@ see the [official catalog](official-catalog.md) for current pins.
131
133
  | `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
132
134
  | `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
133
135
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
136
+ | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
137
+ | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
134
138
 
135
139
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
136
140
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -308,6 +312,7 @@ it and answer live, without the block.
308
312
  oats status | workspace status | souls | capabilities | inspect --soul|--home
309
313
  | teams | soul teams <soul> … --max-age <seconds> --json
310
314
  oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
315
+ oats spawn <soul> … --expect-decision <revision> --max-age <seconds> --json (feature spawn-apply-max-age)
311
316
  oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
312
317
  oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
313
318
  ```
@@ -327,10 +332,13 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
327
332
  - **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
328
333
  preview's `result` gains the same block, so you can say "as of
329
334
  `<observedAt>`". The `decision` covers the heads the preview used, reused
330
- or live: a reused head the member has since moved from makes the apply
331
- (which always observes live) refuse `E_DECISION_STALE`, and the apply
332
- records the head it observed, so the next preview under `--max-age` shows
333
- it with a new `decision.revision`. The apply itself refuses the flag.
335
+ or live: a reused head the member has since moved from makes an apply
336
+ that observes live refuse `E_DECISION_STALE`, and the apply records the
337
+ head it observed, so the next preview under `--max-age` shows it with a new
338
+ `decision.revision`. The preview-bound apply takes the flag from
339
+ `spawn-apply-max-age` (OATS 0.58.0): with `--expect-decision`, it reuses
340
+ heads as the preview does, and its decision fence is unchanged
341
+ ([Apply](#apply)). Its answer carries no block.
334
342
  - **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
335
343
  piece of local configuration the kernel read for this answer:
336
344
  `oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
@@ -361,18 +369,25 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
361
369
  spelling of the same repository (ssh vs https) or for a different ref; its
362
370
  commit can no longer be fetched. Each is observed live, as without the flag.
363
371
  A live observation that fails is the usual error, never an older head.
364
- - **Refusals:** every other command, a spawn apply (with or without
365
- `--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`)
372
+ - **Refusals:** every other command, every edit form (`teams add|remove|default`)
366
373
  and any `--server`
367
374
  invocation refuse the flag before reading or writing anything (the removed
368
375
  `soul teams --add|--remove|--default|--clear-default` answer their own
369
376
  `E_BAD_ARGS` first), with
370
377
  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
371
- verbs reuse observations (status, workspace status, souls, capabilities,
372
- capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
373
- and the read forms of teams and soul teams)" and,
378
+ verbs and a preview-bound spawn apply reuse observations (status, workspace
379
+ status, souls, capabilities, capabilities show, inspect --soul|--home,
380
+ spawn --preview, spawn --expect-decision <revision>, trigger poll, and the
381
+ read forms of teams and soul teams)" and,
374
382
  with `--server`, "--max-age cannot be combined with --server: observation
375
- reuse is local to this machine".
383
+ reuse is local to this machine". A spawn apply without `--expect-decision`
384
+ (or with no value after it) refuses it with `E_BAD_ARGS` "--max-age is not
385
+ accepted by \`oats spawn\` without --expect-decision: a spawn apply reuses
386
+ observations only with --expect-decision <revision>, which binds it to the
387
+ decision a preview showed". Write verbs refuse the flag because a writer
388
+ acting on a reused observation could persist a fact the workspace no longer
389
+ holds; a preview-bound apply is the exception because its fence binds it to
390
+ the decision the operator confirmed.
376
391
  A capability command's argv (`oats <namespace> …`) is its provider's: the
377
392
  kernel neither reads nor refuses `--max-age` there. The same holds for
378
393
  `capture`, `recall`, `setup` and `experimental`, which parse their own argv:
@@ -2316,10 +2331,11 @@ it to a temporary copy (`soulFetched: true`).
2316
2331
  localRevision}`, shaped exactly as the read verbs' block; without it the
2317
2332
  preview is exactly as before, and no other field changes shape.
2318
2333
  - `decision.revision` covers the heads the preview used, reused or live.
2319
- Apply never reuses (it refuses `--max-age`): a head that moved since the
2320
- reused observation refuses `E_DECISION_STALE`, and the apply records what
2321
- it observed, so re-preview under `--max-age` to get the new head and
2322
- revision.
2334
+ An apply without `--max-age` (or with `--max-age 0`) observes live: a head
2335
+ that moved since the reused observation refuses `E_DECISION_STALE`, and the
2336
+ apply records what it observed, so re-preview under `--max-age` to get the
2337
+ new head and revision. An apply with `--expect-decision` may reuse heads
2338
+ too (feature `spawn-apply-max-age`, [Apply](#apply)).
2323
2339
 
2324
2340
  **Provider settings.**
2325
2341
  - `providers` is the `--provider` map as typed.
@@ -2363,6 +2379,16 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
2363
2379
  `E_INSTANCE_NAME_TAKEN` (for `--name`) or `E_PLACEMENT_TAKEN`.
2364
2380
  - A refused child spawn appends `child-spawn-refused` to the parent's log (on
2365
2381
  apply only).
2382
+ - `--max-age <s>` with `--expect-decision <revision>` (feature
2383
+ `spawn-apply-max-age`, OATS 0.58.0) reuses member heads this machine
2384
+ observed at most `<s>` seconds ago, exactly as the preview does (the same
2385
+ values and fallbacks to a live observation), so an apply right after its
2386
+ preview asks no remote again. The decision is computed from those heads, and
2387
+ one that differs from `<revision>` is `E_DECISION_STALE`, as without the
2388
+ flag. The answer (success, replay, every refusal) has no `observation`
2389
+ block: the preview already gave its "as of".
2390
+ Without `--expect-decision` the flag is `E_BAD_ARGS`
2391
+ ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
2366
2392
 
2367
2393
  **Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
2368
2394
  with `--expect-decision` records the key and decision in `instance.json`.
@@ -2783,8 +2809,9 @@ its absence.
2783
2809
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2784
2810
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2785
2811
  in the row),
2786
- `identity` when a provider recorded one, `rollbackIncomplete` and
2787
- `retirePending` when present, and the Desktop facts below.
2812
+ `identity` when a provider recorded one, `rollbackIncomplete`,
2813
+ `retirePending` and [`retire`](#row-retire) when present, and the Desktop
2814
+ facts below.
2788
2815
  - <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
2789
2816
  read** (OATS 0.52.0) is listed like every other, and one such home never
2790
2817
  fails the listing. Its row has the fields of a home with no `instance.json`
@@ -2823,6 +2850,55 @@ its absence.
2823
2850
  shell or a retained dead pane keeps, so a row with a claim is checked
2824
2851
  against its session (as `oats session inspect` observes it) and reads
2825
2852
  `null` unless a harness runs there.
2853
+ - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
2854
+ 0.59.0): `{state, since, self, code?, message?}` while a retire of the home
2855
+ is running, scheduled or owed; absent otherwise, and from older kernels.
2856
+ `retirePending` keeps its meaning (the self-retire marker is there) and is
2857
+ not replaced. Status only reads: it takes no claim, removes no file and
2858
+ signals no process. `self` is `true` when the self-retire marker
2859
+ (`.oats-retire-pending-<instance>.json`, [souls-and-instances.md](souls-and-instances.md#self-retire-not-completed))
2860
+ is beside the home, whatever the claim says, and `false` for a retire
2861
+ another process runs (an `oats retire` holding the home's claim). The
2862
+ marker is read first:
2863
+
2864
+ | Beside the home | `state` | `self` | `since` |
2865
+ |---|---|---|---|
2866
+ | the marker, and the result file `.oats-retired-<instance>.json` with `ok: false` | `failed`, with `code` and `message` | `true` | the result's `completedAt`, else the marker's `requestedAt` |
2867
+ | the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
2868
+ | the marker, no failed result, the completion's liveness cannot be read, or the marker names no completion process | `unknown` | `true` | the marker's `requestedAt` |
2869
+ | the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
2870
+ | a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
2871
+ | no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
2872
+ | no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
2873
+ | no marker; the claim's holder gone, a stop's claim, or no claim | absent | | |
2874
+
2875
+ A result with `ok: true` beside a marker still there reads as no result.
2876
+ `code` is the result's `error.code` when it matches `^E_[A-Z0-9_]+$`, and
2877
+ is left out otherwise (the state stays `failed`); `message` is its
2878
+ `error.message` on one line and cut to a retire's one-line reason (at most
2879
+ 2048 UTF-16 code units, a cut ending in `…`), left out when empty: each is
2880
+ a string or absent, never `null`, and only on `failed`. `since` is always
2881
+ there, an instant as `toISOString()` writes it: the time in the table when
2882
+ it is one, else the marker file's modification time (the claim file's for
2883
+ a claim); a `retire` whose time cannot be read at all is not given. A
2884
+ failed retire that owes the home nothing leaves no marker: its row carries
2885
+ no `retire`, and its agent row's `retireFailures[]` holds the outcome, as
2886
+ before. A retire that was killed while it held the claim leaves a claim
2887
+ whose holder is gone, which reads absent.
2888
+
2889
+ **How the clients read it** (`packages/client/retire-state.mjs`): `since`
2890
+ a string, `self` a boolean, `code` an `E_…` code and `message` a string,
2891
+ each optional field absent or a string, never `null`. Any other field is
2892
+ dropped. A value with any field out of this shape is dropped whole, never
2893
+ repaired, and the row reads as if it had none; it never fails the roster.
2894
+ `retirePending` is read on its own and kept as reported. The Desktop and
2895
+ `oats tui` read `running` and `unknown` as **Retiring…**, `failed` as
2896
+ **Retire failed** (its `message` and `code` shown as OATS's words, through
2897
+ the display filter) and `interrupted` as **Retire didn't finish**. A row
2898
+ with `retirePending` and no `retire` (a kernel without the feature) reads
2899
+ **Retiring…**. `rollbackIncomplete` and `spawnInProgress` are read before
2900
+ it. A remote roster row's `retire` is read by the same rule
2901
+ ([remote rows](#remote-row-retire)).
2826
2902
  - **`modules`** becomes drift rows `{name, from, commit, current, status,
2827
2903
  reason?}` when the workspace was read. `status` is `current`, `moved` or
2828
2904
  `missing` (`reason`: `capability-absent`, `package-absent`, or the member's
@@ -2991,6 +3067,18 @@ route target:
2991
3067
  `producer`) is `null`, and an unknown `reason` or an invalid `message` is
2992
3068
  `null` inside a claim that still counts. As on a local row, the host
2993
3069
  reports a claim only for a running instance.
3070
+ - <a id="remote-row-retire"></a>**`retire`** (feature `status-retire-state`, OATS 0.59.0) is on a row only
3071
+ when the host's row has the key: a host whose kernel predates the feature,
3072
+ and a saved route the host did not list, carry none. When present it is
3073
+ passed through the [local row's](#row-retire) rule again on this side: a
3074
+ `state` that is not one of `running`, `unknown`, `failed`, `interrupted`, a
3075
+ `since` that is not a `toISOString()` instant, a `self` that is not a
3076
+ boolean, or a value that is not an object drops the key; a `code` that is
3077
+ not a kernel code, a `code` or `message` that is not a string, and a `code`
3078
+ or `message` on a state other than `failed` are left out, and `message` is
3079
+ cut to the same bound. `oats status --server
3080
+ <id> --json` relays the host's answer verbatim, `retire` included, as it
3081
+ does every other field.
2994
3082
  - **`addressable`** (0.31): `true` for every row the host reports. Routed
2995
3083
  session and lifecycle commands reach it by `--home`, or by name when the
2996
3084
  name is unique on the host ([addressing](servers.md#run-there); a shared
package/docs/desktop.md CHANGED
@@ -227,9 +227,8 @@ a spawn may run for a long time: its roster row reads **Setting up worktree…**
227
227
  until the worktree is ready, and offers no actions meanwhile. If the spawn was
228
228
  interrupted or a capability couldn't set up the worktree, the spawn was rolled
229
229
  back, and the notification says that nothing was created. A home whose spawn
230
- didn't finish its cleanup reads **Spawn didn't finish**, and one whose retire
231
- didn't finish reads **Retire didn't finish**; both offer only **Retire
232
- instance…**, which completes them. A server spawn whose worktree hooks take
230
+ didn't finish its cleanup reads **Spawn didn't finish**, and offers only
231
+ **Retire instance…**, which completes it. A server spawn whose worktree hooks take
233
232
  more than about a minute is not yet supported from the Desktop; use the CLI on
234
233
  the server. Every dropdown in the app has the
235
234
  same themed look, and its open list follows the light or dark theme.
@@ -257,6 +256,34 @@ With an OATS older than 0.52.0, after an interrupted stop the instance can be
257
256
  started and then cannot be stopped while `.oats-stop-pending.json` exists in
258
257
  its home.
259
258
 
259
+ **A retire in progress reads Retiring…, never as a failure.** An instance's
260
+ roster row reads **Retiring…** while:
261
+
262
+ - OATS reports its retire running, or cannot tell whether the process
263
+ holding the retire still runs;
264
+ - its OATS does not report a retire's state yet (no `retire` on the row)
265
+ and the instance has a retire pending;
266
+ - the Desktop's own retire of it was sent and the roster has not been read
267
+ since its answer came. A retire that OATS refused, or whose plan had
268
+ changed, runs nothing, and the row reads as the roster says at once.
269
+
270
+ A retiring row offers no Start, Stop, Restart or Open, and no inline
271
+ button. **Retire instance…** stays in the row's menu, after its usual
272
+ confirmation: OATS refuses a second retire while one runs, and when the
273
+ holder can't be read it may be the only way on.
274
+
275
+ When the retire has ended without finishing, the row says so and offers only
276
+ **Retire instance…**, which finishes it:
277
+
278
+ - **Retire failed**: a self-retire's completion recorded an error. Its
279
+ reason is OATS's own message, with its code, shown through the same
280
+ display filter as every other text from OATS (control characters and
281
+ line breaks never reach the screen, a long message is cut, a message that
282
+ looks like a secret is withheld). With a code and no message, the reason
283
+ is OATS's code, shown the same way.
284
+ - **Retire didn't finish**: a scheduled completion is gone and left no
285
+ outcome.
286
+
260
287
  ## One workspace, several machines
261
288
 
262
289
  The switcher lists each workspace once, however many deployments it has: the
@@ -349,6 +349,10 @@ than the server's checked one account and launched with another
349
349
  given the pane's `PATH` as the pane reads it, a relative entry (and an
350
350
  empty one) resolved against the pane's working directory, the home.
351
351
  The command a refusal names keeps the harness's name as declared.
352
+ The Claude probe (`claude plugin list --json`) sets `DISABLE_TELEMETRY=1`
353
+ for its own run, so Claude skips its telemetry flush at exit: that selects
354
+ no account and changes no answer, and no launch, install step or other
355
+ probe gets it.
352
356
  - **The folder-trust check only warns**: `<harness> folder trust: the
353
357
  configuration file this launch will read could not be established
354
358
  (<why, and what would make it readable>); nothing is said about its
@@ -1035,6 +1039,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
1035
1039
  harness, `shell` for a fallback shell,
1036
1040
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
1037
1041
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
1042
+ With feature `session-inspect-size` in `oats version --json`, a present
1043
+ terminal also reports `size: { cols, rows }`: positive integer window width
1044
+ and height in cells. The kernel reads tmux's `window_width` and
1045
+ `window_height` in the same call as the pane identity, so a viewer can open
1046
+ its PTY at the window's current size without constructing a tmux target.
1047
+ Split windows remain refused. `size` is absent when `present` is false,
1048
+ including a retained dead pane. Malformed dimensions are an
1049
+ `E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
1050
+ `session inspect --server <id> --home <home> --json` relays the execution
1051
+ host's size; check that host's feature list before relying on it. This is a
1052
+ snapshot: inspect again to observe a resize.
1038
1053
  A home without its session receipt is refused with
1039
1054
  `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
1040
1055
  spelling that differs from the on-disk one, the path a kernel before 0.49.0
@@ -120,7 +120,9 @@ and the rules its tests pin.
120
120
  | `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)) |
121
121
  | `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 |
122
122
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
123
+ | `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 |
123
124
  | `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 |
125
+ | `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 |
124
126
  | `servers.mjs` | routing commands to a registered server |
125
127
  | `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 |
126
128
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
@@ -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.2.0
44
- oats.aweb: v1.27.3
43
+ oats.okf: v5.2.1
44
+ oats.aweb: v1.28.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.2.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.2.1** (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.2.0
28
+ oats.okf: v5.2.1
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,10 +50,10 @@ 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.2.0, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.2.1, 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.2.0` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.2.1` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
58
  homes keep their copied provider even after a session restart. Deployments
59
59
  whose briefings never mentioned harvesting now get knowledge proposals at
@@ -9,9 +9,9 @@ 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.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
12
+ | `oats.framework` | `oats-framework/v1.12.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.28.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.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` |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.2.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.2.1`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.2.0 # bare version → the official catalog
47
+ oats.okf: v5.2.1 # 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.2.0`, `5.2.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.2.1`, `5.2.1`, `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.2.0` or `oats-framework/v1.12.0`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.12.2`) 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.12.0
78
- oats.okf: v5.2.0
79
- oats.aweb: v1.27.3
77
+ oats.framework: v1.12.2
78
+ oats.okf: v5.2.1
79
+ oats.aweb: v1.28.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.2.0 ✓ (@ 2ac86ccb)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.1 ✓ (@ 72e989b9)
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.27.3 # a catalog version
137
+ oats package add oats.aweb v1.28.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.2.0",
164
- "commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
163
+ "version": "5.2.1",
164
+ "commit": "72e989b926e8ac1b7b912785beff396d1fc41cbb",
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.2.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.2", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.12.0`
362
- resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.12.2`
362
+ resolves to tag `oats-framework/v1.12.2`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.