@awebai/oats 0.46.0 → 0.48.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.
@@ -0,0 +1,70 @@
1
+ # Qualified post-answer completion
2
+
3
+ ## Boundary and accepted risk
4
+
5
+ Only after exactly one recorded **submitted** development-channel Enter, under the existing qualified executable/version/platform/argv, exact-home consent, original home identity, pane/PID and 110x35 checks, may structural recognition complete observation. It never authorizes input. Existing exact completion families remain available, subject to the marker precedence below. No structural recognition before an answer, after any terminal outcome, or after failed/uncertain input.
6
+
7
+ An unknown dialog can retain the composer and footer and evade this finite marker list. The contract explicitly accepts that completion-reporting risk. Completion closes input authority permanently; it does not establish absence of every dialog, idle state, account admission, channel readiness, or task success. The observed spinner is an in-progress task turn, not an idle prompt. No spinner word, glyph or timing grammar is introduced.
8
+
9
+ ## Source provenance
10
+
11
+ Read-only pinned Claude Code 2.1.289 darwin-arm64 binary SHA256 `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`. [the source manifest](../lib/launch-prompt-fixtures/structural-completion.json) records exact byte intervals and SHA256s for every reference below. No extracted module enters the repository. These are source-derived rules, not additional observed captures.
12
+
13
+ ## Qualified input/footer rule — non-flag footer layout
14
+
15
+ This qualifies the non-Jt footer layout (`tengu_copper_thistle` false) in the pinned source. The flag-enabled layout chooses a single hint instead of this list; it is not separately qualified. A remote flag change can alter the footer without changing the binary and reduce matches; only exact listed shapes match, never additional shapes.
16
+
17
+ Input is the same compared text object, exactly 35 newline-terminated rows at 110x35, bounded to 64 KiB. No whitespace normalization, cropping, ANSI stripping, case folding or transcript rewrite. Reject embedded CR, ESC and other C0 controls except LF. All rows after the footer must be empty. The footer must be the last nonempty row, with this immediately preceding contiguous region:
18
+
19
+ 1. Exactly 110 U+2500 horizontal-line characters.
20
+ 2. Exactly U+276F followed by U+00A0 (`❯` plus NBSP), and nothing else: the actual empty composer row, not a prompt-like substring in prose.
21
+ 3. Exactly 110 U+2500 horizontal-line characters.
22
+ 4. The finite footer below.
23
+
24
+ This accepts the region at any row where all four rows fit, not a fixed transcript height. It refuses nonempty/multiline editor drafts, shell or screen-reader selectors, annotated borders, wrapped footers, notifications between editor and footer, status rows below the footer, and footer-less states. It deliberately does not cover every normal renderer configuration.
25
+
26
+ Source: `prompt-selector` s0/qK renders Z.pointer+NBSP for the ordinary non-screen-reader input; `prompt-symbol` pins Z.pointer to U+276F. `round-border-glyphs` pins top/bottom to U+2500; `prompt-border` BA and `editor-layout` HWe give top/bottom borders with left/right borders absent. The existing raw API captures and the actual retained Max frame corroborate the exact three input rows at 110 columns. `footer-layout` YHe/Oie gives paddingX=2, row width=110, gap=1, right status marginLeft=auto. The sanitized regression frame's input region is rows 11–14; its home-only sanitized derivative is regression input, not an exact spinner matcher.
27
+
28
+ ### Modes (complete list)
29
+
30
+ | Native mode | Exact left label | Allowed cycle suffix |
31
+ |---|---|---|
32
+ | default | `⏸ manual mode on` | absent only |
33
+ | plan | `⏸ plan mode on` | absent or ` (shift+tab to cycle)` |
34
+ | acceptEdits | `⏵⏵ accept edits on` | absent or same cycle suffix |
35
+ | bypassPermissions | `⏵⏵ bypass permissions on` | absent or same cycle suffix |
36
+ | dontAsk | `⏵⏵ don't ask on` | absent or same cycle suffix |
37
+ | auto | `⏵⏵ auto mode on` | absent or same cycle suffix |
38
+
39
+ `mode-map` Sr/DL/bie/qQo enumerates all six; `mode-symbols` pins the symbols; `footer-mode` kx adds literal ` on` when bare is absent. `footer-branches` dHe calls kx without bare and gates the default-keybinding cycle hint on non-default mode and ks. Unknown modes, custom keybindings and bare labels are unsupported.
40
+
41
+ After the mode/cycle label, accept only these exact suffixes, each independently enumerated: empty; ` · ← for agents`; ` · esc to interrupt`; ` · esc to interrupt · ← for agents`. For **default mode only**, also ` · ? for shortcuts` or ` · ? for shortcuts · ← for agents`. Sources: `footer-branches` dHe/EFt (escape interrupt, shortcut hint, ordering), `agent-hint` Cze (left-arrow for agents). No return-to-team-lead, task counter, voice, custom status or arbitrary suffix. The normal hints are not negative markers anywhere in the visible frame; an unsupported footer remains unsupported for structural reasons rather than because it contains a question mark or Esc.
42
+
43
+ The footer is exactly two ASCII spaces + left text + ASCII space gap + one right label from this complete list: `○ low · /effort`, `◐ medium · /effort`, `● high · /effort`, `◉ xhigh · /effort`, `◈ max · /effort`. `effort` bW/y8 and `mode-symbols` define these glyphs and labels. The right label ends at column 108 (two columns right padding are absent in tmux text); gap is exactly `108 - 2 - leftDisplayWidth - rightDisplayWidth`, and at least one. All enumerated glyphs are single-column in the qualified captured geometry. No `effort:` prefix, ultracode, missing effort, altered punctuation, or other effort value. Existing medium-only exact families remain exact; the additional finite effort rules are source-qualified here, not prior capture qualification.
44
+
45
+ ## Qualified negative marker table
46
+
47
+ ONLY after exactly one recorded submitted answer, each listed string is matched **case-sensitively as exact contiguous text anywhere in the visible frame**, before either exact or structural positive completion. It can conservatively block a transcript quoting a known question. No regex/question-word heuristic, case folding, line joining, general `?`, general `Esc`, or exemption for an unknown question. Wrapped or customized unknown questions remain within the explicitly accepted risk. Input prompt matching itself is unchanged: the initial qualified channel question must still be answerable before a submitted answer exists.
48
+
49
+ | Exact forms (each independently tested) | Pinned source reference |
50
+ |---|---|
51
+ | `Accessing workspace:`; `Quick safety check:`; `Yes, I trust this folder`; `No, continue without these permissions`; `No, exit` | trust / TrustDialog |
52
+ | `WARNING: Loading development channels`; `I am using this for local development` | channel confirmation |
53
+ | `Managed settings require approval`; `Yes, I trust these settings`; `No, exit Claude Code` | managed-settings |
54
+ | `Do you want to use this API key?`; `Detected a custom API key in your environment` | api-key |
55
+ | `Select login method:` | login |
56
+ | `Do you want to proceed?` | permission-question / o5 default question |
57
+ | `Do you want to allow this connection?` | connection-question |
58
+ | `Waiting for permission…` | permission-wait / QVe |
59
+ | `Enter to confirm`; `Esc to cancel` | confirmation-guide and key-hint B renderer; gateway/selection-dialog corroborate cancel literal |
60
+ | `esc to cancel` | lower-cancel + key-hint B with lower keyCase |
61
+ | `Enter to select` | selection-dialog literal |
62
+ | `Esc to exit` | managed-settings + key-hint B |
63
+
64
+ The historical local-JSX confirmation is not claimed covered by this list; its marker composition was not separately verified and remains an example of the accepted unknown-dialog risk. Real #712 child screens with missing effort and update/focus notices below the footer remain unqualified; the retained A2 frame has the required effort and no trailing notices.
65
+
66
+ This is the whole v1 marker set, **not a claim that these are all possible native questions**. Generic custom title/confirm labels can evade it. `? for shortcuts` and `esc to interrupt` are explicitly normal UI, never markers. No case-insensitive expansion to `enter to confirm`, `esc to exit`, etc. without another qualified table update.
67
+
68
+
69
+ Private retention and receipt-v2 collection rules are documented in
70
+ [execution targets](execution-targets.md#private-unmatched-launch-evidence).
@@ -9,14 +9,15 @@ 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.6.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.8.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
14
+ | `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
15
+ | `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
19
19
  | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
20
+ | `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
20
21
 
21
22
  Each package lives in its own `awebai/oats-*` repository except
22
23
  `oats.framework`, whose payload root is `oats-package/` here. A capability id
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v4.1.1`, `4.1.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 (`v4.1.1` or `oats-framework/v1.6.1`) and the payload path. An id
54
+ convention (`v4.1.1` or `oats-framework/v1.8.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.6.1
77
+ oats.framework: v1.8.0
78
78
  oats.okf: v4.1.1
79
- oats.aweb: v1.21.1
79
+ oats.aweb: v1.23.2
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.21.1 # a catalog version
137
+ oats package add oats.aweb v1.23.2 # 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
  ```
@@ -339,11 +339,11 @@ A soul that names one of the package's capabilities with
339
339
  "policy": "docs/official-catalog.md",
340
340
  "packages": {
341
341
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
342
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.1", "path": "oats-package" }
342
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
343
343
  }
344
344
  }
345
345
  ```
346
346
 
347
- `ref` carries the tag convention: a workspace's `oats.framework: v1.6.1`
348
- resolves to tag `oats-framework/v1.6.1`. Resolving through the catalog never
347
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.8.0`
348
+ resolves to tag `oats-framework/v1.8.0`. Resolving through the catalog never
349
349
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,93 @@
1
+ # OATS 0.47.0
2
+
3
+ 2026-10-07
4
+
5
+ ## Changed
6
+
7
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.48.0`.** The compatibility band
8
+ admits 0.47; existing feature gates remain unchanged.
9
+
10
+ - **Desktop: "Retire instance" says what will happen, and shows it happening.**
11
+ The roster row's menu item is **Retire instance…** (was "Remove instance…"),
12
+ and the confirmation reads **Retire <name>?** with a **Retire instance**
13
+ button. Stop shares the same dialog: **Stop <name>?**, **Stop session**
14
+ (**Stop sessions** for several).
15
+ - **Plain words.** **What will happen** lists the consequences from the
16
+ plan: the session stops, children stop first and are kept, a recovery copy
17
+ of uncommitted work is saved before the home folder is deleted, the
18
+ worktree is kept on its branch or deleted, and branches and pull requests
19
+ are not changed. **Current state** shows Running / Not running / Unknown,
20
+ the uncommitted work and the branch. The plan's time is shown as an age
21
+ ("Observed just now"), with no timestamps or kernel vocabulary.
22
+ - **Loading and progress.** The dialog opens with a skeleton and "Checking
23
+ what retiring <name> will do…". Changing **Also delete the worktree**
24
+ keeps the facts on screen until the new plan replaces them. Confirming
25
+ shows "Retiring <name>…" with a spinner, and says you can close the window
26
+ while retirement continues. Success ends with "<name> retired", a short
27
+ summary (where the worktree and the recovery copy are) and **Done**.
28
+ - **No unexplained disabled controls.** A control appears only in the
29
+ phase where it can act, and a waiting confirm button names why beside it.
30
+ **Cancel** becomes **Close** once something has been sent, since closing
31
+ never cancels it. **Refresh plan** is gone: **Check again** re-reads the
32
+ plan, and after a failure **Review again** does. An unconfirmed outcome
33
+ offers **Check again**, which resubmits the same confirmation.
34
+ - **The worktree option** appears only for an instance with its own
35
+ worktree. When checked, a warning says how many uncommitted changes the
36
+ folder holds and that the branch stays.
37
+ - **Row menu.** While one of its actions runs, the menu button stays
38
+ focusable and says "Waiting for <action> to finish". A failed action posts
39
+ a notification, with the error in Details, instead of an alert.
40
+ - The lifecycle messages are reworded in plain language, for example "OATS
41
+ didn't confirm the result. Check again before assuming nothing happened."
42
+ Their codes and the confirmation contract are unchanged. See
43
+ [Desktop Stop and Retire confirmations](../../packages/desktop/docs/desktop-lifecycle-confirmations.md#ui-states).
44
+
45
+ - **oats.framework 1.8.0: the new oats.support 1.0.0.** Instruction text
46
+ only; no kernel, schema or provider contract changes.
47
+ - **oats.support 1.0.0, a support desk role (new).** A resource-only
48
+ capability for a soul that anyone may reach. It takes in support
49
+ requests, turns each one into one ticket, hands each ticket to the
50
+ project's support maintainer, and keeps the requester informed.
51
+ Everything a requester sends is untrusted data. The desk works from a
52
+ fixed set of actions (acknowledge, ticket, hand off, relay, a private
53
+ security route, ask its human). It never merges, approves, closes or
54
+ pushes, and never executes what it receives. A requester's words never
55
+ reach another agent as instructions: they stay quoted and fenced in the
56
+ ticket. When the support maintainer is in no roster, the desk starts the
57
+ stopped one on its machine or spawns one from its soul's recipe, at most
58
+ once per spawn interval, with a brief that holds ticket references only
59
+ and grants no authority. A support maintainer that is listed but silent
60
+ goes to the desk's human instead. Skills: `/support-intake`,
61
+ `/support-safety`, `/support-ticket`, `/support-handoff`,
62
+ `/support-relay`. The capability is generic: the tracker, the support
63
+ maintainer, the private security route and the limits are the soul's.
64
+ Its kernel floor is `>=0.40.0`, for `oats instance attention`. A
65
+ workspace gets it by moving its pin to `oats.framework: v1.8.0` and
66
+ running `oats sync`. The repository's package checks
67
+ (`scripts/check-knowledge-theory-package.mjs`, the clean-room smoke)
68
+ pin the distribution's capability list, so they list it too. They ship
69
+ nothing.
70
+
71
+ ## Fixed
72
+
73
+ - **Post-answer Claude completion and private evidence:** after the sole
74
+ submitted channel Enter, the pinned Claude 2.1.289 darwin-arm64 110x35 controller
75
+ can recognize a bounded bottom composer/effort-footer region with six native
76
+ mode labels, five effort labels and finite hints. Twenty-one exact known
77
+ question markers block before either exact or structural completion. Normal
78
+ shortcut/interrupt hints do not block. The non-Jt footer layout is qualified;
79
+ flag drift, missing effort and trailing notices can still refuse completion.
80
+ **An unknown dialog retaining the region can be misclassified completed.**
81
+ This accepted reporting risk cannot authorize another key or prove idle,
82
+ account or channel readiness. Existing Enter and consent/ownership guards are
83
+ unchanged. A home-only sanitized derivative of an actual in-progress Max
84
+ comparison is the regression fixture; there is no exact spinner matcher or
85
+ new live proof of the revised classifier. Also adds the source-qualified
86
+ empty Max/bypass/medium families.
87
+ Exact compared bytes are retained privately for structural completion and
88
+ post-answer unmatched blocks. Receipt v2 distinguishes those two outcomes;
89
+ historical v1 remains readable. A structural save failure reports checked
90
+ incomplete with answer/target preserved. No raw text enters public output.
91
+ See [completion scope](../launch-prompt-completion.md) and
92
+ [private evidence](../execution-targets.md#private-unmatched-launch-evidence).
93
+ This does not close #754 or establish general onboarding success.
@@ -0,0 +1,106 @@
1
+ # OATS 0.48.0
2
+
3
+ 2026-10-08
4
+
5
+ ## Added
6
+
7
+ - **Conditional team default and mapping-only add (#771), feature
8
+ `teams-conditional-default`.** `oats teams default <label> --if-absent`
9
+ sets the local default only where the deployment has no effective default;
10
+ `--expect <label0>` only where the effective default (local, or inherited
11
+ from the workspace) is `<label0>`. A failed condition is
12
+ `E_TEAM_DEFAULT_MISMATCH {expected, observed}` and writes nothing.
13
+ `oats teams add <label> --team <id> --no-default` writes the mapping without
14
+ touching `defaultTeam`; the same label and id already declared is reuse
15
+ (`changed: false, reused: true`). `E_TEAM_EXISTS` also carries `observed:
16
+ {label, team, from}`. Every `oats teams` write holds
17
+ `<deployment>/.agents/locks/local.lock`, so the later of two racing
18
+ conditional writes sees the earlier one and refuses with
19
+ `E_TEAM_DEFAULT_MISMATCH`; a lock still held after 5 s is `E_LOCAL_BUSY`,
20
+ with nothing written. `teamsApi`
21
+ stays 2: the `oats teams --json` shape is unchanged. Callers check the
22
+ feature before passing the flags, because older kernels ignore them, and
23
+ there `--if-absent` is an unconditional set.
24
+
25
+ ## Changed
26
+
27
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.49.0`.** The compatibility band
28
+ admits 0.48; existing feature gates remain unchanged.
29
+
30
+ - **`oats teams` refuses flags it does not take.** Each form (`oats teams`,
31
+ `add`, `remove`, `default`) answers an unknown flag with `E_USAGE {flag}`,
32
+ naming it and the usage, before anything is read or written. Before, they
33
+ were ignored. `--server` on `oats teams` is now refused too: teams has never
34
+ been routed to a server. A script that passes stray flags must drop them.
35
+
36
+ - **The workspace pins oats.framework 1.8.0 and oats.engineering 1.9.0.**
37
+ The official catalog resolves bare `oats.framework` versions to
38
+ `oats-framework/v1.8.0` (oats.support 1.0.0, the support desk role), and
39
+ `oats.engineering` to `v1.9.0`. That adds oats.maintainer's
40
+ `/support-maintainer` skill: a maintainer that serves the support desk's
41
+ tickets. The capability mirrors under `mirrors/` are regenerated from the
42
+ v1.9.0 tag and their trees equal the tag's. Running instances keep what
43
+ they were spawned with; new spawns pick these up after `oats sync`.
44
+
45
+ - **The workspace and official catalog pin oats.aweb 1.23.2.** The generated
46
+ `mirrors/oats-aweb` payload equals the provider v1.23.2 tag tree. This adds
47
+ verified LOCAL join mapping/default readback and explicit LOCAL identity
48
+ selectors at launch and preview (1.23.1), and GLOBAL grant metadata that
49
+ records the app snapshot from each successful native mint receipt: Comms
50
+ labels it as the at-spawn snapshot, inspect shows the current recorded
51
+ metadata, and preview warnings say whether it is retained or unknown
52
+ pending renewal (1.23.2). That snapshot is not a live app acceptance. Existing captured homes
53
+ do not adopt the changes automatically; this pin does not perform sync,
54
+ restart or live acceptance.
55
+
56
+ - **oats.apps 1.0.0 is a new official package.** It exports `oats.folio` and
57
+ `oats.library`, additive guidance capabilities for the aweb Folio and Library
58
+ apps (`aw >=1.36.26`; OATS 0.47.0 or later), and the catalog aliases both
59
+ ids to the package. The generated `mirrors/oats-folio` and
60
+ `mirrors/oats-library` equal the v1.0.0 tag's payload trees. The workspace
61
+ adds `awebai/oats-apps` as a member (its expert soul `oats-apps-expert`) and
62
+ pins `oats.apps: git:github.com/awebai/oats-apps@v1.0.0`: an installed CLI
63
+ resolves bare versions through the catalog it shipped with, and 0.47.0's has
64
+ no `oats.apps`, so the pin goes bare once every deployment's CLI carries
65
+ this entry. No soul selects either capability yet, and no workspace default
66
+ is added.
67
+
68
+ ## Fixed
69
+
70
+ - **Every `oats retire` stops recorded children first, as its plan says
71
+ (#778).** `oats retire <name> --plan` has always said that recorded child
72
+ instances "are stopped first (bounded SIGTERM, never escalated) and
73
+ retained" and that "a child still running after the grace refuses the
74
+ retirement", but before 0.48.0 only the guarded apply (`--plan-revision`
75
+ with `--idempotency-key`, what the Desktop sends) did it. A plain
76
+ `oats retire <name>` and a `--self` retirement left the children running,
77
+ attached ones on a work tree that had just been removed, with no stop
78
+ event.
79
+ - **Behavior change.** A plain `oats retire` and `--self` now stop recorded
80
+ children first and keep them. They refuse, retiring nothing, when one
81
+ won't stop or its session can't be established: `E_CHILDREN_RUNNING
82
+ {childrenStopped}`, exit 1, and the text names each child and its code
83
+ (`children still running: <name> (<code>); nothing retired`). `--force`
84
+ does not bypass it: end the child's session yourself (the receipt's
85
+ `stillRunning` names its processes), then retry.
86
+ - The receipt lists the children as `childrenStopped[]` (absent when there
87
+ are none), and the text prints `child <name>: stopped` or
88
+ `already idle` for each.
89
+ - `--self` stops the children recorded when the retirement was scheduled
90
+ (skipping any retired since), in its detached completion before it stops
91
+ the caller. A refusal leaves the caller's window and home in place and
92
+ writes `E_CHILDREN_RUNNING` with `childrenStopped` and the `retry` command
93
+ to the result file that `oats status` reports.
94
+ - The guarded apply is unchanged for the Desktop. It now stops children
95
+ only after the retire's own read-only refusals, so a retire refused
96
+ there leaves its children running.
97
+
98
+ - **A home without its session receipt says what was looked for and what to
99
+ do (#762).** `session inspect`, `start` and `restart` refused such a home
100
+ with a bare `ENOENT`. The `E_RUNTIME_ENDPOINT_UNKNOWN` refusal now names
101
+ the receipt path it looked for, says to address the home exactly as
102
+ `oats status` prints it (a different spelling of the path looks for the
103
+ receipt elsewhere), and otherwise names the causes and the remedy: stop its
104
+ session yourself if one runs, then `oats retire <name> --plan` and
105
+ `oats retire <name>`, and respawn. The code is unchanged. The receipt's key
106
+ for a differently spelled path is #780.
@@ -102,7 +102,9 @@ souls) is ordinary capability content: **`oats.core`** (package
102
102
  `oats.framework`). Workspaces give it to every soul through
103
103
  `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
104
104
  `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
105
- knowledge an onboarding expert needs. Neither is kernel magic; the kernel still
105
+ knowledge an onboarding expert needs, and **`oats.support`** (same package)
106
+ is the support desk role: a publicly reachable soul that tickets requests and
107
+ hands them to a support maintainer. None of them is kernel magic; the kernel still
106
108
  composes its own instance-boundary and work-mode briefings, and the "You run
107
109
  on OATS" briefing is `oats.core`'s inject: a soul without `oats.core` gets no
108
110
  OATS operating instructions, and `oats doctor --soul` says so. Its capability
@@ -429,6 +431,13 @@ takes a final capture of notes and the session record into durable custody; an
429
431
  incomplete capture keeps the home for a retry. Retirement never waits for a
430
432
  model or GitHub: processing continues after the home is gone.
431
433
 
434
+ Recorded children (the instances whose recorded parent chain reaches this
435
+ one) are stopped first, never escalated, and kept: their homes stay. If one is
436
+ still running after the grace, or its stop cannot be established, retire
437
+ refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
438
+ bypass it. This holds for plain, guarded and `--self` retires alike
439
+ ([desktop-cli-api.md](desktop-cli-api.md)).
440
+
432
441
  Before any retire hook runs, retire preserves the instance's uncommitted and
433
442
  unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
434
443
  the summary. One retire writes at most one recovery directory. A worktree
@@ -751,8 +760,16 @@ exist under "not copied", by name, with the declaring capability. The
751
760
  declaration is recorded at spawn: a home spawned before its capability
752
761
  declared them gains no exclusion from a package update, and is copied whole.
753
762
 
754
- Retire stops the harness through the home's session receipt. A home spawned
755
- before 0.25.9 has none. It retires only when its session is observably gone:
763
+ Retire stops the harness through the home's session receipt, kept beside the
764
+ home in the instances directory's `.oats-retirement/baselines/` and keyed by
765
+ the home's path. First address the home exactly as `oats status` prints it: a
766
+ different spelling of its path (letter case, a deployment directory moved
767
+ since the spawn) looks for the receipt elsewhere. A home can also be without
768
+ its receipt because it was spawned before 0.25.9, it was copied, the
769
+ `.oats-retirement` beside it was removed, or its creation did not finish;
770
+ `session inspect`, `start` and `restart` then refuse with
771
+ `E_RUNTIME_ENDPOINT_UNKNOWN` naming the receipt path they looked for. Such a
772
+ home retires only when its session is observably gone:
756
773
  instance.json records no launch, or the recorded tmux server is not running,
757
774
  or the recorded window is gone and no pane on that server works in the home;
758
775
  and, always, no live process on this host works in the home (a harness
@@ -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.6.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.8.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v4.1.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
 
@@ -421,11 +421,26 @@ the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
421
421
  ```
422
422
  oats teams [--json] # the teams, ids, the default, localTeams, the workspace's souls:, problems
423
423
  oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
424
+ oats teams add <label> --team <id> --no-default # the mapping only; the same label and id again is reuse
424
425
  oats teams remove <label> # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
425
426
  oats teams default <label> # the local default
427
+ oats teams default <label> --if-absent # ... only where there is no effective default
428
+ oats teams default <label> --expect <label0> # ... only where the effective default is <label0>
426
429
  oats soul teams <soul>|'*' [--json] # a soul's default and teams here, and which souls: key gave them
427
430
  ```
428
431
 
432
+ `--if-absent` and `--expect` make a setup safe to run against a deployment
433
+ whose default it has not chosen: the condition is the effective default that
434
+ `oats teams` reports (the local one, else the workspace's), judged when the
435
+ file is written, and a failed one (`E_TEAM_DEFAULT_MISMATCH`) reports what it
436
+ found and writes nothing. A soul's `souls:` default is not the deployment's
437
+ default and is not looked at. Concurrent `oats teams` writes on one deployment
438
+ are serialized, so of two racing conditional writes the later one refuses;
439
+ hand edits to `oats-local.yaml` and changes to `oats-workspace.yaml` are not
440
+ serialized with them. Each form refuses a flag it does not take (`E_USAGE`).
441
+ Callers check for the feature `teams-conditional-default` in `oats version
442
+ --json` first: an older kernel ignores these flags.
443
+
429
444
  The messaging provider's own setup creates provider teams (see the provider's
430
445
  documentation). The spawn preview, `inspect` and `oats souls` report a soul's
431
446
  `teams` and `defaultTeam`; readiness reports the team problems in
package/lib/core.mjs CHANGED
@@ -29,6 +29,7 @@
29
29
  */
30
30
  import { effectiveLaunchPromptPolicy } from "./launch-prompt-policy.mjs";
31
31
  import { createLaunchPromptController } from "./launch-prompts.mjs";
32
+ import { retainLaunchPromptFrame } from "./launch-prompt-evidence.mjs";
32
33
  import { qualifyLaunchPromptFixtures } from "./launch-prompt-fixtures.mjs";
33
34
  import { LAUNCH_PANE_FORMAT, launchPaneTarget, launchPromptTransport } from "./launch-prompt-transport.mjs";
34
35
  import { execFileSync, execSync, spawn as spawnProcess, spawnSync } from "node:child_process";
@@ -646,7 +647,7 @@ function promptController(home, startId, harness, policy, command, io, expectedH
646
647
  const described = describeLaunchCommand(command);
647
648
  const qualification = qualifyLaunchPromptFixtures({ home: realPathOrNearest(home), harness, executablePath: described.executable, argv: described.argv });
648
649
  return createLaunchPromptController({ home: realPathOrNearest(home), startId, ...qualification, policy, expectedHomeIdentity,
649
- transport: launchPromptTransport(io), audit: data => appendEvent(home, { kind: "launch-prompt", data }),
650
+ transport: launchPromptTransport(io), audit: data => appendEvent(home, { kind: "launch-prompt", data }), retainFrame: retainLaunchPromptFrame,
650
651
  ...(io?.now ? { now: io.now } : {}), ...(io?.sleep ? { sleep: io.sleep } : {}) });
651
652
  }
652
653
  function retainedPromptError(home, instance, target, parentLineageCommitted, launchPrompts) {
@@ -5455,16 +5456,26 @@ function launchStateAgrees(meta, authority) {
5455
5456
  ["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
5456
5457
  }
5457
5458
 
5459
+ /** The refusal for a home whose session receipt file does not exist where its path says it is. The
5460
+ * receipt is keyed by the home's path, so a different spelling of that path looks elsewhere. */
5461
+ function missingSessionReceipt(home, receiptPath) {
5462
+ return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${receiptPath}. First address the home exactly as \`oats status\` prints it (a different spelling — letter case, a moved deployment directory — looks for the receipt elsewhere). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
5463
+ }
5464
+
5458
5465
  /** Session control uses the independent endpoint receipt. */
5459
5466
  function instanceSessionTarget(home) {
5460
5467
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
5461
5468
  home = realPathOrNearest(home);
5462
5469
  refuseHerdrHome(home);
5470
+ const receiptPath = retirementBaselinePath(home);
5463
5471
  let baseline, meta;
5464
5472
  try {
5465
- baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8"));
5473
+ baseline = JSON.parse(readFileSync(receiptPath, "utf8"));
5466
5474
  meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
5467
- } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`); }
5475
+ } catch (e) {
5476
+ if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home, receiptPath);
5477
+ throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`);
5478
+ }
5468
5479
  const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
5469
5480
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
5470
5481
  if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
@@ -5592,6 +5603,17 @@ export function stopInstanceSession(home, o = {}) {
5592
5603
  return { home: s.home, backend: s.target.backend, stopped: true, alreadyIdle: false, state: receipt.state, receipt };
5593
5604
  }
5594
5605
 
5606
+ /** What a retire plan promises about recorded children, applied: each is stopped
5607
+ * (default grace, never escalated) in the order given (the plan's: deepest first)
5608
+ * and kept. Every outcome is collected, so a refusal names each child that is
5609
+ * still running or whose stop could not be established. */
5610
+ function stopRecordedChildren(children) {
5611
+ return children.map((kid) => {
5612
+ try { const s = stopInstanceSession(kid.home, {}); return { instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }; }
5613
+ catch (e) { return { instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }; }
5614
+ });
5615
+ }
5616
+
5595
5617
  export async function attachInstanceSession(home) {
5596
5618
  const s = instanceSessionTarget(home);
5597
5619
  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
@@ -5994,7 +6016,10 @@ export function startInstanceSession(home, o = {}) {
5994
6016
  checkRoots();
5995
6017
  const baselinePath = retirementBaselinePath(realHome);
5996
6018
  let baseline;
5997
- try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`); }
6019
+ try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
6020
+ if (e.code === "ENOENT") throw missingSessionReceipt(realHome, baselinePath);
6021
+ throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`);
6022
+ }
5998
6023
  if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
5999
6024
  baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
6000
6025
  writeJsonAtomic(baselinePath, baseline, 0o600);
@@ -7294,7 +7319,9 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
7294
7319
  instance: name, agent: found.agent.name, root: resolve(root),
7295
7320
  requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
7296
7321
  // A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
7297
- options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}) }, resultPath,
7322
+ options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
7323
+ // The recorded children as they were when the retirement was scheduled: the completion stops them first.
7324
+ ...(Array.isArray(o.children) ? { children: o.children.map((c) => ({ instance: c.instance, home: c.home })) } : {}) }, resultPath,
7298
7325
  };
7299
7326
  const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
7300
7327
  for (const k of CORE_LAUNCH_ENV) delete env[k];
@@ -7373,10 +7400,11 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
7373
7400
  result = retireInstance(intent.root, intent.instance, {
7374
7401
  home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
7375
7402
  ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
7403
+ ...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
7376
7404
  ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
7377
7405
  });
7378
7406
  } catch (e) {
7379
- record({ ok: false, error: { code: e.code, message: e.message }, ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
7407
+ record({ ok: false, error: { code: e.code, message: e.message }, ...(e.details?.childrenStopped ? { childrenStopped: e.details.childrenStopped } : {}), ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
7380
7408
  console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
7381
7409
  return false;
7382
7410
  }
@@ -7554,6 +7582,19 @@ export function retireInstance(root, name, o = {}) {
7554
7582
  throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
7555
7583
  }
7556
7584
  }
7585
+ // The plan's promise about recorded children (`o.children`, computed the way
7586
+ // the plan computes them): stopped first and kept, after every refusal above
7587
+ // that changes nothing and before this instance is quiesced. One still running,
7588
+ // or whose stop could not be established, refuses the retirement: nothing is
7589
+ // retired, nothing is escalated, and --force does not bypass it. A child whose
7590
+ // instance.json is gone by now (a --self snapshot's child retired in between)
7591
+ // is no longer an instance, and the plan would not list it: it is not stopped.
7592
+ let childrenStopped;
7593
+ if (Array.isArray(o.children)) {
7594
+ childrenStopped = stopRecordedChildren(o.children.filter((kid) => existsSync(join(kid.home, "instance.json"))));
7595
+ const running = childrenStopped.filter((k) => !k.ok);
7596
+ if (running.length) throw Object.assign(oatsError("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`), { details: { childrenStopped } });
7597
+ }
7557
7598
  // `=` forces exact matching: tmux targets otherwise PREFIX-match window names.
7558
7599
  // A no-launch instance is already quiesced. A launched one must have exact
7559
7600
  // window absence established before recovery copying begins.
@@ -7952,7 +7993,7 @@ export function retireInstance(root, name, o = {}) {
7952
7993
  rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
7953
7994
  }
7954
7995
 
7955
- const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
7996
+ const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
7956
7997
  const w = [...(hookResults?.warnings || [])];
7957
7998
  if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
7958
7999
  if (isCapturedHome(meta) && !quarantine) {
@@ -0,0 +1,67 @@
1
+ /** Completion reporting only, never input authority. Source-qualified Claude
2
+ * 2.1.289 non-Jt footer layout; the caller must enforce qualification and one
3
+ * submitted answer. Unknown dialogs retaining this region can evade the finite
4
+ * markers. That reporting risk is accepted; no subsequent key may be sent.
5
+ * See launch-prompt-fixtures/structural-completion.json and README.md. */
6
+ export const CLAUDE_QUESTION_MARKERS = Object.freeze([
7
+ 'Accessing workspace:',
8
+ 'Quick safety check:',
9
+ 'Yes, I trust this folder',
10
+ 'No, continue without these permissions',
11
+ 'No, exit',
12
+ 'WARNING: Loading development channels',
13
+ 'I am using this for local development',
14
+ 'Managed settings require approval',
15
+ 'Yes, I trust these settings',
16
+ 'No, exit Claude Code',
17
+ 'Do you want to use this API key?',
18
+ 'Detected a custom API key in your environment',
19
+ 'Select login method:',
20
+ 'Do you want to proceed?',
21
+ 'Do you want to allow this connection?',
22
+ 'Waiting for permission…',
23
+ 'Enter to confirm',
24
+ 'Esc to cancel',
25
+ 'esc to cancel',
26
+ 'Enter to select',
27
+ 'Esc to exit',
28
+ ]);
29
+
30
+ const modes = [
31
+ ['default', '⏸ manual mode on'], ['plan', '⏸ plan mode on'],
32
+ ['acceptEdits', '⏵⏵ accept edits on'], ['bypassPermissions', '⏵⏵ bypass permissions on'],
33
+ ['dontAsk', "⏵⏵ don't ask on"], ['auto', '⏵⏵ auto mode on'],
34
+ ];
35
+ const efforts = ['○ low · /effort', '◐ medium · /effort', '● high · /effort', '◉ xhigh · /effort', '◈ max · /effort'];
36
+ const hints = ['', ' · ← for agents', ' · esc to interrupt', ' · esc to interrupt · ← for agents'];
37
+ const shortcuts = [' · ? for shortcuts', ' · ? for shortcuts · ← for agents'];
38
+ const footers = new Set();
39
+ for (const [mode, label] of modes) {
40
+ for (const cycle of mode === 'default' ? [''] : ['', ' (shift+tab to cycle)']) {
41
+ for (const hint of mode === 'default' ? [...hints, ...shortcuts] : hints) {
42
+ for (const right of efforts) {
43
+ const left = label + cycle + hint;
44
+ // Every enumerated character is single-column in the qualified layout.
45
+ const gap = 108 - 2 - left.length - right.length;
46
+ if (gap >= 1) footers.add(' ' + left + ' '.repeat(gap) + right);
47
+ }
48
+ }
49
+ }
50
+ }
51
+ const border = '─'.repeat(110);
52
+
53
+ export function classifyClaudeLaunchCompletion(screen) {
54
+ if (screen?.width !== 110 || screen?.height !== 35 || typeof screen.text !== 'string'
55
+ || Buffer.byteLength(screen.text, 'utf8') > 64 * 1024) return null;
56
+ // No exemptions for unknown questions. Ordinary shortcut/interrupt hints are
57
+ // simply not markers; do not broaden this into a generic '?' or Esc rule.
58
+ if (CLAUDE_QUESTION_MARKERS.some(marker => screen.text.includes(marker))) return 'blocked';
59
+ if (/[\x00-\x09\x0b-\x1f]/.test(screen.text)) return null;
60
+ const rows = screen.text.split('\n');
61
+ if (rows.length !== 36 || rows.pop() !== '') return null;
62
+ let footer = rows.length - 1;
63
+ while (footer >= 0 && rows[footer] === '') footer--;
64
+ if (footer < 3 || !footers.has(rows[footer]) || rows[footer - 1] !== border
65
+ || rows[footer - 2] !== '❯\u00a0' || rows[footer - 3] !== border) return null;
66
+ return 'completed';
67
+ }