@awebai/oats 0.63.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.
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
@@ -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
@@ -2241,6 +2241,11 @@ containing them ships. For operator recovery, see
2241
2241
 
2242
2242
  ## Spawn
2243
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
+
2244
2249
  ### The preview
2245
2250
 
2246
2251
  ```text
@@ -2287,7 +2292,8 @@ it to a temporary copy (`soulFetched: true`).
2287
2292
  ([Instance names](#instance-names)). `home` and `worktree` (worktree mode,
2288
2293
  else `null`) are canonical: never derive paths.
2289
2294
  - `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
2290
- - `branch` defaults to `agents/<instance>` (`--branch` overrides); `base` is
2295
+ - In worktree mode, `branch` defaults to `agents/<instance>` (`--branch <b>`
2296
+ overrides); `base` is
2291
2297
  `--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
2292
2298
  soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
2293
2299
  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
@@ -2495,6 +2501,42 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2495
2501
  a silent `-2`.
2496
2502
  - The name is part of the decision.
2497
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
+
2498
2540
  <a id="spawn-errors"></a>
2499
2541
  ### Spawn errors
2500
2542
 
@@ -58,7 +58,7 @@ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
58
58
  a retained dead pane also reads `false`. A wrapper shell with a live non-shell
59
59
  descendant still reads `true`. Status shares session inspection's pane rule,
60
60
  with one batched pane read per socket/session and one lazy process scan across
61
- 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
62
62
  `running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
63
63
  inspect --json` reports the session a new spawn would open in as `session`
64
64
  (`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
@@ -1073,12 +1073,16 @@ oats session attach --home /abs/home --detach-key 'C-\'
1073
1073
  wrapper shell included; `false` for a fallback shell (`state: shell`, where
1074
1074
  `present` stays `true`), an absent or dead pane or a missing home
1075
1075
  (`stopped`) and a home that never launched (`not-launched`). It costs no
1076
- second observation: at most one process-table read, and only for a pane
1077
- whose own command is a shell. `running` is activity at the authorized
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
1078
1081
  endpoint. It does not say the agent is generating, idle, healthy or ready
1079
1082
  for input, nor that it consumed a wake, and it does not prove which
1080
- executable runs if a process inside the pane was replaced. When the
1081
- backend or the process table cannot be read, or the pane answer is
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
1082
1086
  malformed or split, inspect is an error as before, never `running: false`.
1083
1087
  That includes a tmux server that is gone (`no server running on` its
1084
1088
  socket, as after a reboot): status reads that row as `running: false`, and
@@ -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.2` (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.2`) 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.2
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.2", "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.2`
362
- resolves to tag `oats-framework/v1.13.2`. 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.
@@ -0,0 +1,105 @@
1
+ # OATS 0.64.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.63 Desktop refuses a 0.64.0 CLI. The
9
+ 0.64.0 Desktop accepts OATS CLIs `>=0.26.0 <0.65.0`.
10
+
11
+ - **The official catalog moves oats.framework 1.13.2 → 1.13.3** (oats.core
12
+ 2.6.5 and oats.setup 2.8.2, see Provider updates). The other packages are
13
+ unchanged. A deployment takes it by moving its `oats.framework` pin and
14
+ running `oats sync`. Only new spawns use it.
15
+
16
+ - **Coming from 0.61 or earlier:** do 0.62.0's Upgrade steps too (the capture
17
+ service's `oats setup`, once per user on each host, from that user's shell).
18
+
19
+ ## Changed
20
+
21
+ - **One way in: the README's "Start here" points to the
22
+ `oats-getting-started` skill**, which a person's own coding agent
23
+ downloads verbatim and follows ([#1314](https://github.com/awebai/oats/issues/1314)).
24
+ - **The skill is rewritten.** It asks one round of questions: the use case,
25
+ the existing repositories, the knowledge tools, new or existing
26
+ workspace, messaging, harness and deployment directory.
27
+ - **It installs what is missing,** then OATS Desktop and the CLI at the
28
+ same version (with the pi bridge, `@awebai/oats-pi`, when the harness is
29
+ pi). The Desktop comes from the release asset, downloaded with
30
+ `gh` and checked against `SHA256SUMS.txt` and its attestation; on Linux it
31
+ installs per user and shows in the app launcher.
32
+ - **The GitHub login** is gh's device flow, which the agent starts and the
33
+ person approves in their browser.
34
+ - **A new workspace** becomes a private repository holding the workspace
35
+ file, its membership and one thin soul,
36
+ `<workspace>-oats-setup-expert`, which holds `oats.setup` and has no
37
+ knowledge of its own, so it spawns on a machine before knowledge is set
38
+ up there. It takes the workspace's messaging, so it stays the
39
+ workspace's operator. **An existing workspace** is onboarded as it is;
40
+ when it has messaging, the skill sets it up on the machine before the
41
+ spawn, with an invite token the person types in their own terminal.
42
+ - **Then** the skill spawns the setup expert with the person's answers as
43
+ its task, and the expert does the rest (`/oats-setup-expert`,
44
+ oats.framework 1.13.0). An existing workspace without a setup soul gets
45
+ one first, from its owner, by pull request.
46
+ - The Desktop is started on the new deployment, and the TUI is offered.
47
+ - The person types only passwords, logins and tokens, and no secret passes through
48
+ the agent.
49
+
50
+ - `spawnOrigin` now describes the caller independently of lineage: valid
51
+ instance context in this deployment records `instance`; otherwise `operator`,
52
+ including operator spawns with `--parent`. Existing instances keep their
53
+ recorded values, whose older meaning followed the relation. Attribution is
54
+ informational and does not change permissions (#1371).
55
+
56
+ - Desktop: the command palette (⌘K / Ctrl+Shift+K) now shows the sidebar's
57
+ tree, with the sidebar's lines and state dots, ordered by the instance you
58
+ focused most recently. A group or a parent moves up when you focus any
59
+ instance under it, and a child stays under its parent. This replaces the
60
+ flat Recent group. The palette still opens on the agent you were on before,
61
+ and the sidebar keeps its own name order (#1383).
62
+
63
+ - **OATS Desktop accepts an `oats` CLI 0.64.x.** Its band is now
64
+ `>=0.26.0 <0.65.0`. 0.64 adds no new gate on the band: `spawnOrigin` keeps
65
+ its `instance`/`operator` values, which the Desktop passes through without
66
+ reading, and the Desktop already shows a fallback shell as `shell` (#1387).
67
+
68
+ ## Fixed
69
+
70
+ - Shared spawn help now lists the existing `--base <ref>` flag beside `--branch`
71
+ and explains its worktree-only scope and default to the soul commit observed
72
+ by spawn (#1370, #445).
73
+
74
+ - `oats spawn --help` and `oats help` now list the full existing spawn flag
75
+ inventory, including decision replay, scope, launch, child policy and wake
76
+ options, with compatibility and internal inputs labelled. Flag behavior is
77
+ unchanged (#1373).
78
+
79
+ - Status and session inspection now recognize a fallback shell when tmux
80
+ reports an empty or `unset` pane command, so a stopped harness no longer
81
+ appears to be running in that case (#1381).
82
+
83
+ ## Provider updates
84
+
85
+ - **oats.framework 1.13.3: oats.core 2.6.5 and oats.setup 2.8.2.** Text
86
+ only: neither capability's floor (`compatibility.oats`) changes.
87
+ - **`/oats-operate`** says what `spawnOrigin` records from OATS 0.64.0: the
88
+ caller's context (`instance` from a valid instance environment in this
89
+ deployment, otherwise `operator`), independent of the relation. It is
90
+ attribution, not a permission check, and a remote spawn records the
91
+ host side. The skill also says how `--branch` and `--base` choose a
92
+ worktree's branch and start point
93
+ ([#1371](https://github.com/awebai/oats/issues/1371),
94
+ [#1370](https://github.com/awebai/oats/issues/1370)).
95
+ - **oats.setup names the right OATS version for the getting-started entry
96
+ path.** `/oats-setup-expert`, `/oats-setup-model` and the oats.setup
97
+ briefing said the `oats-getting-started` skill writes the setup expert's
98
+ hand-over and creates its soul from OATS 0.62.0. That skill first ships
99
+ in 0.64.0, and they now say so
100
+ ([#1314](https://github.com/awebai/oats/issues/1314)).
101
+
102
+ ## Documentation
103
+
104
+ - `docs/first-team.md` opens with the getting-started skill as the quick
105
+ way; the page remains the manual path.
@@ -306,6 +306,12 @@ soul would, run it from the deployment with `OATS_INSTANCE_HOME` and
306
306
 
307
307
  ### Spawn
308
308
 
309
+ `oats spawn --help` lists the existing spawn flags and their conditions; the
310
+ spawn section of `oats help` contains the same inventory. Both work outside a
311
+ deployment. Compatibility and internal inputs are labelled, including the
312
+ locally refused legacy instance selector. For preview confirmation and receipt
313
+ replay, see the [spawn decision and apply contract](desktop-cli-api.md#the-decision).
314
+
309
315
  ```bash
310
316
  oats spawn release-manager --purpose cut-3.2 --task "…" # a soul of a confirmed member
311
317
  oats spawn release-manager --preview --json # decide everything, create nothing
@@ -384,8 +390,7 @@ Spawn lineage is **explicit** and relation-based:
384
390
  declares what the new instance IS to an existing one (`--parent <instance>` is
385
391
  sugar for `--relative-to <instance> --relation child`):
386
392
 
387
- - **child**: nests under the anchor: `parentInstance` = anchor,
388
- `spawnOrigin: instance`.
393
+ - **child**: nests under the anchor: `parentInstance` = anchor.
389
394
  - **parent**: the NEW instance becomes the anchor's parent: it inherits the
390
395
  anchor's old lineage slot, and the anchor's `instance.json` is re-pointed so
391
396
  its `parentInstance` is the new instance (a reviewer/maintainer of your work
@@ -400,15 +405,27 @@ sugar for `--relative-to <instance> --relation child`):
400
405
  when one exists; when the anchor is a root, the new instance records an
401
406
  explicit `siblingInstance` link so the cluster is still derivable from
402
407
  `oats status --json` (`parentInstance` + `siblingInstance` edges).
403
- - **unrelated** (default): no link, operator-origin, top-level.
408
+ - **unrelated** (default): no link, top-level.
404
409
 
405
410
  Attached-mode spawns are ALWAYS children of the owner of the shared work tree
406
411
  (the instance in whose home the tree is, as its `work/` or as one of its
407
412
  extra trees: see [`attached`](#attached--another-instances-tree)),
408
413
  because an attached agent serves that owner; relation flags other than a
409
- redundant child-of-owner are rejected. Any other spawn, including one from a
410
- shell that inherited an agent's environment variables, is operator-origin and
411
- appears top-level.
414
+ redundant child-of-owner are rejected.
415
+
416
+ `spawnOrigin` records the caller independently of these links. For new spawns
417
+ from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
418
+ `OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
419
+ otherwise it is `operator`. A stopped home counts. A shell, Desktop or console
420
+ caller without that context records `operator` even with `--parent`; an instance
421
+ caller records `instance` even without a relation. A shell inheriting valid
422
+ instance context also records `instance`. This is informational attribution,
423
+ not a security boundary or a permission check. Existing instances keep their
424
+ recorded value, including the relation-based meaning recorded by older kernels.
425
+ For a remote spawn (`--server`), attribution uses the host-side caller context;
426
+ caller identity is not forwarded, so the origin is normally `operator`.
427
+ See [the caller resolution rules](desktop-cli-api.md#spawn-origin).
428
+
412
429
  Agents spawning sub-agents should pass `--parent "$OATS_INSTANCE"` (or the
413
430
  relation that fits).
414
431
 
@@ -1623,6 +1640,9 @@ as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
1623
1640
  (`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
1624
1641
  [configuration.md](configuration.md)).
1625
1642
 
1643
+ `--branch <b>` overrides the branch name; `--base <ref>` overrides its start
1644
+ point. These options apply to worktree mode.
1645
+
1626
1646
  The branch starts at the commit of the soul's repository that the spawn
1627
1647
  observed (the one it resolved the soul at), not at what the clone has checked
1628
1648
  out: the clone may be a human's checkout or a shared reference, far behind.
package/docs/upgrading.md CHANGED
@@ -92,7 +92,8 @@ Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI
92
92
  Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
93
  release. Read 0.62.0's Upgrade section and keep this order: install the
94
94
  Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
- `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`), then that
95
+ `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
96
+ Desktop `>=0.26.0 <0.65.0`), then that
96
97
  release's CLI and matching pi bridge. Only **after
97
98
  installing that CLI**, run its setup conversion once per user on each host,
98
99
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.13.2 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.3 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
package/lib/core.mjs CHANGED
@@ -3696,6 +3696,30 @@ export function spawnInstance(root, agent, o = {}) {
3696
3696
  function localMissingForSpawn(agent) {
3697
3697
  return oatsError("E_LOCAL_MISSING", `spawning ${agent?.name ?? "an instance"} needs a workspace deployment (oats-local.yaml, found walking up from the deployment): a soul's capabilities are the workspace's resolution, prepared before the spawn — \`oats onboard\` creates the deployment`);
3698
3698
  }
3699
+ /** Informational caller attribution, never permission or lineage. Only consistent
3700
+ * runtime identity evidence resolving to an extant home in this deployment counts;
3701
+ * a stopped home still counts. Invalid evidence must not refuse a spawn. */
3702
+ function callerSpawnOrigin(root) {
3703
+ const name = process.env.OATS_INSTANCE, home = process.env.OATS_INSTANCE_HOME;
3704
+ if (name === undefined && home === undefined) return "operator";
3705
+ try {
3706
+ if (name !== undefined && !INSTANCE_NAME_RE.test(name)) return "operator";
3707
+ if (home !== undefined && !isAbsolute(home)) return "operator";
3708
+ let matches;
3709
+ if (home === undefined) {
3710
+ matches = findInstanceHomes(root, name);
3711
+ if (matches.length !== 1) return "operator";
3712
+ }
3713
+ const canonical = realpathSync(home ?? matches[0].home);
3714
+ // Name lookup's immediate-child check also applies to the agents root: an
3715
+ // instances/ directory symlinked to another deployment cannot qualify it.
3716
+ if (basename(dirname(canonical)) !== "instances" || dirname(dirname(dirname(canonical))) !== realpathSync(root)) return "operator";
3717
+ const record = readHomeRecord(canonical);
3718
+ if (record.state !== "record" || record.meta.instance !== basename(canonical) || (name !== undefined && record.meta.instance !== name)) return "operator";
3719
+ matches ??= findInstanceHomes(root, record.meta.instance);
3720
+ return matches.some((m) => realpathSync(m.home) === canonical) ? "instance" : "operator";
3721
+ } catch { return "operator"; }
3722
+ }
3699
3723
  export async function spawnInstanceAsync(root, agent, o = {}) {
3700
3724
  const it = spawnBody(root, agent, o);
3701
3725
  let step = it.next();
@@ -3714,6 +3738,8 @@ function unconfirmedSpawn(error) {
3714
3738
  return error;
3715
3739
  }
3716
3740
  function* spawnBody(root, agent, o = {}) {
3741
+ // Capture the caller before target scaffolding or hooks supply the new instance's identity.
3742
+ const spawnOrigin = callerSpawnOrigin(root);
3717
3743
  if (!o.prepared) throw localMissingForSpawn(agent);
3718
3744
  const deliver = (r) => r;
3719
3745
  const work = o.work || agent.work || "checkout";
@@ -3845,12 +3871,8 @@ function* spawnBody(root, agent, o = {}) {
3845
3871
  // never leaves a half-created home behind. ATTACHED mode is special by design
3846
3872
  // decision: an attached agent shares its owner's work tree and is ALWAYS the
3847
3873
  // owner's child — relation flags that say anything else are contradictory and
3848
- // rejected. Ambient env
3849
- // (OATS_INSTANCE) is deliberately NOT consulted: any shell
3850
- // opened inside an agent's tmux window inherits those vars, and env inheritance
3851
- // is not evidence of intent — human spawns from such shells were misattributed
3852
- // as instance-origin. Manual spawns land top-level unless a relation is
3853
- // explicitly given (operator directive).
3874
+ // rejected. Caller identity is attribution only: it never supplies a lineage
3875
+ // edge. Without an explicit relation a spawn stays top-level.
3854
3876
  const legacyParent = typeof o.parent === "string" && o.parent.trim() ? o.parent.trim() : undefined;
3855
3877
  let relation = typeof o.relation === "string" && o.relation.trim() ? o.relation.trim() : undefined;
3856
3878
  let relativeTo = typeof o.relativeTo === "string" && o.relativeTo.trim() ? o.relativeTo.trim() : undefined;
@@ -4900,7 +4922,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4900
4922
  siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
4901
4923
  relation: relation || undefined,
4902
4924
  relativeTo: relation ? relativeTo : undefined,
4903
- spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
4925
+ spawnOrigin,
4904
4926
  policy: { childSpawns: ownChildPolicy },
4905
4927
  ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo ?? null, number: o.triggerEvent.number ?? null, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile,
4906
4928
  // A capability source's event carries its declared fields (a pull request's never does).
@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
5
5
  import { performance } from "node:perf_hooks";
6
6
 
7
7
  const shells = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "login"]);
8
+ const isShellProcess = (name) => shells.has(basename(name).replace(/^-/, ""));
8
9
  function tmux(target, args, { exec = execFileSync, input, timeout = 10000, killSignal } = {}) {
9
10
  // launchd does not supply a UTF-8 locale. In that environment tmux replaces
10
11
  // the tab delimiters in list-panes output with underscores unless forced.
@@ -55,7 +56,16 @@ export function createSessionPaneInspector(io) {
55
56
  throw new Error("invalid tmux pane response");
56
57
  }
57
58
  let state = dead === "1" ? "stopped" : "unknown";
58
- if (dead === "0" && shells.has(command)) {
59
+ let shell = shells.has(command);
60
+ if (dead === "0" && (command === "" || command === "unset") && /^\d+$/.test(panePid)) {
61
+ // A missing tmux label can still be a fallback shell. Only the pane's
62
+ // own comm can establish that; an optional failed read stays unknown.
63
+ try {
64
+ const own = readProcesses().find(([, pid]) => pid === panePid);
65
+ shell = own ? isShellProcess(own[3]) : false;
66
+ } catch { /* missing process information is not proof of a fallback shell */ }
67
+ }
68
+ if (dead === "0" && shell) {
59
69
  // macOS tmux can report the wrapper shell while the harness is its child.
60
70
  // Only a shell with no non-shell descendants is a fallback prompt.
61
71
  if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
@@ -67,7 +77,7 @@ export function createSessionPaneInspector(io) {
67
77
  for (const [, pid, parent, name] of processes) {
68
78
  if (descendants.has(parent) && !descendants.has(pid)) {
69
79
  descendants.add(pid); changed = true;
70
- if (!shells.has(basename(name).replace(/^-/, ""))) active = true;
80
+ if (!isShellProcess(name)) active = true;
71
81
  }
72
82
  }
73
83
  }
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.13.2",
46
+ "ref": "oats-framework/v1.13.3",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.63.0",
3
+ "version": "0.64.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.64.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.65.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 64, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 65, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */