@awebai/oats 0.60.0 → 0.62.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 (96) hide show
  1. package/README.md +15 -19
  2. package/bin/oats.mjs +68 -21
  3. package/docs/capabilities.md +1 -1
  4. package/docs/configuration.md +9 -0
  5. package/docs/desktop-cli-api.md +28 -5
  6. package/docs/desktop.md +7 -0
  7. package/docs/execution-targets.md +49 -3
  8. package/docs/first-team.md +8 -0
  9. package/docs/implementation.md +2 -1
  10. package/docs/named-test-runs.md +382 -0
  11. package/docs/official-catalog.md +1 -1
  12. package/docs/packages.md +5 -5
  13. package/docs/release-notes/v0.61.0.md +155 -0
  14. package/docs/release-notes/v0.62.0.md +223 -0
  15. package/docs/tui.md +10 -4
  16. package/docs/upgrading.md +133 -11
  17. package/docs/workspaces.md +1 -1
  18. package/lib/core.mjs +2 -2
  19. package/lib/doctor-capture.mjs +35 -0
  20. package/lib/session-viewer.mjs +86 -7
  21. package/package-catalog.json +1 -1
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/instance-presentation.mjs +10 -0
  25. package/packages/client/instance-tree.mjs +48 -6
  26. package/packages/record/README.md +87 -13
  27. package/packages/record/bin/capture-hook.mjs +8 -0
  28. package/packages/record/bin/capture.mjs +143 -124
  29. package/packages/record/bin/recall.mjs +8 -3
  30. package/packages/record/bin/setup.mjs +115 -225
  31. package/packages/record/bin/turn-record.mjs +2 -2
  32. package/packages/record/docs/capture-service.md +1443 -28
  33. package/packages/record/docs/capture-status.schema.json +429 -12
  34. package/packages/record/lib/capture-admission.mjs +82 -0
  35. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  36. package/packages/record/lib/capture-aw.mjs +31 -12
  37. package/packages/record/lib/capture-budget.mjs +31 -0
  38. package/packages/record/lib/capture-cc.mjs +39 -6
  39. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  40. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  41. package/packages/record/lib/capture-command-operation.mjs +37 -0
  42. package/packages/record/lib/capture-command-output.mjs +61 -0
  43. package/packages/record/lib/capture-command-worker.mjs +6 -0
  44. package/packages/record/lib/capture-command.mjs +48 -0
  45. package/packages/record/lib/capture-completion.mjs +152 -0
  46. package/packages/record/lib/capture-context.mjs +50 -0
  47. package/packages/record/lib/capture-default-roots.mjs +30 -0
  48. package/packages/record/lib/capture-discovery.mjs +114 -0
  49. package/packages/record/lib/capture-failures.mjs +45 -0
  50. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  51. package/packages/record/lib/capture-health-installation.mjs +117 -0
  52. package/packages/record/lib/capture-health.mjs +116 -0
  53. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  54. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  55. package/packages/record/lib/capture-hook.mjs +26 -0
  56. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  57. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  58. package/packages/record/lib/capture-index-reset.mjs +109 -0
  59. package/packages/record/lib/capture-index-work.mjs +77 -0
  60. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  61. package/packages/record/lib/capture-issues.mjs +15 -2
  62. package/packages/record/lib/capture-lock.mjs +102 -16
  63. package/packages/record/lib/capture-native-unit.mjs +322 -0
  64. package/packages/record/lib/capture-pass.mjs +102 -0
  65. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  66. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  67. package/packages/record/lib/capture-retry.mjs +102 -0
  68. package/packages/record/lib/capture-run.mjs +125 -0
  69. package/packages/record/lib/capture-scratch.mjs +12 -3
  70. package/packages/record/lib/capture-service-definition.mjs +104 -0
  71. package/packages/record/lib/capture-service-install.mjs +362 -0
  72. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  73. package/packages/record/lib/capture-service-runner.mjs +18 -0
  74. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  75. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  76. package/packages/record/lib/capture-source-queue.mjs +199 -0
  77. package/packages/record/lib/capture-source-work.mjs +85 -0
  78. package/packages/record/lib/capture-state.mjs +16 -71
  79. package/packages/record/lib/capture-status.mjs +171 -0
  80. package/packages/record/lib/capture-supervisor.mjs +117 -0
  81. package/packages/record/lib/capture-watch.mjs +32 -0
  82. package/packages/record/lib/capture-work-session.mjs +238 -0
  83. package/packages/record/lib/capture-worker.mjs +58 -0
  84. package/packages/record/lib/derived-state.mjs +28 -15
  85. package/packages/record/lib/file-lines.mjs +22 -6
  86. package/packages/record/lib/formats.mjs +4 -3
  87. package/packages/record/lib/index-capture.mjs +97 -0
  88. package/packages/record/lib/index-db.mjs +3 -17
  89. package/packages/record/lib/index-reset.mjs +19 -0
  90. package/packages/record/lib/store.mjs +36 -11
  91. package/packages/record/lib/transcript-prefix.mjs +125 -0
  92. package/packages/tui/lib/client.mjs +2 -2
  93. package/packages/tui/lib/model.mjs +15 -5
  94. package/packages/tui/lib/views/palette.mjs +7 -3
  95. package/skills/oats-getting-started/SKILL.md +1 -1
  96. package/docs/macos-test-runs.md +0 -246
package/README.md CHANGED
@@ -1,33 +1,29 @@
1
1
  # OATS: an open framework for specialised agent teams
2
2
 
3
- **Free, open source, provider-agnostic, and decentralised by design.**
3
+ **Free, open source, provider- and harness-agnostic, and decentralised by design.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@awebai/oats.svg)](https://www.npmjs.com/package/@awebai/oats)
6
6
  [![Release](https://img.shields.io/github/v/release/awebai/oats?display_name=tag)](https://github.com/awebai/oats/releases)
7
7
  [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
8
8
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
9
 
10
- OATS—**Open Agent Team Specification**—is a framework for building, running and coordinating teams of specialised AI agents. You can organise your team however you need, choosing models, harnesses and capabilities without being tied to a particular provider or stack.
10
+ OATS—**Open Agent Team Specification**—is a provider- and harness-agnostic framework for building distributed agent teams: on one laptop, across machines or across a large organisation, as flexibly as you need. It is completely free and open source.
11
11
 
12
- **Capabilities are the building blocks of an OATS setup.** When you define an agent, you choose its capabilities. Each provides the know-how and tools for knowledge systems, messaging, task coordination or any other workflows, tools or ways of working. We provide defaults to get started, but you can adapt existing capabilities or create fully custom ones to shape how your agents work and which tools they use.
12
+ - **Every agent keeps the full power of its harness.** Claude Code, Codex or pi: OATS connects them, so agents on different harnesses and providers communicate and work together.
13
+ - **The CLI and contracts set up the team; capabilities shape it.** Choose the agents, the tools you already use and how they coordinate. We ship opinionated defaults that we think work well, and you can change or replace any of them.
14
+ - **You keep control** of messaging, knowledge, coordination and anything else your team does, so your knowledge, workflows and team structure outlast any model or platform.
15
+ - **So you don't lose your head as the threads multiply,** there are two clients: **OATS Desktop**, a free, fully integrated ADE (an agentic IDE), and **`oats tui`** for the terminal (in preview).
16
+ - **Built on what you already use:** Git, GitHub or GitLab, and your agent harnesses. No OATS account, central server or OATS-hosted database; integrations you choose may run their own.
13
17
 
14
- The [official catalog](docs/official-catalog.md) is the reviewed list of official packages; a workspace trusts a package by declaring it, and listing does not declare it for you.
18
+ For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has its own for its area. Through capabilities you decide:
15
19
 
16
- For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has specific capabilities for its own area of expertise.
20
+ - which specialists make up the team;
21
+ - which models and harnesses their instances use;
22
+ - where their knowledge lives and how it grows;
23
+ - which skills, tools and workflows they receive;
24
+ - how they communicate and coordinate.
17
25
 
18
- Through your capabilities, you remain in control of:
19
-
20
- - Which specialists make up the team.
21
- - Which models and harnesses their instances use.
22
- - Where their knowledge lives and how it develops.
23
- - Which skills, tools and workflows they receive.
24
- - How they communicate and coordinate.
25
-
26
- These choices determine how your team operates and where the value of its work accumulates. Keeping them under your control means your knowledge, workflows and team structure can outlast any particular model or platform.
27
-
28
- OATS also provides **OATS Desktop: a free, fully integrated ADE—an agentic IDE**. It brings your team, its work and its agent sessions into one place, making day-to-day collaboration with your agents clearer and more pleasant.
29
-
30
- OATS builds on tools you already use—**Git, GitHub or GitLab, and your preferred agent harnesses**. People can share agent definitions, knowledge and workflows across projects without an OATS account, a central OATS server or an OATS-hosted database. Selected integrations may use their own servers or databases; those are your choices, not a mandatory OATS service.
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.
31
27
 
32
28
  ## Why OATS
33
29
 
@@ -235,7 +231,7 @@ This README explains the framework and its direction. Advanced mechanisms such a
235
231
 
236
232
  ## Contributing and releases
237
233
 
238
- Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS can be run on a macOS runner by hand: see [macOS test runs](docs/macos-test-runs.md).
234
+ Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see [named test runs](docs/named-test-runs.md).
239
235
 
240
236
  Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the [release notes](docs/release-notes/) before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
241
237
 
package/bin/oats.mjs CHANGED
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * oats — the OATS command line.
4
4
  *
5
- * oats doctor [dir] [--soul <s>] [--json] show the deployment; --soul: the instructions an instance of <s> would carry
5
+ * oats doctor [dir] [--soul <s>] [--json] show deployment and offline capture warnings; --soul: composition only
6
6
  * oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
7
7
  * agents/), then sync
8
8
  * oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
@@ -25,6 +25,7 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
25
25
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
+ import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
28
29
  import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
29
30
  import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
30
31
  import {
@@ -44,7 +45,7 @@ import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlo
44
45
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
45
46
  import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
46
47
  import { terminalText } from "../lib/refused-text.mjs";
47
- import { soulsOffered } from "../lib/instance-resolution.mjs";
48
+ import { qualifiedSoulName, soulCandidates, soulsOffered } from "../lib/instance-resolution.mjs";
48
49
  import { parseConfigData } from "../lib/config-data.mjs";
49
50
  import * as remoteModule from "../lib/remote.mjs";
50
51
  import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
@@ -829,7 +830,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
829
830
  information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
830
831
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
831
832
  ...(problems.length ? { problems } : {}),
832
- warnings: hookEvents.warnings,
833
+ warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
833
834
  };
834
835
  }
835
836
  /** Kernel/bridge version skew (published in lockstep from one tag), in every pi folder a launch
@@ -876,6 +877,7 @@ async function doctor(dir) {
876
877
  for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
877
878
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
878
879
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
880
+ if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
879
881
  for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
880
882
  for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
881
883
  if (soulName) {
@@ -3463,7 +3465,13 @@ async function sessionCmd() {
3463
3465
  if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
3464
3466
  // --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
3465
3467
  // status 20. Without it every key reaches the agent and there is no keyboard exit.
3466
- process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
3468
+ // What earlier attaches left (a viewer whose attach died without detaching): one line, on
3469
+ // stderr, before the client takes the terminal, and only when something was removed.
3470
+ const onSwept = ({ sessions, tables }) => {
3471
+ const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
3472
+ if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
3473
+ };
3474
+ process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), onSwept });
3467
3475
  return;
3468
3476
  }
3469
3477
  if (args[1] === "inspect") result = inspectInstanceSession(home);
@@ -3536,7 +3544,7 @@ async function tuiCmd() {
3536
3544
  * instance homes), then runs exactly the `oats sync` path — discover over the
3537
3545
  * remotes, confirm membership, resolve `packages:`, write `oats-lock.json`. Nothing is installed, no soul
3538
3546
  * is created, nothing is spawned, no `oats-config.yaml` is written: the member
3539
- * clones and the operator expert are the operator's next steps, printed here. */
3547
+ * clones and the workspace's setup expert are the operator's next steps, printed here. */
3540
3548
  async function onboardCmd() {
3541
3549
  const bail = (code, message, details) => (JSON_MODE ? jsonFail(code, message, details) : die(message));
3542
3550
  const usage = "usage: oats onboard [<dir>] --workspace <repo ref> [--json] (or --dir <dir>)";
@@ -3615,12 +3623,15 @@ async function onboardCmd() {
3615
3623
  // (4) The taught layout as next steps (design doc §4), and the envelope.
3616
3624
  const standalone = synced.discovery.standalone === true;
3617
3625
  const members = synced.report.members;
3618
- // The operator expert is suggested only when THIS workspace lists a soul by that name (a
3619
- // confirmed member's or, standalone, the repo's own); otherwise any listed soul is spawnable.
3626
+ // The setup expert is suggested only when THIS workspace lists one (setupExpertOf); otherwise
3627
+ // any listed soul is spawnable.
3620
3628
  const soulNames = synced.items.souls.map((s) => s.name);
3621
- const setupExpert = soulNames.includes("oats-operator-expert");
3622
- const spawnHint = setupExpert ? `oats spawn oats-operator-expert --dir ${shortPath(dir)}` : null;
3623
- const anySoulHint = `spawn any listed soul: oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
3629
+ const { OPERATOR_CAPABILITY } = await import("../lib/operator-coverage.mjs");
3630
+ const wsName = standalone ? null : synced.discovery.workspace?.name;
3631
+ const conventional = typeof wsName === "string" && wsName ? `${wsName}-oats-setup-expert` : null;
3632
+ const setupExpert = setupExpertOf(synced.discovery, { conventional, capability: OPERATOR_CAPABILITY });
3633
+ const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}` : null;
3634
+ const anySoulHint = `oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
3624
3635
  // A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
3625
3636
  // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
3626
3637
  // listed exactly like any other member when it is one: a clone of it is needed only if someone
@@ -3660,10 +3671,38 @@ Next:
3660
3671
  2. Check who may read the host: ${synced.discovery.key}${hostIsMember ? " is itself a member" : " is a dedicated host"}. The workspace file
3661
3672
  names every member, so if any member is private the host must be a private repo that is not
3662
3673
  a public member; public contributors then get the standalone case (from: here + oats.core).
3663
- 3. ${setupExpert ? "Spawn the operator expert to guide the rest (souls, teams, provider settings):" : "No soul named oats-operator-expert is listed here —"}
3674
+ 3. ${setupExpert ? `Spawn ${setupExpert}, this workspace's OATS setup expert
3675
+ (it holds ${OPERATOR_CAPABILITY}), to guide the rest:` : `No soul here holds ${OPERATOR_CAPABILITY} — add a ${conventional ? `${conventional} soul` : "soul"} that declares it,
3676
+ or spawn any listed soul:`}
3664
3677
  ${spawnHint ?? anySoulHint}`);
3665
3678
  }
3666
3679
 
3680
+ /** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314), among the
3681
+ * souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
3682
+ * `{ from: … }`, from any source (`off` is no declaration): the one named `conventional`
3683
+ * (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace name);
3684
+ * else the first by name; else null. A soul is never chosen by its name alone. Only the soul's own declaration is read, never
3685
+ * a resolution: oats.setup that reaches a soul through the workspace defaults alone is not seen. → the
3686
+ * name to spawn it by: the bare name, else `<member>/<soul>` (`<package>/<soul>`), else
3687
+ * `<member repo key>/<soul>`, the first that names this soul alone. */
3688
+ function setupExpertOf(discovery, { conventional, capability }) {
3689
+ const candidates = soulCandidates(discovery);
3690
+ const declares = (entry) => {
3691
+ const caps = entry.definition?.capabilities;
3692
+ const choice = caps !== null && typeof caps === "object" && Object.hasOwn(caps, capability) ? caps[capability] : null;
3693
+ return choice !== null && typeof choice === "object" && typeof choice.from === "string" && choice.from !== "";
3694
+ };
3695
+ const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
3696
+ const entries = candidates.map((c) => c.entry).sort((a, b) => order(a.name, b.name) || order(qualifiedSoulName(a), qualifiedSoulName(b)));
3697
+ const chosen = (conventional && entries.find((e) => e.name === conventional && declares(e))) || entries.find(declares);
3698
+ if (!chosen) return null;
3699
+ // The shortest name a spawn resolves to exactly this soul: two members can share a repository
3700
+ // basename (github.com/a/agents, github.com/b/agents), so the last form is the full repo key.
3701
+ const forms = [chosen.name, qualifiedSoulName(chosen), ...(typeof chosen.package === "string" ? [] : [`${chosen.repoKey}/${chosen.name}`])];
3702
+ const only = (name) => { const hits = candidates.filter((c) => c.matches(name)); return hits.length === 1 && hits[0].entry === chosen; };
3703
+ return forms.find(only) ?? forms[forms.length - 1];
3704
+ }
3705
+
3667
3706
  /** `oats onboard <dir> [--workspace <ref>] --check`: what onboarding <dir> here would meet, read-only (the
3668
3707
  * question `oats server connect` asks a host before onboarding there, and `oats server check` asks of a
3669
3708
  * registered deployment). A leading ~ is this machine's home. `state` is absent | empty | not-empty |
@@ -4039,12 +4078,12 @@ const EXPERIMENTAL_CMDS = new Set(["dress", "spawn", "segments", "mind"]);
4039
4078
  async function recordCmd(sub) {
4040
4079
  process.argv.splice(2, 1);
4041
4080
  if (sub === "setup") {
4042
- // setup writes a node into the user's Claude settings and into the capture watcher's unit,
4081
+ // setup writes a node into the user's Claude settings and into the capture service's unit,
4043
4082
  // and nothing rewrites them but setup run again: it is handed the rule's answer for the node
4044
4083
  // running this kernel (docs/capabilities.md, "The node a hook writes down"). The script is
4045
4084
  // imported into this process, so the variable is set here, over whatever the caller's
4046
4085
  // environment held; packages/record imports nothing of the kernel.
4047
- const { node, warning } = stableNode({ consequence: "the capture hooks and the capture watcher stop when it goes away", remedy: "run `oats setup` again" });
4086
+ const { node, warning } = stableNode({ consequence: "the capture hooks and the capture service stop when it goes away", remedy: "run `oats setup` again" });
4048
4087
  if (warning) console.error(`oats: warning: ${warning}`);
4049
4088
  process.env.OATS_NODE_BIN = node;
4050
4089
  }
@@ -4734,8 +4773,9 @@ Usage:
4734
4773
  oats onboard [<dir>] --workspace <repo ref> realize a workspace here: writes <dir>/oats-local.yaml
4735
4774
  [--json] and agents/, then runs the oats sync path (lock v3)
4736
4775
  and prints the
4737
- next steps (clone members you work IN, spawn
4738
- oats-operator-expert); creates no soul, spawns nothing
4776
+ next steps (clone members you work IN, spawn the
4777
+ workspace's setup expert (the soul holding oats.setup));
4778
+ creates no soul, spawns nothing
4739
4779
  [--check] --check: write nothing; report <dir> (~ = this home),
4740
4780
  its state and whether Git reads the workspace remote
4741
4781
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
@@ -4853,8 +4893,8 @@ Usage:
4853
4893
  [--launch-config <name>|none] command and preflight; read-only, nothing
4854
4894
  [--harness r] [--model m] started; a named configuration is a unit, so
4855
4895
  [--yolo | --no-yolo] --json a disagreeing --harness is refused
4856
- oats doctor [dir] [--soul <name>] [--json] resolved targets, trust, requirements;
4857
- --soul shows final composed AGENTS.md
4896
+ oats doctor [dir] [--soul <name>] [--json] resolved targets and offline capture warnings;
4897
+ --soul shows final composed AGENTS.md only
4858
4898
  oats update [--check] [--yes] check npm for a newer kernel and move the pi bridge
4859
4899
  [--dir <deployment>] in every pi folder the deployment's launches use
4860
4900
  (docs/upgrading.md); then run oats doctor
@@ -4962,15 +5002,22 @@ Usage:
4962
5002
 
4963
5003
  The turn record (core — every conversation captured, searchable, replicated):
4964
5004
  oats capture [--watch|--status] land Claude Code/pi/codex sessions and aw
4965
- [--owner <name>] [--root <dir>] client logs in the record; reconciliation
4966
- is the capture
5005
+ [--owner <name>] [--root <dir>] client logs in the record: one bounded
5006
+ supervised reconciliation pass; partial
5007
+ passes exit 0 with work pending
5008
+ oats capture --hook launch a detached pass; exit 0 means
5009
+ capture launched, not completed
5010
+ oats capture --health [--json] offline installation, run and issue
5011
+ diagnosis; captures nothing
4967
5012
  oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]
4968
5013
  one session file (an archived session),
4969
5014
  captured as --home capture would
4970
5015
  oats recall [--kind k] [--thread t] search the whole record — mail, chat,
4971
5016
  [--from f] [--show id] <query> sessions — with exact turn provenance
4972
- oats setup [--owner <name>] [--dry-run] install capture hooks + background watcher
4973
- [--no-service] [--no-hooks] (launchd/systemd), then run the first pass
5017
+ oats setup [--owner <name>] [--root <dir>] [--replace-service]
5018
+ [--no-service] [--no-hooks] [--dry-run]
5019
+ install hooks + periodic capture
5020
+ (launchd/systemd), then run the first pass
4974
5021
 
4975
5022
  oats experimental <dress|spawn|segments|mind> EXPERIMENTAL tools over the record —
4976
5023
  selection and agent synthesis; unproven by
@@ -842,7 +842,7 @@ A package that also runs under a kernel older than the variable falls back to
842
842
  `oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
843
843
  own process, over any value the caller's environment held, before it runs the
844
844
  turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
845
- into the capture hooks and the capture watcher's unit. In the third case
845
+ into the capture hooks and the capture service's unit. In the third case
846
846
  `oats setup` carries the warning, a dry run included.
847
847
 
848
848
  ### The worktree event
@@ -305,6 +305,15 @@ configuration is a host choice: a soul never names one.
305
305
  environment, command and preflight checks) and starts nothing.
306
306
  - The old key `runtime` is still read as `harness`, with a
307
307
  `deprecated-runtime-name` warning.
308
+ - **Claude's permissions** are Claude's own settings, not OATS keys. They go
309
+ in the user settings of the Claude config a launch uses (its
310
+ `CLAUDE_CONFIG_DIR`, else `~/.claude`), or `--permission-mode` goes in a
311
+ configuration's `args`. Never in a home's `.claude/settings.json`: the
312
+ capabilities manage it at every start, and Claude ignores auto mode there.
313
+ oats.setup's `/oats-agent-permissions` (oats.framework 1.13.0) teaches the
314
+ setup: auto mode, narrow allow rules for the `oats` and `gh` reads,
315
+ `oats spawn` and reading `aw` mail and chat, and what stays gated.
316
+ `yolo` is separate and is meant for isolated machines.
308
317
 
309
318
  ### The harness default
310
319
 
@@ -882,8 +882,8 @@ same argument, given once). The ref is checked before anything is written.
882
882
  "hosting":{"host":"github.com/acme/agents","hostIsMember":true,"rule":"If any member is private, host oats-workspace.yaml in a private repo …"},
883
883
  "next":{"clone":[{"key":"github.com/acme/agents","name":"agents","url":"https://github.com/acme/agents.git","dir":"/w/agents-repo","present":false,"host":true},
884
884
  {"key":"github.com/acme/platform","name":"platform","url":"https://github.com/acme/platform.git","dir":"/w/platform","present":true,"host":false}],
885
- "spawn":"oats spawn oats-operator-expert --dir /w",
886
- "souls":["oats-operator-expert","platform-engineer","release-manager"]}}
885
+ "spawn":"oats spawn acme-oats-setup-expert --dir /w",
886
+ "souls":["acme-oats-setup-expert","platform-engineer","release-manager"]}}
887
887
  ```
888
888
 
889
889
  - `sync` is the full [`oats sync`](#oats-sync) report (abridged above).
@@ -895,9 +895,32 @@ same argument, given once). The ref is checked before anything is written.
895
895
  existing clone (the `clones:` entry, else `<dir>/<name>`), else where to
896
896
  clone it: `<dir>/<name>`, or `<dir>/agents-repo` for a member named
897
897
  `agents`. `url` is `null` when unknown.
898
- - `next.spawn` is `oats spawn oats-operator-expert --dir <dir>` when the
899
- workspace has a soul by that name, else `null`. `next.souls` is the first
900
- three soul names, sorted.
898
+ - `next.spawn` is `oats spawn <soul> --dir <dir>` naming the workspace's
899
+ OATS setup expert, else `null` (OATS 0.61.0; before it, only a soul named
900
+ `oats-operator-expert` was named). Among the souls onboarding lists
901
+ (confirmed members', external and package souls; standalone, the
902
+ repository's own), the setup expert is:
903
+ 1. the soul named `<workspace name>-oats-setup-expert` that declares
904
+ `oats.setup`, where the workspace name is the `name:` of
905
+ `oats-workspace.yaml` (`sync.workspace.name`); a standalone view has no
906
+ workspace name, so this step does not apply there;
907
+ 2. otherwise the first soul by name that declares `oats.setup`;
908
+ 3. otherwise none: `null`.
909
+
910
+ A soul declares `oats.setup` when its own `soul.yaml` names it under
911
+ `capabilities:` as `{ from: … }`, from any source (`package`, `here` or a
912
+ member key); `oats.setup: off` does not count. A soul is never chosen by
913
+ its name alone: one named `<workspace name>-oats-setup-expert` that does
914
+ not declare `oats.setup` falls through to step 2.
915
+
916
+ Only the soul's own declaration is read, not its resolved composition:
917
+ `oats.setup` that reaches a soul only through the workspace's `defaults:`
918
+ is not seen, and a declared `oats.setup` is not checked to resolve. A soul
919
+ whose name another listed soul shares is named so that `oats spawn` finds
920
+ it alone: `<member>/<soul>` or `<package>/<soul>`, else, when two members
921
+ share a repository name, `<member repo key>/<soul>`. The text output's step 3 names
922
+ the same soul, or, with none, the conventional name to add.
923
+ `next.souls` is the first three soul names, sorted.
901
924
  - Errors: `E_BAD_ARGS` (usage, no `--workspace`, a repeated directory, an
902
925
  unknown flag), `E_REPO_REF`, `E_ALREADY_ONBOARDED {local, dir}` (this
903
926
  directory already has `oats-local.yaml`), `E_ONBOARD_FAILED {dir}`. A
package/docs/desktop.md CHANGED
@@ -529,6 +529,13 @@ has reached the execution host. Both CLI installations must advertise
529
529
  `session-upload`. A failed transfer leaves the draft unchanged and shows an
530
530
  error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
531
531
 
532
+ ## The sidebar's instance tree
533
+
534
+ The sidebar lists a workspace's instances as a tree: a child sits one step
535
+ right of its parent, and related instances are grouped together. Siblings are
536
+ joined by a dotted line through their dots. A parent's line to its children
537
+ runs just to the right of the dotted line, so the two never merge.
538
+
532
539
  ## Identity marks and harness badges
533
540
 
534
541
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -1103,6 +1103,50 @@ oats session attach --home /abs/home --detach-key 'C-\'
1103
1103
  another session, another agent's terminal. Your own sessions keep your
1104
1104
  setting.
1105
1105
 
1106
+ **An attach that dies without detaching leaves nothing behind.** A
1107
+ cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh can end
1108
+ `oats` and its tmux client together. `oats` itself then removes nothing, so
1109
+ the tmux server does. Once its client has attached, the viewer's client
1110
+ sets a `client-detached` hook on the viewer session alone: when a client
1111
+ leaves and none is left, the hook kills the viewer session. It is set after
1112
+ the attach, so a viewer whose client never attached is removed by `oats`
1113
+ or by the next attach's sweep. From then on, the server removes the viewer
1114
+ when its last client's connection drops without a word from the client:
1115
+ `oats` and its client SIGKILLed together (oomd, a stop timeout). A client
1116
+ that ends any other way (a hang-up, a termination, a `detach-client` from
1117
+ another client) is not seen by that hook: `oats` removes the viewer as it
1118
+ ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
1119
+ `destroy-unattached`: on tmux 3.4 it crashes the agents' server when another
1120
+ client detaches the viewer. A keyed viewer's key table (below)
1121
+ belongs to the server, not to the session, and its `client-detached` hook
1122
+ unbinds the table as it kills the session. For a viewer session that ends
1123
+ another way (its agent's window ends, a `kill-session`), a keyed viewer sets
1124
+ one global hook entry on the agents' server, `session-closed[900]`: when a
1125
+ session whose name is a viewer's closes, the entry unbinds the key table of
1126
+ that name. It is the only global hook entry OATS owns there.
1127
+ Every keyed viewer sets the same entry again, which leaves it unchanged,
1128
+ and no other index is touched. Keep your own `session-closed` hooks
1129
+ (`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
1130
+ 900 is replaced. A global `client-detached` hook of yours does not run
1131
+ for a viewer's client whose connection dropped: the viewer session's own
1132
+ hook takes its place there. The entry needs `run-shell -C`, which tmux has from 3.2.
1133
+ Before 3.2 it does nothing, and the next attach's sweep removes the table.
1134
+
1135
+ Every attach also sweeps the server before it opens its viewer. It removes:
1136
+
1137
+ - a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
1138
+ whose attaching process, the pid in its name, no longer exists;
1139
+ - a viewer key table whose session no longer exists.
1140
+
1141
+ The sweep keeps a viewer whose attach is alive, even with no client: its
1142
+ client may not have attached yet. It also never removes an attached
1143
+ viewer, anything not named as a viewer, or the `oatsview-locked` table
1144
+ that every viewer without a key shares. When it removed something, the
1145
+ attach prints one line on stderr before the viewer opens:
1146
+ `oats: removed <n> leftover viewer session(s) and <m> key table(s) of
1147
+ earlier attaches`. A failed sweep is not the attach's failure; the next
1148
+ attach sweeps again.
1149
+
1106
1150
  On tmux 3.2 and later the viewer's tmux client asks for synchronized
1107
1151
  output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
1108
1152
  DEC mode 2026, so a terminal that receives a redraw in two pieces does not
@@ -1119,9 +1163,11 @@ oats session attach --home /abs/home --detach-key 'C-\'
1119
1163
  The key is taken from the agent's input: the agent never receives it while
1120
1164
  this viewer is attached. A keyed viewer reads a tmux key table of its own,
1121
1165
  named as its temporary session and removed with it, so the key is bound
1122
- for that viewer alone. Check the feature in `oats version --json` before
1123
- passing the flag: a kernel without it ignores the flag and opens a viewer
1124
- with no exit.
1166
+ for that viewer alone. The key's binding also removes the viewer session's
1167
+ `client-detached` hook before it detaches: the session outlives its client
1168
+ until `oats` has read that the key was used, and `oats` then removes it.
1169
+ Check the feature in `oats version --json` before passing the flag: a
1170
+ kernel without it ignores the flag and opens a viewer with no exit.
1125
1171
 
1126
1172
  The key is one of these, spelled exactly (case-sensitive):
1127
1173
 
@@ -69,6 +69,14 @@ runs before adding its pin. Then clone the
69
69
  member you will work in beside `oats-local.yaml` (only a soul's work target
70
70
  needs a clone — discovery and resolution run over the remotes).
71
71
 
72
+ The last next step names the workspace's OATS setup expert to spawn, among the
73
+ souls that declare `oats.setup` in their own `soul.yaml`: the one named
74
+ `<workspace name>-oats-setup-expert` (`acme-oats-setup-expert` for a
75
+ workspace named `acme`), else the first by name. With neither, it says so and suggests
76
+ adding that conventional soul, or spawning any listed soul. The full rule and
77
+ its limits are in
78
+ [desktop-cli-api.md](desktop-cli-api.md#oats-onboard-onboardapi-2).
79
+
72
80
  `--json` returns `onboardApi: 2` (`local`, `dir`, `agents`, `lock`, the full
73
81
  `sync` report, `hosting`, `next.clone[]`, `next.spawn`); running it twice is
74
82
  `E_ALREADY_ONBOARDED` (use `oats sync`); a mistyped ref is `E_REPO_REF`, an
@@ -79,7 +79,7 @@ and the rules its tests pin.
79
79
  | `souls/` | this repository's own souls (a workspace member) |
80
80
  | `docs/` | the reference pages, schemas, design records and release notes |
81
81
  | `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
82
- | `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
82
+ | `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
83
83
  | `test/` | the kernel and CLI suites, with their fixtures |
84
84
 
85
85
  ## Kernel modules
@@ -96,6 +96,7 @@ and the rules its tests pin.
96
96
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
97
97
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
98
98
  | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
99
+ | `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
99
100
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
100
101
  | `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
101
102
  | `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |