@awebai/oats 0.69.7 → 0.69.9

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.
package/README.md CHANGED
@@ -35,12 +35,15 @@ The [official catalog](docs/official-catalog.md) is the reviewed list of officia
35
35
  curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
36
36
  ```
37
37
 
38
- If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for me". It then:
38
+ If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for this project". It then:
39
39
 
40
- - **Asks first, in one round:** your project, its repositories, the knowledge tools you use, and a username for agent messaging.
41
- - **Installs OATS and OATS Desktop,** then creates your workspace in one commit: the workspace, a messaging team, a setup expert and a first developer. Or it joins this machine to an existing workspace.
42
- - **Gives your agents identities and messaging:** one command signs up a hosted [aweb](https://aweb.ai) team for the new workspace, with no API key and no pull requests to merge.
43
- - **Hands over to the setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
40
+ - **Asks first, in one round:** your project, its repositories and where the workspace should live, the knowledge tools you use, and how your agents message each other ([aweb](https://aweb.ai) by default).
41
+ - **Installs OATS, OATS Desktop and the messaging CLI.**
42
+ - **Creates your workspace's team:** you sign in to your aweb account in your browser, and one command creates the team, owned by your account, that every agent you spawn joins.
43
+ - **Writes your workspace** in one commit, in your repository or a new private one: the workspace and its team, nothing else. Or it joins this machine to an existing workspace.
44
+ - **Spawns the setup expert and opens the Desktop on it.** The setup expert is an OATS agent that turns OATS's defaults into your own coordination, knowledge and tasks capabilities, with you. You type only passwords, logins and tokens.
45
+
46
+ You end with a working workspace, the Desktop open on it, and its setup expert running.
44
47
 
45
48
  Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
46
49
 
package/bin/oats.mjs CHANGED
@@ -53,7 +53,7 @@ const {
53
53
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
54
54
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
55
55
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
56
- findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
56
+ findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, MAX_INSTANCE_NAME, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
57
57
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
58
58
  } = await kernelImport("core", () => import("../lib/core.mjs"));
59
59
  const {
@@ -84,7 +84,7 @@ const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_B
84
84
  const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
85
85
  const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
86
86
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
87
- const { livenessWord, lostLine, statusWord } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
87
+ const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
88
88
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
89
89
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
90
90
  const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
@@ -2601,7 +2601,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2601
2601
  { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2602
2602
  // Feature waiting-on-you: non-null only on a running row; the reader has
2603
2603
  // already validated the message (one line, no control characters).
2604
- if (i.running === true && i.waitingOnYou) console.log(` ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
2604
+ { const waiting = waitingLine(i); if (waiting) console.log(` ${waiting}`); }
2605
2605
  const key = i.home ?? `${a.name}/${i.instance}`;
2606
2606
  if (i.identity) console.log(` identity: ${servedIdentityLine(i.identity)}`);
2607
2607
  // The kernel the home's plain `oats` runs (its last launch's), when it is not this one.
@@ -3695,8 +3695,9 @@ async function onboardCmd() {
3695
3695
  const { OPERATOR_CAPABILITY } = await import("../lib/operator-coverage.mjs");
3696
3696
  const wsName = standalone ? null : synced.discovery.workspace?.name;
3697
3697
  const conventional = typeof wsName === "string" && wsName ? `${wsName}-oats-setup-expert` : null;
3698
- const setupExpert = setupExpertOf(synced.discovery, { conventional, capability: OPERATOR_CAPABILITY });
3699
- const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}` : null;
3698
+ const chosenExpert = setupExpertOf(synced.discovery, { conventional, workspaceName: wsName, capability: OPERATOR_CAPABILITY });
3699
+ const setupExpert = chosenExpert?.soul ?? null;
3700
+ const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}${chosenExpert.name ? ` --name ${chosenExpert.name}` : ""}` : null;
3700
3701
  const anySoulHint = `oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
3701
3702
  // A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
3702
3703
  // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
@@ -3746,18 +3747,24 @@ Next:
3746
3747
  3. ${setupExpert ? `Spawn ${setupExpert}, this workspace's OATS setup expert
3747
3748
  (it holds ${OPERATOR_CAPABILITY}), to guide the rest:` : `No soul here holds ${OPERATOR_CAPABILITY} — add a ${conventional ? `${conventional} soul` : "soul"} that declares it,
3748
3749
  or spawn any listed soul:`}
3749
- ${spawnHint ?? anySoulHint}`);
3750
+ ${spawnHint ?? anySoulHint}${chosenExpert?.why ? `\n (${chosenExpert.why})` : ""}`);
3750
3751
  }
3751
3752
 
3752
- /** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314), among the
3753
- * souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
3754
- * `{ from: … }`, from any source (`off` is no declaration): the one named `conventional`
3755
- * (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace name);
3756
- * 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
3757
- * a resolution: oats.setup that reaches a soul through the workspace defaults alone is not seen. → the
3758
- * name to spawn it by: the bare name, else `<member>/<soul>` (`<package>/<soul>`), else
3759
- * `<member repo key>/<soul>`, the first that names this soul alone. */
3760
- function setupExpertOf(discovery, { conventional, capability }) {
3753
+ /** The framework's package soul that sets up a workspace (awebai/oats#1665 D1). */
3754
+ const FRAMEWORK_SETUP_SOUL = { package: "oats.framework", name: "oats-setup-expert" };
3755
+
3756
+ /** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314, #1665 D1), among
3757
+ * the souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
3758
+ * `{ from: … }`, from any source (`off` is no declaration), in this order: the workspace's own soul named
3759
+ * `conventional` (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace
3760
+ * name); else oats.framework's package soul `oats-setup-expert`; else the first by name; else null. A soul
3761
+ * is never chosen by its name alone. Only the soul's own declaration is read, never a resolution:
3762
+ * oats.setup that reaches a soul through the workspace defaults alone is not seen.
3763
+ * → null, or { soul, name, why }: `soul` is the name to spawn it by (the bare name, else
3764
+ * `<member>/<soul>` (`<package>/<soul>`), else `<member repo key>/<soul>`, the first that names this soul
3765
+ * alone); `name` is the instance name for the package soul (packageInstanceName), else null; `why` says
3766
+ * why that name is not the conventional one, else null. */
3767
+ function setupExpertOf(discovery, { conventional, workspaceName, capability }) {
3761
3768
  const candidates = soulCandidates(discovery);
3762
3769
  const declares = (entry) => {
3763
3770
  const caps = entry.definition?.capabilities;
@@ -3766,13 +3773,35 @@ function setupExpertOf(discovery, { conventional, capability }) {
3766
3773
  };
3767
3774
  const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
3768
3775
  const entries = candidates.map((c) => c.entry).sort((a, b) => order(a.name, b.name) || order(qualifiedSoulName(a), qualifiedSoulName(b)));
3769
- const chosen = (conventional && entries.find((e) => e.name === conventional && declares(e))) || entries.find(declares);
3776
+ const isFrameworkSoul = (e) => e.package === FRAMEWORK_SETUP_SOUL.package && e.name === FRAMEWORK_SETUP_SOUL.name;
3777
+ const chosen = (conventional && entries.find((e) => e.name === conventional && typeof e.package !== "string" && declares(e)))
3778
+ || entries.find((e) => isFrameworkSoul(e) && declares(e))
3779
+ || entries.find(declares);
3770
3780
  if (!chosen) return null;
3771
3781
  // The shortest name a spawn resolves to exactly this soul: two members can share a repository
3772
3782
  // basename (github.com/a/agents, github.com/b/agents), so the last form is the full repo key.
3773
3783
  const forms = [chosen.name, qualifiedSoulName(chosen), ...(typeof chosen.package === "string" ? [] : [`${chosen.repoKey}/${chosen.name}`])];
3774
3784
  const only = (name) => { const hits = candidates.filter((c) => c.matches(name)); return hits.length === 1 && hits[0].entry === chosen; };
3775
- return forms.find(only) ?? forms[forms.length - 1];
3785
+ const soul = forms.find(only) ?? forms[forms.length - 1];
3786
+ return { soul, ...(isFrameworkSoul(chosen) && workspaceName ? packageInstanceName(discovery, workspaceName) : { name: null, why: null }) };
3787
+ }
3788
+
3789
+ /** The instance name the framework's setup soul is spawned by, for the workspace `workspaceName`:
3790
+ * `<workspace>-oats-setup-expert`; `<workspace>-oats-setup` when a soul of this workspace already holds
3791
+ * that name (spawn refuses an instance name that is a soul's); else none, and spawn names it. A name
3792
+ * over the instance-name limit is none too: onboarding never refuses on a long workspace name.
3793
+ * → { name, why }, `why` null for the conventional name. */
3794
+ function packageInstanceName(discovery, workspaceName) {
3795
+ const souls = new Set();
3796
+ for (const m of discovery.members || []) for (const s of m.souls || []) if (typeof s?.name === "string") souls.add(s.name);
3797
+ for (const x of discovery.external || []) if (typeof x?.soul?.name === "string") souls.add(x.soul.name);
3798
+ for (const s of discovery.packageSouls || []) if (typeof s?.name === "string") souls.add(s.name);
3799
+ const conventional = `${workspaceName}-oats-setup-expert`, fallback = `${workspaceName}-oats-setup`;
3800
+ const shared = "and an instance may not share a soul's name";
3801
+ if (conventional.length > MAX_INSTANCE_NAME) return { name: null, why: `no --name: ${conventional} would be ${conventional.length} characters, over the ${MAX_INSTANCE_NAME}-character instance-name limit; spawn names it` };
3802
+ if (!souls.has(conventional)) return { name: conventional, why: null };
3803
+ if (!souls.has(fallback)) return { name: fallback, why: `named ${fallback}: this workspace has a soul named ${conventional}, ${shared}` };
3804
+ return { name: null, why: `no --name: this workspace has souls named ${conventional} and ${fallback}, ${shared}; spawn names it` };
3776
3805
  }
3777
3806
 
3778
3807
  /** `oats onboard <dir> [--workspace <ref>] --check`: what onboarding <dir> here would meet, read-only (the
@@ -614,6 +614,42 @@ When the program has changed, the launch runs the new one and says so: a warning
614
614
  in the answer and a `launch-warning` event in the home, both naming the path the
615
615
  hooks were given and the path it runs.
616
616
 
617
+ A spawn hook also gets `OATS_SPAWNER_HOME` (feature `spawn-attribution`): the
618
+ absolute home of the instance whose session ran the spawn, as the kernel
619
+ validated it and recorded it in `instance.json` `spawnedBy`
620
+ ([Spawned by](desktop-cli-api.md#spawned-by)). The hook's own
621
+ `OATS_INSTANCE_HOME` is the new instance's, so this is how a provider learns
622
+ who spawned it. Unlike `spawnOrigin`, which is informational, it selects who
623
+ signs: a messaging capability that attributes identities issues the new one
624
+ from this spawner, and from the deployment's own agent when it is absent. It is set only for a spawn
625
+ hook, and only when there is a spawner. It is absent when a person spawned (a
626
+ shell, the Desktop, an automation), when the caller's session was found gone,
627
+ when the caller's home is another deployment's, and for a `--server` spawn
628
+ whose caller is not a live home on that host. A spawner whose session cannot
629
+ be read is kept. It is independent of `--relation` and of `parentInstance`.
630
+ It is reserved like `OATS_HARNESS_EXECUTABLE`: a launch configuration, a
631
+ trigger or a hook's `env` cannot set it, an inherited value is dropped from
632
+ every hook's environment, from the environment a launch or a tmux server
633
+ starts with and from a scheduled job's, and it never reaches the harness's
634
+ pane, even from an existing server's environment. The kernel reads the caller from its environment only, so a harness that
635
+ strips its session's environment reads as a person's spawn: that changes the
636
+ recorded parent, never the human.
637
+
638
+ Read its absence as a person's spawn only when the kernel lists
639
+ `spawn-attribution` (`oats version --json` `features`): an older kernel never
640
+ sets it, so there absence says nothing. A provider gates the behaviour that
641
+ depends on it on that feature at run time, not with `compatibility.oats`,
642
+ which would refuse every capability of the package on an older host.
643
+
644
+ A messaging capability may record, in the served identity it records
645
+ (`identity` in its hook meta), an optional `attribution: {mode:
646
+ "human"|"none"|"unknown", human: {id, label}|null, parent: {id}|null}`. The
647
+ kernel never interprets its strings; it shows the human's `label` as
648
+ `attributedHuman` on status rows, read through the messaging slot under a
649
+ waiting claim's message rule ([Attributed human](desktop-cli-api.md#attributed-human)).
650
+ Absent means today's behaviour. `spawnedBy` and `attribution` report: no
651
+ kernel decision reads them.
652
+
617
653
  A dispatched command (`oats <namespace> <command>`, from an instance home or
618
654
  from the deployment directory) receives:
619
655
 
@@ -1196,6 +1232,15 @@ own dialog, and the kernel can't see which load. `reported` doesn't mean every
1196
1232
  dialog: [What a hold leaves open](schedules.md#what-a-hold-leaves-open) names what
1197
1233
  it can't see, the Claude dialogs that fire no hook among them.
1198
1234
 
1235
+ **A pi home with no provider** (oats.core 2.12.0). pi starts with no provider, takes
1236
+ its prompt and shows no error, so the home reads as running while nothing happens.
1237
+ On a real pass, spawn and launch hooks run `OATS_HARNESS_EXECUTABLE --list-models`,
1238
+ bounded at 3 s, and warn only when pi answers "No models available". The warning
1239
+ never refuses. No executable handed, a failed or slow probe, or any other answer
1240
+ says nothing. The hook sees the calling process's environment, not the pane's, so
1241
+ a pi folder (`PI_CODING_AGENT_DIR`) or key that only the launch or the pane has can
1242
+ warn on a pi that works.
1243
+
1199
1244
  **One home per settings file.** The launch hook bakes the home it writes the
1200
1245
  settings for into every command, as its real path (oats.core 2.4.1). The
1201
1246
  script acts only when the session's `$OATS_INSTANCE_HOME` names that same
@@ -168,6 +168,7 @@ see the [official catalog](official-catalog.md) for current pins.
168
168
  | `status-liveness` | the local liveness on `oats status --json` instance rows is complete: `running` and `runtimeState` are read live at every call, from the row's recorded tmux server under the pane and shell-descendant rule, with `false` for a shell only on positive evidence and `null` when the reading is inconclusive ([The roster](#the-roster-oats-status---json)). A client needs no liveness probe of its own beside the roster where the probe lists it, whether the read goes through the warm reader or the CLI. Independent of `warm-reader` | |
169
169
  | `wake-hold` | a scheduled wake sends no key while the home has a live `permission`, `question` or unknown-reason claim, or a claims read that can't be trusted: the run is `skipped`, `reason: "waiting-on-you"`, `pending: true`, with `held` ([A held wake](schedules.md#a-held-wake)); the `wake-held` event ([the event kinds](#events)); `wakeHold` on every successful `session inspect --json` ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)), from the hook answer `dialogClaims` ([Commands and hooks](capabilities.md#commands-and-hooks)). Gate on the feature, then on `wakeHold`: the feature says this kernel holds, `wakeHold` whether this home's dialogs become claims, and `unknown` is not covered | |
170
170
  | `lifecycle-claim-start` | every `oats session start` and `oats session restart`, and a scheduled start, holds the home's lifecycle claim for the whole start (#1602), as `details.action: "start"`: a retire, a stop apply or an upgrade apply that arrives while it runs is refused `E_LIFECYCLE_BUSY` with `details.action: "start"`; the start or restart is refused `E_INSTANCE_RETIRING` beside a retire and `E_LIFECYCLE_BUSY` (with `details.holder` and `details.action`) beside a stop or an upgrade, before any effect; two starts still answer `E_SESSION_START_BUSY` ([Commands that meet on one home](#lifecycle-pairs)). A restart holds one claim across its stop and its launch. A kernel without it takes no claim for these, and reads a `start` holder as a retire | |
171
+ | `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
171
172
 
172
173
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
173
174
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -996,23 +997,35 @@ same argument, given once). The ref is checked before anything is written.
996
997
  existing clone (the `clones:` entry, else `<dir>/<name>`), else where to
997
998
  clone it: `<dir>/<name>`, or `<dir>/agents-repo` for a member named
998
999
  `agents`. `url` is `null` when unknown.
999
- - `next.spawn` is `oats spawn <soul> --dir <dir>` naming the workspace's
1000
- OATS setup expert, else `null` (OATS 0.61.0; before it, only a soul named
1001
- `oats-operator-expert` was named). Among the souls onboarding lists
1002
- (confirmed members', external and package souls; standalone, the
1003
- repository's own), the setup expert is:
1004
- 1. the soul named `<workspace name>-oats-setup-expert` that declares
1005
- `oats.setup`, where the workspace name is the `name:` of
1000
+ - `next.spawn` is a command string, `oats spawn <soul> --dir <dir>
1001
+ [--name <instance>]`, naming the workspace's OATS setup expert, else
1002
+ `null` (OATS 0.61.0; before it, only a soul named `oats-operator-expert`
1003
+ was named). Among the souls onboarding lists (confirmed members', external
1004
+ and package souls; standalone, the repository's own), the setup expert is:
1005
+ 1. the workspace's own soul named `<workspace name>-oats-setup-expert`
1006
+ that declares `oats.setup`, where the workspace name is the `name:` of
1006
1007
  `oats-workspace.yaml` (`sync.workspace.name`); a standalone view has no
1007
1008
  workspace name, so this step does not apply there;
1008
- 2. otherwise the first soul by name that declares `oats.setup`;
1009
- 3. otherwise none: `null`.
1009
+ 2. otherwise `oats.framework`'s package soul `oats-setup-expert`, when it
1010
+ declares `oats.setup`;
1011
+ 3. otherwise the first soul by name that declares `oats.setup`;
1012
+ 4. otherwise none: `null`.
1010
1013
 
1011
1014
  A soul declares `oats.setup` when its own `soul.yaml` names it under
1012
1015
  `capabilities:` as `{ from: … }`, from any source (`package`, `here` or a
1013
1016
  member key); `oats.setup: off` does not count. A soul is never chosen by
1014
- its name alone: one named `<workspace name>-oats-setup-expert` that does
1015
- not declare `oats.setup` falls through to step 2.
1017
+ its name alone: a soul named `<workspace name>-oats-setup-expert` or
1018
+ `oats-setup-expert` that does not declare `oats.setup` falls through to
1019
+ the next step.
1020
+
1021
+ Only the package soul of step 2 gets `--name`: `<workspace
1022
+ name>-oats-setup-expert`; `<workspace name>-oats-setup` when a soul of the
1023
+ workspace already holds the first name (spawn refuses an instance name that
1024
+ is a soul's); none when that is taken too, or when the name would pass the
1025
+ 64-character instance-name limit. Spawn then names the instance itself;
1026
+ onboarding never refuses on a long workspace name. The text output says why
1027
+ a name other than the first is suggested. A soul of steps 1 and 3 is
1028
+ spawned with no `--name`.
1016
1029
 
1017
1030
  Only the soul's own declaration is read, not its resolved composition:
1018
1031
  `oats.setup` that reaches a soul only through the workspace's `defaults:`
@@ -2969,6 +2982,58 @@ Idempotent spawn replay returns the recorded value. Remote rows relay the
2969
2982
  host's value unchanged, including historical values, and use `null` when the
2970
2983
  host does not supply one. Consumers must allow for those historical meanings.
2971
2984
 
2985
+ <a id="spawned-by"></a>
2986
+ ### Spawned by
2987
+
2988
+ From feature `spawn-attribution`, every new home records `spawnedBy`: the
2989
+ instance whose session ran the spawn, `{instance, home}` (the canonical
2990
+ absolute home), or `null`. `instance.json` and the `spawned` event's `data`
2991
+ carry it as recorded. The `oats status --json` row carries it only in that
2992
+ shape: an `instance` that is an instance name and an absolute `home`, and no
2993
+ other key; anything else (a hand-edited record) reads `null`. A home spawned
2994
+ before the feature has no key on its row. It is apart from lineage: `parentInstance`, `relation`
2995
+ and `relativeTo` say nothing about it, and a spawn with `--relation unrelated`
2996
+ from an instance still has a spawner.
2997
+
2998
+ It is read by the same check as [Spawn origin](#spawn-origin), plus the
2999
+ spawner's liveness. The caller is the instance that check confirms; the
3000
+ kernel then reads its session by its own liveness read (the `running` of
3001
+ `oats session inspect`, feature `session-inspect-running`, and of status
3002
+ rows), which has three answers:
3003
+
3004
+ - **Running:** the spawner is that instance.
3005
+ - **Found gone** (a fallback shell, a dead or absent pane, a home that never
3006
+ launched, or its tmux server gone): `null`.
3007
+ - **Cannot tell** (its tmux server cannot be read, its session receipt cannot
3008
+ be used): the spawner is kept. As far as anyone knows, that instance runs
3009
+ this command. The spawn is never refused.
3010
+
3011
+ So `spawnedBy` non-null implies `spawnOrigin: "instance"`, and
3012
+ `spawnOrigin: "instance"` with `spawnedBy: null` means the spawner's session
3013
+ was found gone. `spawnOrigin: "operator"` always has `spawnedBy: null`: a
3014
+ person's shell, the Desktop, an automation (a scheduled job's environment
3015
+ carries no instance), and a home of another deployment. A `--server` spawn
3016
+ sends no caller environment to the host, so its spawner is `null` unless the
3017
+ caller is a live home on that host.
3018
+
3019
+ Limits:
3020
+
3021
+ - It reads the environment only, so a harness that strips its session's
3022
+ environment reads as a person's spawn. That changes the recorded parent,
3023
+ never the human.
3024
+ - The caller is read from an unauthenticated environment, so any process of
3025
+ the same OS user can name a live instance as its spawner. That is accepted
3026
+ under the custody answer: a convention under the same OS user, not a
3027
+ boundary.
3028
+ - `spawnedBy` and the messaging identity's `attribution`
3029
+ ([Attributed human](#attributed-human)) report, and no kernel decision
3030
+ reads them.
3031
+ - `spawnedBy` is written once, at spawn. Retire's lineage repair doesn't
3032
+ touch it, and it can name a home that no longer exists.
3033
+
3034
+ Spawn hooks get it as `OATS_SPAWNER_HOME` when it is not `null`
3035
+ ([capabilities.md](capabilities.md#commands-and-hooks)).
3036
+
2972
3037
  <a id="spawn-errors"></a>
2973
3038
  ### Spawn errors
2974
3039
 
@@ -3335,7 +3400,7 @@ its absence.
3335
3400
  read** (OATS 0.52.0) is listed like every other, and one such home never
3336
3401
  fails the listing. Its row has the fields of a home with no `instance.json`
3337
3402
  and nothing from the record: `instance`, `home`, the Desktop facts
3338
- (`startedAt`, `identityAddress`, `modelFrom`, each `null`), `waitingOnYou:
3403
+ (`startedAt`, `identityAddress`, `modelFrom`, `attributedHuman`, each `null`), `waitingOnYou:
3339
3404
  null`, `rollbackIncomplete` and `retirePending` when present, and `running:
3340
3405
  null` with `runtimeState: "unreachable"` and `runtimeError:
3341
3406
  "E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json cannot be read
@@ -3553,6 +3618,26 @@ restart, else `createdAt` for a launched home, else `null`. `modelFrom` is
3553
3618
  `"harness-default"`, or `null` for an older home. `identityAddress` is the
3554
3619
  messaging identity's `address` (else `alias`), or `null`.
3555
3620
 
3621
+ <a id="attributed-human"></a>
3622
+ **Attributed human** (feature `spawn-attribution`): `attributedHuman` is on
3623
+ every instance row, the label of the human the instance's messaging identity
3624
+ is attributed to, or `null`. The messaging capability may record an optional
3625
+ `attribution` in the served identity it records (`identity`):
3626
+ `{mode: "human"|"none"|"unknown", human: {id, label}|null, parent: {id}|null}`,
3627
+ with opaque strings the kernel never interprets. The row reads it by slot,
3628
+ never by name: only the identity of the capability whose layer is `messaging`
3629
+ counts. The row's `identity` falls back to any capability that recorded one;
3630
+ this never does, so no other capability can name a human on a row.
3631
+ It is the `label` when `mode` is `"human"`, else `null`; an absent
3632
+ `attribution` is `null` too, never shown as "none". The label is untrusted
3633
+ text, held to a waiting claim's `message` rule ([Waiting on you](#waiting-on-you)):
3634
+ one line of 1 to 200 characters with no refused character (a control
3635
+ character, a line break, a bidi control), else `null`. An omitted `human` or
3636
+ `parent` is `null`. A malformed `attribution` (an unknown `mode`, a `human` without a
3637
+ string `id` and `label`, a `parent` without a string `id`) reads as absent and
3638
+ never fails the row. `identity` on the row and in `oats inspect` carries the
3639
+ `attribution` as recorded.
3640
+
3556
3641
  <a id="the-remote-roster-oats-server-roster---json"></a>
3557
3642
  ### The remote roster (`oats server roster --json`)
3558
3643
 
@@ -3627,7 +3712,8 @@ route target:
3627
3712
  `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
3628
3713
  `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
3629
3714
  `relativeTo` and `spawnOrigin`, and (relayed from 0.42.1) `work`, `repo`,
3630
- `branch`, `modelFrom`, `soul` and `modules`, are always present, `null`
3715
+ `branch`, `modelFrom`, `soul` and `modules`, and (feature
3716
+ `spawn-attribution`) `attributedHuman` and `spawnedBy`, are always present, `null`
3631
3717
  when the host does not supply them (an older host, a fact it never
3632
3718
  recorded, or a saved route the host no longer lists). Each is the
3633
3719
  [local row's](#the-roster-oats-status---json) fact of the same name,
@@ -3635,7 +3721,10 @@ route target:
3635
3721
  is a path on the host, never read here, and `soul` and `modules` are the
3636
3722
  host's own drift observation (against its own members and lock), not
3637
3723
  recomputed: `modules` is the drift rows, or the recorded map when the host
3638
- could not read its workspace, as on a local row.
3724
+ could not read its workspace, as on a local row. `attributedHuman` passes
3725
+ the [local row's](#attributed-human) label rule again on this side, and
3726
+ `spawnedBy` the [local row's](#spawned-by) shape rule: a value either
3727
+ refuses is `null`.
3639
3728
  - **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
3640
3729
  only when the host's kernel reports it: a row from a host before 0.40.0,
3641
3730
  and a saved route the host did not list, have no such key. Absent means
@@ -4482,8 +4571,13 @@ oats instance attention [--message <text>] [--clear] --json
4482
4571
  - **Where it shows.** `waitingOnYou` on the events read, on `oats status
4483
4572
  --json` instance rows (running rows only) and on `oats session inspect
4484
4573
  --json` (beside `state`, whose enum is unchanged; `null` unless the harness
4485
- is running). Plain `oats status` prints `! needs input (<reason>):
4486
- <message>` under a running instance's row while it holds a claim.
4574
+ is running). Plain `oats status` prints `! needs input (<reason>) since
4575
+ <start>, <elapsed>: <message>` under a running instance's row while it holds
4576
+ a claim (the message and its colon are omitted when absent). The start is
4577
+ local to the CLI machine: `HH:MM` today, `Mon D HH:MM` on another day in
4578
+ the same year, or `YYYY-MM-DD HH:MM` in another year. Elapsed time is floored
4579
+ to `under a minute`, `N min`, `N h` or `N d`. A future start omits elapsed
4580
+ time; an unparseable start retains the line without any time.
4487
4581
  - **Cost.** To compute the field, `oats status` reads the home log of each
4488
4582
  running row (the workspace log only when the home log is absent), with
4489
4583
  the same bounded read as the events read: at most the last 4 MiB, so a
package/docs/desktop.md CHANGED
@@ -153,7 +153,33 @@ recently added workspaces there, once.
153
153
  opened, or your home directory when there is none (never ~/Downloads);
154
154
  **Choose oats…** opens in the directory of the chosen or discovered CLI.
155
155
 
156
- Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
156
+ Launch flags for scripted use: `--dir <workspace>`, `--instance <name>` and
157
+ `OATS_DESKTOP_PORT`.
158
+
159
+ ### Opening on an instance
160
+
161
+ `--instance <name>` beside `--dir <deployment>` opens the deployment's window
162
+ with that instance selected in the roster, as **Show in roster** selects it:
163
+ its row is revealed (a collapsed parent or the Background section opens) and
164
+ takes the keyboard focus. Press Enter to open its terminal. On a first launch
165
+ and on a launch while Desktop runs, it behaves the same way.
166
+
167
+ - **It only selects.** Nothing starts, attaches or is written, and Desktop
168
+ reads nothing for it beyond the roster reads it makes anyway.
169
+ - **The name must be an instance name**, the one `oats spawn --name` takes. Any
170
+ other value is ignored, and the window says the instance named at launch
171
+ isn't a valid instance name, without repeating the value.
172
+ - **Only the `--dir` deployment's own instances count.** Its other machines and
173
+ other workspaces never match. A name that isn't there yet (a spawn still
174
+ finishing) is waited for, over the roster's next reads, for about 30
175
+ seconds; then the window says "No instance <name> in this workspace". A name
176
+ two of its instances share selects nothing, and the window says so.
177
+ - **Your choice wins.** Selecting anything, typing or clicking while it waits
178
+ drops it. A later launch's `--instance` replaces it.
179
+ - Without `--dir`, with a `--dir` that isn't a deployment, or from a folder
180
+ that is one but no `--dir`, `--instance` is ignored and the launch behaves
181
+ as it would without it. A Desktop older than this one ignores it too, and
182
+ opens the workspace.
157
183
 
158
184
  ### One window per workspace
159
185
 
@@ -182,7 +208,8 @@ workspace on a server: `name — server`).
182
208
  to restore, one window opens on the last workspace you used.
183
209
  - **Launching again.** Running the app again (`open -a "OATS Desktop" --args
184
210
  --dir <deployment>`, or from inside a deployment) adds that deployment if
185
- needed and brings its window to the front, opening one if it has none. Any
211
+ needed and brings its window to the front, opening one if it has none, with
212
+ its `--instance` selected ([Opening on an instance](#opening-on-an-instance)). Any
186
213
  other launch brings the most recently used window to the front. A launch of
187
214
  another version also offers to restart into it ([Updating](#updating)).
188
215
  - **Closing.** Closing a window leaves the other windows, and their
@@ -2,8 +2,9 @@
2
2
 
3
3
  **The quick way:** the README's [Start here](../README.md#start-here): your
4
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
5
+ it. It installs OATS, creates your workspace and its team (or joins an
6
+ existing workspace), and spawns the workspace's setup expert, `oats.framework`'s
7
+ `oats-setup-expert`, which does the rest with you. This page is the manual
7
8
  path, for writing a workspace by hand.
8
9
 
9
10
  The model is in [workspaces.md](workspaces.md), packages in
@@ -28,8 +28,9 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
28
28
  through the home's `oats` link, before any PATH or global lookup (the
29
29
  order is in [its README](../packages/pi/README.md)).
30
30
  - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
31
- `oats.support` and `oats.knowledge-theory` capabilities and the
32
- `knowledge-theory-expert` soul,
31
+ `oats.onboarding`, `oats.support` and `oats.knowledge-theory`
32
+ capabilities and the `knowledge-theory-expert` and `oats-setup-expert`
33
+ souls,
33
34
  released as a package under its own `oats-framework/v<version>` tags.
34
35
  `oats.core` is the one with executables: its spawn and launch hook and the
35
36
  Claude Code waiting emitter (`capabilities/oats-core/bin/`).
@@ -543,7 +544,7 @@ A pull request that touches `packages/tui/`, `packages/client/`, a
543
544
  `test/tui-*.test.mjs` file or the workflow itself also runs
544
545
  [`tui-macos.yml`](../.github/workflows/tui-macos.yml): every TUI test file,
545
546
  `packages/tui/test/*.test.mjs` and `test/tui-*.test.mjs`, one file at a time
546
- and each test within five minutes, on `macos-14` with tmux installed, in about
547
+ and each test within five minutes, on `macos-15` with tmux installed, in about
547
548
  five minutes. Its last step fails the run if a test left a tmux server on the
548
549
  default `oats` socket, as a hand-started run checks after each file; it does
549
550
  not give each file a process group of its own, as a hand-started run does. The
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.7.0
44
- oats.aweb: v1.32.1
44
+ oats.aweb: v1.33.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -246,7 +246,7 @@ These are constants of the scripts, not inputs:
246
246
  | time for one file, then its process group is killed | 5 minutes | 20 minutes |
247
247
  | time for the job | 60 minutes | 240 minutes |
248
248
  | wait for the user manager | none | 60 seconds at the validation step |
249
- | runner | `macos-14` (arm64), Node 22 | `ubuntu-24.04` (x64), Node 22 |
249
+ | runner | `macos-15` (arm64), Node 22 | `ubuntu-24.04` (x64), Node 22 |
250
250
 
251
251
  A Linux file gets 20 minutes because the files that qualify the record
252
252
  capture at scale ([#1108](https://github.com/awebai/oats/issues/1108)) run
@@ -9,10 +9,10 @@ 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.17.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.19.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
13
13
  | `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
14
+ | `oats.aweb` | `v1.33.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.18.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.1.0` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.7.0`, `5.7.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.7.0` or `oats-framework/v1.17.0`) and the payload path. An id
54
+ convention (`v5.7.0` or `oats-framework/v1.19.0`) 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.17.0
77
+ oats.framework: v1.19.0
78
78
  oats.okf: v5.7.0
79
- oats.aweb: v1.32.1
79
+ oats.aweb: v1.33.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.32.1 # a catalog version
137
+ oats package add oats.aweb v1.33.1 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.7.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.17.0", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.19.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.17.0`
362
- resolves to tag `oats-framework/v1.17.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.19.0`
362
+ resolves to tag `oats-framework/v1.19.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -222,7 +222,7 @@ and packages it depends on, and what its entry points call of a cache.
222
222
  version of an id from the row, so it refuses a step without it.
223
223
 
224
224
  **`release.yml` and `build-installers.yml` name their runners by version
225
- too** (`ubuntu-24.04`, as they name `macos-14`), never by a label that GitHub
225
+ too** (`ubuntu-24.04`, as they name `macos-15`), never by a label that GitHub
226
226
  moves to another system by itself (`ubuntu-latest`). The Linux installers are
227
227
  built on that runner, and what they need of a system follows the system that
228
228
  built them.
@@ -231,7 +231,7 @@ break on the new system shows in pull-request CI first and not at a release.
231
231
 
232
232
  The labels `release.yml` and `build-installers.yml` may name are a list beside
233
233
  the table of actions in `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
234
- `macos-14`. Every job of the two runs on a label of that list, and both build
234
+ `macos-15`. Every job of the two runs on a label of that list, and both build
235
235
  on the same Linux. A label is added to the list by whoever decides the runner,
236
236
  as an action's row is by whoever read it.
237
237
 
@@ -401,7 +401,7 @@ DMG/ZIP/AppImage/DEB artifacts exist, both packaged macOS `.app` bundles
401
401
  pass strict deep codesign verification of their complete ad-hoc signatures
402
402
  (`codesign --verify --deep --strict`), node-pty's packaged `spawn-helper` is
403
403
  executable, and node-pty loads and spawns under the packaged Electron ABI.
404
- The macOS x64 leg cross-builds on macos-14 and installs Rosetta 2 so that its
404
+ The macOS x64 leg cross-builds on macos-15 and installs Rosetta 2 so that its
405
405
  x64 Electron + node-pty ABI probe really executes; a wrong-architecture
406
406
  native module fails that leg.
407
407
 
@@ -480,8 +480,8 @@ always records `release.status: pending`.
480
480
  ## Releasing `oats.framework`
481
481
 
482
482
  The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
483
- `oats.support`, `oats.knowledge-theory`) is not published by `release.yml` or
484
- by this lane. A deployment takes it from this repository at the tag
483
+ `oats.onboarding`, `oats.support`, `oats.knowledge-theory`) is not published
484
+ by `release.yml` or by this lane. A deployment takes it from this repository at the tag
485
485
  `oats-framework/v<version>`, through the catalog ref or its workspace pin. A
486
486
  skill changed under `oats-package/` therefore reaches deployments only when
487
487
  that tag moves, whatever kernel version carried the change.