@awebai/oats 0.62.0 → 0.64.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 (40) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +58 -23
  3. package/docs/desktop-cli-api.md +73 -3
  4. package/docs/execution-targets.md +45 -2
  5. package/docs/first-team.md +6 -0
  6. package/docs/official-catalog.md +1 -1
  7. package/docs/packages.md +5 -5
  8. package/docs/release-lane.md +13 -0
  9. package/docs/release-notes/v0.63.0.md +135 -0
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/souls-and-instances.md +32 -7
  12. package/docs/upgrading.md +6 -3
  13. package/docs/workspaces.md +1 -1
  14. package/lib/core.mjs +100 -28
  15. package/lib/session-input.mjs +12 -2
  16. package/lib/tree-copy.mjs +188 -7
  17. package/package-catalog.json +1 -1
  18. package/package.json +1 -1
  19. package/packages/client/cli-locator.mjs +2 -2
  20. package/packages/client/instance-tree.mjs +53 -3
  21. package/packages/client/roster-sections.mjs +22 -6
  22. package/packages/record/bin/capture.mjs +59 -17
  23. package/packages/record/bin/setup.mjs +2 -1
  24. package/packages/record/docs/capture-service.md +89 -5
  25. package/packages/record/lib/capture-command-operation.mjs +2 -2
  26. package/packages/record/lib/capture-command-output.mjs +3 -2
  27. package/packages/record/lib/capture-command.mjs +20 -3
  28. package/packages/record/lib/capture-hook-runner.mjs +1 -1
  29. package/packages/record/lib/capture-index-reset.mjs +1 -0
  30. package/packages/record/lib/capture-lock.mjs +67 -33
  31. package/packages/record/lib/capture-pass.mjs +22 -8
  32. package/packages/record/lib/capture-run.mjs +1 -1
  33. package/packages/record/lib/capture-service-runner.mjs +1 -1
  34. package/packages/record/lib/capture-supervisor.mjs +24 -5
  35. package/packages/record/lib/capture-work-session.mjs +7 -4
  36. package/packages/record/lib/capture-worker.mjs +20 -4
  37. package/packages/record/lib/derived-state.mjs +30 -2
  38. package/packages/record/lib/index-db.mjs +118 -49
  39. package/packages/record/lib/store.mjs +13 -6
  40. package/skills/oats-getting-started/SKILL.md +438 -170
package/README.md CHANGED
@@ -25,6 +25,19 @@ For example, a kernel expert, a UX expert and a customer-support expert can shar
25
25
 
26
26
  The [official catalog](docs/official-catalog.md) is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
27
27
 
28
+ ## Start here
29
+
30
+ Ask your coding agent (Claude Code, Codex, pi or any other) to download the `oats-getting-started` skill verbatim and follow it:
31
+
32
+ ```bash
33
+ curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
34
+ ```
35
+
36
+ - **It asks first:** your project, its repositories and the knowledge tools you use.
37
+ - **It installs OATS and OATS Desktop,** then creates your workspace with its own setup expert, or joins this machine to an existing workspace.
38
+ - **It hands over to that setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
39
+ - **Download it, don't web-fetch it:** a tool that summarises pages would lose its exact commands.
40
+
28
41
  ## Why OATS
29
42
 
30
43
  OATS grew from a practical need: we wanted control over our agent setups—not just which model answered a prompt, but also:
@@ -212,7 +225,7 @@ oats onboard ~/acme --workspace git:github.com/acme/agents # this machine's de
212
225
  oats spawn <soul> --task "First concrete task"
213
226
  ```
214
227
 
215
- The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
228
+ [Start here](#start-here) does all of this for you. The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
216
229
 
217
230
  Further documentation:
218
231
 
package/bin/oats.mjs CHANGED
@@ -105,7 +105,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
105
105
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
106
106
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
107
107
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
108
- 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
+ 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", "session-inspect-running"];
109
109
  /** Commands `--server <id>` runs on a registered server. */
110
110
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
111
111
  const flag = (name) => {
@@ -2839,9 +2839,8 @@ async function spawnCmd() {
2839
2839
  // Lineage is explicit: --relation child|sibling|parent|unrelated anchors the new
2840
2840
  // instance to --relative-to <instance>. --parent X is sugar for
2841
2841
  // --relative-to X --relation child (agents spawning sub-agents pass their own
2842
- // name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn is
2843
- // operator-origin and lands top-level — ambient env vars in the shell are
2844
- // never treated as parentage.
2842
+ // name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn lands
2843
+ // top-level; caller attribution never supplies parentage.
2845
2844
  const parent = flag("parent");
2846
2845
  if (parent !== undefined && (parent === true || !String(parent).trim())) bail("E_BAD_ARGS", "--parent needs an instance name");
2847
2846
  let relation = flag("relation");
@@ -4829,30 +4828,66 @@ Usage:
4829
4828
  spawn hooks); --model replaces the recorded model
4830
4829
  for this and later starts; a live harness is refused
4831
4830
  oats spawn <agent> [--task <text> | --task-file <f>] spawn an instance (tmux; --no-launch
4832
- [--purpose <slug>] [--repo <r>] = scaffold only); the agent is a workspace
4833
- [--parent <instance>] soul or a capability-defined agent
4834
- [--relation child|sibling|parent|unrelated] --relation + --relative-to anchor the
4835
- [--relative-to <instance>] new instance to an existing one; --parent X
4836
- [--relative-root <agents-root>] disambiguates same-named team anchors
4837
- [--work worktree|checkout|attached|workspace|directory] = sugar for --relative-to X --relation
4838
- [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] child (default: unrelated, top-level)
4839
- [--no-launch] [--json] without --launch-config/--harness the launch is the
4840
- soul's preference: oats-local.yaml souls.launch.<soul>,
4841
- then souls.launch."*", then the soul's launch:, then pi
4842
- with team: declared, unknown souls
4843
- resolve across the team scope's repos
4831
+ [--purpose <slug> | --name <slug>] = scaffold only); the agent is a workspace
4832
+ [--repo <path>] soul or a capability-defined agent
4833
+ --purpose derives <agent>-<purpose>;
4834
+ --name is exact (no prefix), unused in the
4835
+ deployment, a slug and not a soul name
4836
+ [--dir <scope>] [--agents-root <abs>] deployment scope; --agents-root must match
4837
+ that deployment's agents root
4838
+ [--parent <instance>] sugar for --relative-to X --relation child
4839
+ [--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
4840
+ [--relative-to <instance>] default: unrelated, top-level
4841
+ [--relative-root <agents-root>] disambiguates same-named anchors
4842
+ [--work worktree|checkout|attached|workspace|directory] override the soul's work mode
4843
+ [--work-dir <owner-work>] attached: the owner's work tree (always a child)
4844
+ [--branch <b>] [--base <ref>] worktree branch and starting ref;
4845
+ --base: worktree only; defaults to the soul
4846
+ commit observed by spawn (#445)
4844
4847
  directory: owned home/work, config context may
4845
4848
  be non-Git; rejects --work-dir and --branch
4846
- [--name <slug>] the exact instance name (no <agent>- prefix;
4847
- not with --purpose); must be a slug, not a
4848
- soul name, and unused in the deployment
4849
+ [--harness pi|claude|codex] [--launch-config <name>|none] explicit launch selection;
4850
+ otherwise oats-local.yaml souls.launch.<soul>,
4851
+ then souls.launch."*", then the soul's launch:, then pi;
4852
+ a harness uses its host default configuration if set;
4853
+ none selects the bare harness; a named configuration
4854
+ is a unit (a conflicting --harness is refused)
4855
+ [--model <id>|@native-default] override the selected model; @native-default
4856
+ selects the harness's own model default
4857
+ [--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
4858
+ [--no-launch] [--json] scaffold without launching; JSON result envelope
4859
+ [--allow-child-spawns|--no-child-spawns] this instance's child-spawn policy (default:
4860
+ allowed); enforced by OATS, not an OS sandbox
4849
4861
  [--provider <capability> <key>=<value>] a provider setting for this spawn only
4850
4862
  (repeatable; dotted keys nest; recorded in
4851
4863
  instance.json providers.<capability>)
4852
- [--preview [--max-age <s>]] decide everything, create nothing; the JSON's
4853
- decision binds an apply (--expect-decision <rev>);
4854
- --max-age reuses recent heads, on a preview and
4855
- on an apply bound by --expect-decision only
4864
+ [--preview] decide everything, create no instance; --json
4865
+ includes the decision revision for confirmation
4866
+ [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
4867
+ [--idempotency-key <key>] with --expect-decision, replay the completed receipt
4868
+ for the same key and confirmed decision; a different
4869
+ decision conflicts, an unfinished spawn refuses
4870
+ [--max-age <s>] reuse heads up to <s> seconds old (0-86400; 0 live),
4871
+ on preview or --expect-decision apply only;
4872
+ refused with --server; decision binding still holds
4873
+ [--wake-file <json-file> | --wake-json <json-text>] wake object: {cron, tz, message, enabled}
4874
+ --wake-json wins over --wake-file; either overrides
4875
+ --wake-every and --wake-cron
4876
+ [--wake-every <N> | --wake-cron <expr>] alternative: cron */N minutes (1-59) or explicit cron
4877
+ requires --wake-message <text> or --wake-message-file <f>;
4878
+ --wake-message-file wins over --wake-message
4879
+ [--wake-tz <zone>] optional for cron/every (default: local zone);
4880
+ saved after spawn, bound to the new home
4881
+ --runtime <harness> compatibility alias for --harness (deprecated)
4882
+ --instance <name> compatibility token for older routed hosts;
4883
+ refused locally: use --purpose or --name
4884
+ --trigger-event <json-file> internal trigger-runner event input, copied to
4885
+ <home>/.oats/trigger-event.json, exposed through
4886
+ OATS_TRIGGER_EVENT_FILE and recorded in
4887
+ instance.json.trigger (docs/schedules.md)
4888
+ [--help|-h] global help switches: show usage and exit
4889
+ oats spawn <agent> ... --server <id> routed spawn on the server's installed oats;
4890
+ --server is consumed before the local flag scanner
4856
4891
  oats retire <instance> [--force] retire an instance (window, hooks,
4857
4892
  [--self] worktree, home); --self = retire the
4858
4893
  [--keep-dir] [--json] CALLING instance: the window dies, then
@@ -46,7 +46,7 @@ see the [official catalog](official-catalog.md) for current pins.
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
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
+ "status-retire-state","session-inspect-size","session-inspect-running"],
50
50
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
51
51
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
52
52
  "capabilityShowApi":1}
@@ -124,6 +124,7 @@ see the [official catalog](official-catalog.md) for current pins.
124
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) |
125
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
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)) | |
127
+ | `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
127
128
  | `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"}`) | |
128
129
  | `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 | |
129
130
  | `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)) | |
@@ -2240,6 +2241,11 @@ containing them ships. For operator recovery, see
2240
2241
 
2241
2242
  ## Spawn
2242
2243
 
2244
+ Use `oats spawn --help` (also the spawn section of `oats help`) for the
2245
+ existing flag inventory, including compatibility and internal inputs. Help
2246
+ needs no deployment; the preview and apply contracts below govern confirmation
2247
+ and replay.
2248
+
2243
2249
  ### The preview
2244
2250
 
2245
2251
  ```text
@@ -2286,7 +2292,8 @@ it to a temporary copy (`soulFetched: true`).
2286
2292
  ([Instance names](#instance-names)). `home` and `worktree` (worktree mode,
2287
2293
  else `null`) are canonical: never derive paths.
2288
2294
  - `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
2289
- - `branch` defaults to `agents/<instance>` (`--branch` overrides); `base` is
2295
+ - In worktree mode, `branch` defaults to `agents/<instance>` (`--branch <b>`
2296
+ overrides); `base` is
2290
2297
  `--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
2291
2298
  soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
2292
2299
  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
@@ -2494,6 +2501,42 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2494
2501
  a silent `-2`.
2495
2502
  - The name is part of the decision.
2496
2503
 
2504
+ ### Spawn origin
2505
+
2506
+ For new instances from OATS 0.64.0, `spawnOrigin` describes the caller:
2507
+ `instance` when `OATS_INSTANCE` and/or `OATS_INSTANCE_HOME` identify an extant
2508
+ instance home in this deployment, otherwise `operator`. It is recorded in
2509
+ `instance.json` and reported unchanged by the spawn result and status JSON.
2510
+
2511
+ - A home alone must be absolute and resolve canonically to a home here, with a
2512
+ readable instance record whose name agrees with its directory.
2513
+ - A name alone must resolve uniquely to such a home here.
2514
+ - With both supplied, the name and canonical home must agree. An explicit
2515
+ valid home can disambiguate a duplicated historical name.
2516
+ - Invalid, stale, foreign or contradictory supplied evidence records
2517
+ `operator`, with no fallback to another signal. The working directory,
2518
+ `OATS_HOME`, `PI_AGENT_*`, relation and attached ownership do not supply
2519
+ caller identity. A stopped but extant home counts; no process or tmux
2520
+ liveness check is made.
2521
+
2522
+ A shell, Desktop or console caller without valid instance context records
2523
+ `operator`, even with `--parent`. A caller with valid instance context records
2524
+ `instance`, even without a relation. A shell that inherits that context also
2525
+ records `instance`. `parentInstance`, `relativeTo` and `relation` still describe
2526
+ lineage independently; existing child-spawn policy enforcement is unchanged.
2527
+ This field is informational attribution, not agent-authorship proof, an
2528
+ identity credential, a security boundary or an authorization input. There is
2529
+ no flag to choose it.
2530
+
2531
+ For a remote spawn (`--server`), attribution uses the host-side caller context.
2532
+ Caller identity is not forwarded, so the origin is normally `operator`.
2533
+
2534
+ Existing homes keep their recorded value, including the relation-based meaning
2535
+ recorded by earlier kernels; an absent value stays absent in local status.
2536
+ Idempotent spawn replay returns the recorded value. Remote rows relay the
2537
+ host's value unchanged, including historical values, and use `null` when the
2538
+ host does not supply one. Consumers must allow for those historical meanings.
2539
+
2497
2540
  <a id="spawn-errors"></a>
2498
2541
  ### Spawn errors
2499
2542
 
@@ -5139,7 +5182,34 @@ answered before any effect and carries [`details.holder`](#busy-holder)). The
5139
5182
  codes a retire answers only before any effect are
5140
5183
  [one list](#before-effect-codes). A recovery whose Git status disagrees with
5141
5184
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
5142
- source, recovery}], total}}` (the first 10 paths). Usage errors are text on
5185
+ source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
5186
+ bytes disagree with the source's (`worktree recovery verification disagreed
5187
+ with the source`) carries `details: {home, recoveryDisagreement: {basis:
5188
+ "current", entries: [{path, kind}], complete, stoppedBy?}}`, and the message
5189
+ names its first 5 entries. The refusal itself is the exact digest comparison
5190
+ and is unchanged; this report is read only after it refused, from the source
5191
+ and the copy as they are then (`basis: "current"`), so a source that changed
5192
+ since its bytes were recorded can show other differences, or none. `kind` is
5193
+ one of `missing` (in the source, not the copy), `extra`, `type`, `mode`,
5194
+ `link-target` and `file-content`, nothing is listed below a `missing`,
5195
+ `extra` or `type` entry, and one path can carry several kinds. `path` is
5196
+ relative to the worktree, with the same Git paths left out as the
5197
+ comparison: each printable ASCII byte as itself, a backslash as `\\`, every
5198
+ other byte as `\xHH`. No content, link target or absolute path is reported,
5199
+ and an entry that is a link is compared as a link, never followed. Every
5200
+ read is by path, so what is read is checked against what was listed: a file
5201
+ must be the regular file it was listed as (opened without following a link
5202
+ or waiting on a FIFO), and a directory the one it was listed as, before and
5203
+ after its listing and when the search leaves it; otherwise the search stops
5204
+ as `unreadable` and nothing found below that directory is reported. A
5205
+ replacement that is undone before the replaced directory is checked again is
5206
+ not detected: what was read through it can then be compared and named. Every
5207
+ path named is relative to the worktree. The search is bounded: at most 20 entries,
5208
+ 200,000 directory entries read (counted as each listing is read, so no
5209
+ listing goes past the budget), 64 MiB of file bytes read (files are compared
5210
+ in chunks, sizes first) and 5 seconds, checked between filesystem calls; when it stops early, `complete` is `false` and
5211
+ `stoppedBy` names why (`discrepancies`, `entries`, `bytes`, `time`, or
5212
+ `unreadable` when a tree could not be read). Usage errors are text on
5143
5213
  stderr, not envelopes.
5144
5214
 
5145
5215
  <a id="retire-reached"></a>
@@ -40,7 +40,9 @@ is the default); `tmux` must be installed on the execution host. A launched
40
40
  home keeps the session it recorded: `session start` and `restart` never
41
41
  re-read the defaults. The session target is recorded twice: in
42
42
  `instance.json` and in an independent lifecycle receipt. Every session command
43
- checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise).
43
+ checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise, with
44
+ `details.fields` naming what differs; see [Inspect, input and
45
+ attach](#inspect-input-and-attach)).
44
46
 
45
47
  ### tmux
46
48
 
@@ -56,7 +58,7 @@ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
56
58
  a retained dead pane also reads `false`. A wrapper shell with a live non-shell
57
59
  descendant still reads `true`. Status shares session inspection's pane rule,
58
60
  with one batched pane read per socket/session and one lazy process scan across
59
- all shell panes. A recorded server or pane that cannot be read gives
61
+ all panes that need it. A recorded server or pane that cannot be read gives
60
62
  `running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
61
63
  inspect --json` reports the session a new spawn would open in as `session`
62
64
  (`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
@@ -1064,6 +1066,47 @@ oats session attach --home /abs/home --detach-key 'C-\'
1064
1066
  live claim that the instance needs input from a human, `{since, producer,
1065
1067
  reason, message}`, or `null`; it is non-null only for a running harness
1066
1068
  (docs/desktop-cli-api.md, "Waiting on you").
1069
+ With feature `session-inspect-running`, every successful result also
1070
+ carries `running`, a boolean read from the same pane observation by the
1071
+ same rule `oats status --json` uses for a row's `running`: `true` for a live
1072
+ non-shell process in the agent pane (`state: unknown`), a harness behind a
1073
+ wrapper shell included; `false` for a fallback shell (`state: shell`, where
1074
+ `present` stays `true`), an absent or dead pane or a missing home
1075
+ (`stopped`) and a home that never launched (`not-launched`). It costs no
1076
+ second observation: at most one process-table read, only for a pane whose
1077
+ command is a shell, empty or the literal `unset`. An empty or `unset` label
1078
+ uses the pane PID's own process name from that same scan to establish a shell
1079
+ before checking descendants; an unreadable or non-shell own process stays
1080
+ `unknown` (`running: true`). `running` is activity at the authorized
1081
+ endpoint. It does not say the agent is generating, idle, healthy or ready
1082
+ for input, nor that it consumed a wake, and it does not prove which
1083
+ executable runs if a process inside the pane was replaced. When the backend
1084
+ cannot be read, a required process-table read for an explicitly labelled
1085
+ shell fails, or the pane answer is
1086
+ malformed or split, inspect is an error as before, never `running: false`.
1087
+ That includes a tmux server that is gone (`no server running on` its
1088
+ socket, as after a reboot): status reads that row as `running: false`, and
1089
+ inspect answers `E_SESSION_UNAVAILABLE`. Wherever inspect answers, its
1090
+ `running` is the one status reports.
1091
+ A consumer that sees no `running` (an older kernel or an older remote host)
1092
+ may read `state: unknown` on a successful result as running; a failed
1093
+ inspect is unknown, never stopped.
1094
+ `session inspect --server <id> --home <home> --json` relays the execution
1095
+ host's `running`, or its absence, as the host answered.
1096
+ A home whose `instance.json` disagrees with its session receipt is refused
1097
+ with `E_RUNTIME_AUTHORITY_MISMATCH` before any pane or process is read; the
1098
+ same refusal from any other session command, or in the answer of
1099
+ `oats retire`, carries the same details (the record a deferred
1100
+ `retire --self` leaves keeps only the code and message). Its `details.fields` names the differing fields, in this order, from this
1101
+ vocabulary only: `launched`, `tmux.session`, `tmux.window`, `tmux.socket`
1102
+ (the socket compared resolved, so a relative spelling of the same socket
1103
+ agrees). It carries no paths, values or receipt content. `launched` is
1104
+ listed unless a blocked or incomplete launch prompt explains
1105
+ `launched: false`; such a retained prompt is still allowed while its
1106
+ endpoint agrees, and only the endpoint fields that differ are named
1107
+ otherwise. A missing or invalid receipt stays `E_RUNTIME_ENDPOINT_UNKNOWN`
1108
+ and malformed metadata keeps its own refusal; neither carries
1109
+ `details.fields`.
1067
1110
  - **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
1068
1111
  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
1069
1112
  is never run by a shell. Existing endpoint authority, fallback-shell,
@@ -1,5 +1,11 @@
1
1
  # Run your first OATS team
2
2
 
3
+ **The quick way:** the README's [Start here](../README.md#start-here): your
4
+ coding agent downloads the `oats-getting-started` skill verbatim and follows
5
+ it. It installs OATS, creates your workspace with its own setup expert soul (or joins
6
+ an existing workspace), and hands over to that expert. This page is the manual
7
+ path, for writing a workspace by hand.
8
+
3
9
  The model is in [workspaces.md](workspaces.md), packages in
4
10
  [packages.md](packages.md), and the deployment layout this page creates in
5
11
  [configuration.md](configuration.md).
@@ -9,7 +9,7 @@ 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.13.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
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.1` or `oats-framework/v1.13.1`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.3`) 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,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.13.1
77
+ oats.framework: v1.13.3
78
78
  oats.okf: v5.2.1
79
79
  oats.aweb: v1.29.0
80
80
  teams:
@@ -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.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.1", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.3", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.1`
362
- resolves to tag `oats-framework/v1.13.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.3`
362
+ resolves to tag `oats-framework/v1.13.3`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -496,3 +496,16 @@ When the diff is not empty:
496
496
  not read it: it tags its own copy of `oats-package/`.) A green CI proves
497
497
  that the tag exists, not which commit it names: the pin's reviewer
498
498
  confirms on the remote that it names the first PR's merge commit.
499
+
500
+ ## Raising the Node version
501
+
502
+ A pull request that raises the Node version the workflows run
503
+ (`node-version` in `.github/workflows/`) also carries a macOS
504
+ [named run](named-test-runs.md) of `test/recovery-link-mode.test.mjs` at its
505
+ exact head. Every case in that file runs, with none skipped, and the run's
506
+ test warnings are read. The copier keeps each symbolic link's own mode with
507
+ `fs.lchmodSync`, which only macOS has and which Node lists as deprecated. If
508
+ a Node version drops it, the copy of a link whose mode differs from the new
509
+ link's must still be refused. Never take the link's mode out of the digest,
510
+ and never follow the link or change its target's mode, to make the upgrade
511
+ pass.
@@ -0,0 +1,135 @@
1
+ # OATS 0.63.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.62 Desktop refuses a 0.63.0 CLI. The
9
+ 0.63.0 Desktop accepts OATS CLIs `>=0.26.0 <0.64.0`.
10
+
11
+ - **The official catalog moves oats.framework 1.13.1 → 1.13.2** (oats.core
12
+ 2.6.4, see Provider updates). The other packages are unchanged. A
13
+ deployment takes it by moving its `oats.framework` pin and running
14
+ `oats sync`. Only new spawns use it.
15
+
16
+ ## Added
17
+
18
+ - `oats session inspect --json` reports `running` on every successful result,
19
+ advertised as `session-inspect-running`. Wherever inspect answers, it is the
20
+ liveness `oats status --json` reports for the row, by the same rule over the
21
+ same pane observation: `true` for a live harness, behind a wrapper shell included, and `false` for
22
+ a fallback shell, an absent or dead pane, a missing home or a home that never
23
+ launched. `state` and its enum are unchanged, and a failed observation is
24
+ still an error, never `false`; that includes a tmux server that is gone,
25
+ which status reads as `running: false` and inspect answers with
26
+ `E_SESSION_UNAVAILABLE`. `running` is activity at the session
27
+ endpoint, not health, readiness, busy or idle, or proof of which executable
28
+ runs. `--server` relays the execution host's answer; an older host's answer
29
+ has no `running`. See
30
+ [inspect, input and attach](../execution-targets.md#inspect-input-and-attach) (#1346).
31
+ - `E_RUNTIME_AUTHORITY_MISMATCH` (instance metadata that disagrees with the
32
+ independent session receipt, from a session command or `oats retire`) carries
33
+ `details.fields`: which of `launched`, `tmux.session`, `tmux.window` and
34
+ `tmux.socket` differ, never their values. A missing or invalid receipt is
35
+ still `E_RUNTIME_ENDPOINT_UNKNOWN`, without fields, and every refusal still
36
+ happens before any pane or process is read (#1346).
37
+
38
+ ## Changed
39
+
40
+ - A retire that refuses because the worktree recovery copy disagrees with the
41
+ source (`E_WORK_PRESERVATION_FAILED`, `worktree recovery verification
42
+ disagreed with the source`) now says where. `details.recoveryDisagreement`
43
+ lists up to 20 escaped relative paths, each with a fixed kind (`missing`,
44
+ `extra`, `type`, `mode`, `link-target`, `file-content`), and the message
45
+ names the first 5. The refusal is still decided by the exact digest
46
+ comparison, and nothing else changes: no hook runs, nothing is deleted and
47
+ the staged copy is removed as before. The report is read afterwards, from
48
+ the source and the copy as they are then, so it is a diagnosis, not a
49
+ verdict. Its search is bounded (entries, bytes read and 5 seconds) and says
50
+ when it stopped early. No content, link target or absolute path is
51
+ reported. See [the retire errors](../desktop-cli-api.md#retire) (#1360).
52
+
53
+ - **OATS Desktop accepts an `oats` CLI 0.63.x.** Its band is now
54
+ `>=0.26.0 <0.64.0`. 0.63 adds no new gate on the band: the Desktop does
55
+ not read `running` on `session inspect --json` or the mismatch's
56
+ `details.fields`, and it already reads a `launched` event's
57
+ `launchConfig: null` as no configuration (#1367).
58
+
59
+ ## Fixed
60
+
61
+ - A `session start|restart` that selects the bare harness from a home
62
+ recorded with a named configuration (for example `--launch-config none
63
+ --harness codex` on a home started with a claude configuration) now records
64
+ `launchConfig: null` everywhere. The launch itself, `instance.json` and the
65
+ command's answer already said so. But the session's `launched` event and the
66
+ restart receipt (`.oats-restart.json` `next.launchConfig`) named the earlier
67
+ configuration. So did the `launched` event an adoption records for a start
68
+ whose metadata write failed. Each now takes the name from the recipe the
69
+ start launched, its pending receipt's for an adoption. Only a receipt
70
+ without a recipe still falls back to the recorded one. Selection is
71
+ unchanged: `--launch-config none` is the bare harness, as
72
+ [launch configurations](../configuration.md#launch-configurations) say.
73
+ This is the kernel half of #1345. The provider's delivery for the selected
74
+ harness is tracked separately.
75
+
76
+ - SIGTERM or SIGINT now stops a capture pass cooperatively, where the worker was
77
+ killed at once before. The supervised pass starts no further worker, asks the
78
+ current worker to stop at its next unit boundary through the lock owner
79
+ record, and kills and reaps the worker if it has not stopped after a 5-second
80
+ grace, capped by the pass's deadline. The worker writes its own
81
+ `failed`/`interrupted` receipt and keeps its committed counts and the previous
82
+ `lastSuccess`. A killed worker leaves its `running` receipt, which the next
83
+ pass records as interrupted. The worker also catches a signal sent to the
84
+ caller's whole process group (Ctrl-C, `timeout`, a service manager), so it
85
+ is not killed mid-unit. An interrupted run's failure message now reads
86
+ "Capture execution was interrupted.", for a stop and for a later recovery
87
+ alike. The lock is released and the command exits 1.
88
+ `capture --home`, `--file` and `--reset-cursors` still run in the calling
89
+ process. They now stop at their safe points (before and after taking the
90
+ lock, before each format's batch, before the index update, and after the
91
+ work before answering), answer their
92
+ existing `failed` receipt with `capture interrupted by SIGTERM` and a
93
+ confirmed `appended`, release the lock and exit 1. Discovery, a format's
94
+ batch and the index update cannot be preempted, so a signal waits for the
95
+ segment it arrived in. See
96
+ [stopping capture](../../packages/record/docs/capture-service.md#stopping-capture-and-the-lock-owner-record) (#1347).
97
+ - The capture lock's `owner.json` now says who took it: `command`, `caller`
98
+ (`entry` and `trigger`) and `ppid`. These are fixed labels and process facts,
99
+ never argv or environment. They are diagnostic only. Records from earlier
100
+ releases are read and reclaimed exactly as before (#1347).
101
+
102
+ - The index update after `capture --home` or `--file` now skips streams it can
103
+ prove current. A stream is skipped when its validation checkpoint names the
104
+ journal's current version and its search cursor agrees with that checkpoint.
105
+ A skipped stream takes no stream lock, no validation and no `capture.db`
106
+ connection of its own. The pass opens `capture.db` once instead of twice per
107
+ stream, so an unchanged record no longer costs two lock cycles and two
108
+ database opens for every stream. Work now follows the streams that changed
109
+ and their new bytes. Backlog from `--no-index` passes, streams changed by
110
+ other writers, and missing or inconsistent evidence are still validated
111
+ under the stream lock, and a stale union still resets and is rebuilt. See
112
+ [the index update](../../packages/record/docs/capture-service.md) (#1348).
113
+
114
+ - A retire's recovery copy now keeps each symbolic link's own mode. The copy
115
+ recreated a link with its exact target but the platform's default mode,
116
+ while the verification digest holds the link's mode, so on macOS a worktree
117
+ whose ignored dependency tree has links of another mode (for example
118
+ `node_modules/.bin` links at 0700) was refused with "worktree recovery
119
+ verification disagreed with the source". The link is now given its source's
120
+ mode with lchmod, on the link itself, never on its target. Where the
121
+ platform cannot set a link's mode and the new link's differs, the copy is
122
+ refused rather than verified against another digest, and no target
123
+ changes. Spawn's copies of skills and the other recovery copies use the
124
+ same copier. See
125
+ [what a recovery copy carries](../souls-and-instances.md#retire) (#1360).
126
+
127
+ ## Provider updates
128
+
129
+ - **oats.framework 1.13.2, oats.core 2.6.4: `/oats-operate` reads inspect's
130
+ `running`** ([#1346](https://github.com/awebai/oats/issues/1346)). From OATS
131
+ 0.63.0 (feature `session-inspect-running`), the skill says what `running` on
132
+ `oats session inspect --json` means: activity at the session endpoint, not
133
+ health or readiness. A failed inspect is an error, never `running: false`.
134
+ Without the field, `state: unknown` on a successful result reads as running.
135
+ Text only: the capability's floor (`compatibility.oats`) is unchanged.