@awebai/oats 0.22.1 → 0.22.3

package/capabilities/oats-okf/skills/memory-harvest/SKILL.md

@@ -68,6 +68,45 @@ knowledge; if instances should RUN it the same way every time, it wants to
 be a skill instead. Souls also grow role-specific types and sections — list
 new sections in the bundle index and log the growth.
 
+## Record-fed candidates
+
+Your briefing may name **record windows** beside (or instead of) notes: the
+source instance's own captured session turns since the last harvest, each
+window given as an exact `oats recall --thread <t> --json --after <id>
+--until <id>` command. Standing roles that write few notes still learn; this
+is how what they learned reaches the soul.
+
+- Run each command exactly as given, never wider: the ids are the boundary
+  two harvests agree on, and each window is sized for one full reading (the
+  rest of a long backlog comes in later harvests). Read every window in full.
+  If your tool output truncates, redirect the command's output to a file in
+  your home and read the file in parts; that is a complete reading, not a
+  wider one. If you still could not read a window completely, this harvest
+  has FAILED: judge nothing from it and leave the watermark files untouched. If a command is rejected because its
+  `--after` id is no longer in the thread (a pruned or redacted record), run
+  it again without `--after` and read from the start; if its `--until` id is
+  rejected, this harvest has failed (leave the watermark files alone; the next
+  `oats okf harvest` replans). Read the `text` parts;
+  `tool_use` and `tool_result` are context, not lessons.
+- Extract **candidates** in the shape of notes: one candidate per insight, a
+  one-line title, the claim, and its provenance as the turn ids it came from.
+  A candidate is something the instance learned or decided, stated in the
+  turns, not something you infer it should have learned.
+- Then judge every candidate exactly as a note: promote, merge, or drop
+  against the same bar. Expect most to drop: session trivia, tool noise,
+  restated repo facts and task-scoped decisions all fail it. Promoted
+  concepts cite the turn ids in their frontmatter or body so the claim can be
+  traced back.
+- **The watermark records what you read, not what you promoted.** The
+  package prepared the exact next watermark beside the current one; your
+  briefing gives the one `mv` that advances it. Run it once your judgement of
+  every window is complete: after the commit, PR, or direct edit when
+  something was promoted, and just the same when everything dropped, which
+  is the normal outcome. Never retype it. Only a harvest that fails or is
+  abandoned leaves both files untouched, so the next harvester reads the same
+  window again; a completed judgement that never advanced the watermark would
+  be re-read forever.
+
 ## Bookkeeping (non-negotiable)
 
 1. Every promoted concept: correct frontmatter, listed in its section's
@@ -92,7 +131,9 @@ what your custody allows:
    `memory-harvest: 2 lessons + 1 skill gotcha from worker-x notes`.
 2. **Worktree of the soul's home repo** (workspace-mode source): the same single
    commit on your own branch, then push it and open a PR. Never merge it, and
-   never push to that repo's main branch — its owners review soul changes.
+   never push to that repo's main branch — its owners review soul changes. A
+   harvest that promoted nothing has no commit, push or PR to make; it is
+   complete, not failed, and still advances the watermark.
 3. **Uncommitted local soul**: nothing to commit. Your edits to the soul ARE the
    delivery; they take effect for the next instance immediately.
 

package/docs/capability-manifest.schema.json

@@ -119,6 +119,20 @@
               "marketplace": {
                 "type": "string",
                 "description": "Optional source to register before installing (Claude marketplaces). Shown at the consent prompt, since registering a third-party source is part of what is being agreed to."
+              },
+              "when": {
+                "type": "object",
+                "description": "Applies only when every named capability setting has the given effective value (a requirement conditional on configuration, e.g. delivery: channel).",
+                "additionalProperties": {}
+              },
+              "minVersion": {
+                "type": "string",
+                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the runtime's listing names; an older or absent manifest fails the requirement with the install remedy.",
+                "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+"
+              },
+              "ifInstalled": {
+                "type": "boolean",
+                "description": "When true, an absent package satisfies the row; the row's minVersion and loadability checks apply only to a package that is installed (an ambient extension that must honour a contract if present)."
               }
             },
             "additionalProperties": false
@@ -217,6 +231,33 @@
         "type": "string"
       },
       "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve like local souls where the capability is active, souls stay read-only in the package, instances home under the scope's local-agents/."
+    },
+    "settings": {
+      "type": "object",
+      "description": "Declared capability settings: name to { default, values?, description }. Documentation for `oats use --settings`; undeclared settings are still accepted.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "default": {},
+          "values": {
+            "type": "array",
+            "description": "Accepted scalar values; an effective value outside the list is refused at resolution.",
+            "items": {}
+          },
+          "description": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "environmentNamespaces": {
+      "type": "array",
+      "description": "Additional environment-name prefixes this capability may declare besides its vendor's own (e.g. AWEB_ for the official oats.aweb integration). Each is an uppercase prefix ending in an underscore; the reserved core (OATS_, PI_AGENT_) and process bootstrap namespaces cannot be claimed. Disclosed at trust time with the environment list.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Z][A-Z0-9]*_$"
+      }
     }
   },
   "additionalProperties": false

package/docs/execution-targets.md

@@ -0,0 +1,210 @@
+# Execution targets and shared wake delivery
+
+Implementation agreement, 2026-09-05. Lead owns native runtime launch,
+local tmux/Herdr adapters and terminal input; oats owns server registration,
+remote CLI routing and Desktop target selection. Aweb owns the event listener,
+notification state and delivery policy through OATS terminal input. This is the implementation
+contract, not a claim that these features have shipped.
+
+OATS manages composition, worktrees, capability lifecycle and retirement on the execution
+host. A session backend manages the persistent terminal. Desktop is a client;
+closing it must stop neither the agent nor notification delivery.
+
+```mermaid
+flowchart LR
+  UI[Desktop] --> CLI[OATS CLI]
+  CLI --> Local[Local OATS]
+  CLI --> SSH[OpenSSH]
+  SSH --> Remote[Remote OATS]
+  Local --> Sessions[tmux or Herdr]
+  Remote --> RemoteSessions[tmux or Herdr]
+  Events[aweb SSE] --> Wake[aweb wake service on execution host]
+  Wake --> Local
+  RemoteWake[aweb wake service on remote host] --> Remote
+```
+
+Server registrations live in the operator's machine configuration, outside
+repository configuration. Each entry has an id, label, OpenSSH host alias,
+absolute workspace path and OATS/Herdr executable paths. SSH owns key selection,
+host verification and authentication. Registration stores no private keys.
+Remote lifecycle calls invoke the remote installed OATS CLI with argument-safe
+quoting and the same JSON envelope as local calls. Version/envelope compatibility
+is checked before mutation. Repository operations always run on that host.
+
+The local representation of a remote instance snapshots its route:
+
+```json
+{
+  "serverId": "build-server",
+  "target": {
+    "sshHost": "build-server",
+    "workspace": "/srv/team",
+    "oatsPath": "/usr/local/bin/oats",
+    "herdrPath": "/usr/local/bin/herdr"
+  },
+  "instance": "developer-fix",
+  "home": "/srv/team/agents/developer/instances/developer-fix"
+}
+```
+
+`serverId` is for display. Later inspect/retire operations use the snapshot,
+never silently resolve a changed registry entry. A local cache is not authority
+for the remote instance's state. Remote status is pulled from its owning kernel.
+
+The host's instance and independent retirement baseline retain the same local
+session receipt. Existing `tmux: {session, window, socket}` remains readable.
+New Herdr instances use:
+
+```json
+{
+  "backend": "herdr",
+  "binary": "/usr/local/bin/herdr",
+  "socket": "/home/operator/.config/herdr/sessions/oats/herdr.sock",
+  "workspaceId": "w1",
+  "paneId": "w1:p1",
+  "terminalId": "term_65ab9108c6c301",
+  "protocol": 20
+}
+```
+
+The terminal id distinguishes a replacement occupant after a server restart.
+Backend operations allocate, start, inspect, stop and attach a viewer. Retirement
+compares the receipt with its baseline and proves the original session absent.
+An unavailable server or failed inspection is not proof of absence. The same
+rule applies to spawn compensation and detached self-retirement. Lifecycle
+operations run on the target host, so the local backend does not implement SSH.
+
+Herdr 0.8.2 exposes snapshots, socket commands, agent-state inspection and JSONL
+terminal observation/control. Its protocol is versioned. Agent prompts reject
+approval-blocked agents, but prompting a working agent does not prove the new
+message was processed. The adapter must retain this distinction. See the
+[Herdr socket API](https://herdr.dev/docs/socket-api/) and
+[remote connections](https://herdr.dev/docs/persistence-remote/).
+
+An aweb host service owns event streams for managed instances; the GUI displays
+and controls it. Reuse aweb's existing authenticated event/run loop rather than copying credential
+and SSE parsing into OATS or Desktop. OATS exposes backend-neutral session
+inspection and literal terminal input; aweb supplies delivery policy. Current authorization is
+per identity: one long-lived stream per active identity, coalesced per instance,
+with bounded retries. A single team stream requires an explicit server API.
+Reconnect also checks pending state so a lost edge does not strand unread work.
+
+Delivery is a fixed instruction to check `aw` mail/chat from the instance home,
+not arbitrary sender content typed into a shell. The service never acknowledges
+mail or chat on the agent's behalf. Aweb pending hints survive reconnect and service
+restart, coalesce while busy and defer at approval prompts. A stopped harness,
+an unknown occupant or a fallback shell is not a delivery target. Do not call a
+successful terminal write an agent acknowledgement.
+
+Native channels remain selectable during qualification; session delivery must
+be exclusive with them for each instance. Removal follows real tests of Pi,
+Claude and Codex receiving mail/chat, a busy turn, an approval prompt, reconnect,
+service restart, GUI closure and a stopped runtime. The OATS Pi tool extension
+and the aweb Pi channel are separate packages; replacing notification transport
+does not silently remove unrelated tools.
+
+Acceptance includes local CLI/Desktop spawn, reattach, preserved work and
+retirement through both backends; then the same operations on a user-designated
+SSH target. Registering a host without a successful remote agent run does not
+qualify remote support.
+
+## Session CLI contract
+
+Run on the execution host:
+
+```sh
+oats session attach --home /absolute/instance
+oats session inspect --home /absolute/instance --json
+oats session input --home /absolute/instance --text-file /path/to/message --json
+printf '%s' 'Check your pending work.' | oats session input --home /absolute/instance --json
+```
+
+`attach` is interactive and does not accept `--json`. It validates the saved
+endpoint on the execution host, then opens a Herdr terminal viewer or an
+isolated tmux session linked to that agent's window alone. Closing its terminal
+cleans the viewer without stopping the agent; retiring the agent ends the viewer
+instead of switching it to a sibling. This host-local command is also the
+remote Desktop attachment seam over an SSH PTY.
+
+Input accepts UTF-8 text up to 256 KiB, with no NUL bytes. The CLI uses the
+independent lifecycle receipt and refuses metadata disagreement. Tmux uses
+literal bracketed paste followed by Enter. Herdr uses pane input followed by
+Enter. Neither path interprets message text as a shell command. A fallback
+shell or ambiguous split tmux window refuses automatic input.
+
+Success uses the existing envelope:
+
+```json
+{"schemaVersion":1,"ok":true,"result":{"home":"/absolute/instance","backend":"herdr","present":true,"state":"idle","submitted":true}}
+```
+
+Inspect omits `submitted`; optional backend identifiers describe the observed
+terminal. `state` is the Herdr agent state when available, `unknown` for a live
+unclassified harness, `shell` for a fallback shell, `stopped` for an absent/dead
+terminal, or `not-launched`. Errors use `ok:false,error:{code,message}` and a
+nonzero exit. An unavailable backend is an error, never a stopped result.
+Tmux receipts identify socket/session/window; automatic input requires one live
+pane in that exact window. Herdr additionally verifies the original terminal ID.
+The broker owns busy/approval policy and must not interpret `submitted` as
+processing acknowledgement.
+
+Capability spawn hooks register a pending home before runtime allocation;
+inspection becomes available once its receipt is persisted. Retire hooks
+unregister after quiescence. The broker must tolerate this lifecycle order and
+missing homes, and persist pending hints until handled. Kernel session operations
+contain no aweb identity, credentials, stream or notification logic.
+
+The portable integration belongs to the official `oats.aweb` capability.
+The aweb development deployment currently selects its owned `aweb.identity`
+capability; that deployment-specific choice does not change the broker interface
+and needs equivalent registration glue when switched to session delivery.
+
+## Shared permission setting
+
+Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
+scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
+`--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
+the same per-launch choice. With no setting, native policy is retained.
+
+Codex receives `--yolo` plus a launch-local trust setting for the generated
+instance home; Claude receives `--dangerously-skip-permissions`. Pi's existing
+project trust behavior is unchanged. `--no-yolo` removes the OATS bypass flags;
+it leaves the operator's native harness settings in force. Instance metadata
+records an explicitly resolved setting. This choice applies when starting an
+agent, not retroactively to running sessions.
+
+Desktop remote terminal requests contain only the server id and instance name.
+The selected installed CLI resolves the saved route and performs remote
+inspection before attaching over SSH. Pending inspections share the terminal
+resource limit and duplicate requests share one inspection. Remote status and
+instance keys must include the server so identical paths on different hosts
+remain distinct.
+
+## Desktop remote roster and lifecycle
+
+Desktop uses the installed CLI's `server roster --json` feature when advertised.
+It refreshes one aggregate roster at a time, independently of terminal traffic;
+the CLI owns SSH deadlines, server registration and saved routes. Each target
+appears in the workspace selector with its souls and instances. An unreachable
+target stays visible with unknown runtime state and an error. A saved route
+remains visible after its registration is removed or changed.
+
+Choose the server workspace to spawn one of its souls. A successful launch
+switches to that workspace and opens the instance terminal once it appears in
+the roster. The instance action menu offers harvest and retirement, including
+for stopped agents. Remote harvest runs in the saved home on the execution host;
+retirement uses the same saved route and work-preservation rules as the CLI.
+Closing a viewer leaves the agent running.
+
+Desktop retirement requires the CLI's `retire-home` feature and always sends
+the exact selected home. The remote kernel must support that feature too;
+older kernels require an upgrade before the GUI can retire an instance.
+This keeps same-named instances distinct. Retirement feedback reports every
+preserved recovery path and its classes, including an incomplete cleanup.
+
+This first projection enables terminal and lifecycle actions only for remote
+instances with a route saved on this machine. Other observed instances are
+listed, but require the execution host's CLI to manage them. Remote brain files
+are accessed through the terminal. The roster and remote harvest require CLI
+feature tokens `roster` and `harvest`; the published 0.22.2 kernel has remote
+spawn, status, retirement and terminals, but not these two additions.

package/docs/implementation.md

@@ -158,7 +158,20 @@ instance homed inside a repository with its own `.claude/skills` sees those
 too. Project *settings* — hooks, plugins, permissions, custom agents — resolve
 from the instance home rather than from ancestors.
 
-Both runtimes record what they actually expose in `instance.json` under
+Codex is available with `--runtime codex`. It starts in the instance home,
+reads `AGENTS.md` and `.agents/skills` natively, and receives `TASK.md` as its
+initial prompt. User configuration, approval policy, ancestor instructions and
+ambient skill sources remain native. Worktrees are already below the instance
+home; checkout/attached paths outside it use Codex's normal approval handling
+and may require approval for writes, depending on the operator's policy.
+OATS does not pass `--add-dir`, which Codex refuses under some native policies.
+OpenAI-prefixed model preferences are translated to
+Codex ids; other provider preferences fall back to its configured default.
+The Desktop model field accepts a native id without using Pi's model catalog.
+This launch support does not supply an aweb channel for Codex: agents can use
+`aw` from their home, with automatic wake delivery tracked separately.
+
+All runtimes record what they actually expose in `instance.json` under
 `composition.materialized.runtimePosture`: the OATS-composed set, what is
 curtailed, and what remains ambient. The deviation from strict composition is
 auditable rather than implied.

package/docs/integrations.md

@@ -139,3 +139,39 @@ contract design, and the `integration-authoring` skill routes work to it.
 Test an integration as a capability package: acquire, lock, trust, activate,
 spawn, retire, with the golden fixtures as the behavior oracle for the kernel
 side.
+
+## oats.aweb settings (1.10.0)
+
+Set with `oats use oats.aweb --settings <key>=<value>` at a scope, or per
+soul through the binding's `settings:` map.
+
+- `delivery: channel | session` (default `channel`). `session` hands
+  notification delivery to the host wake broker: `AWEB_DELIVERY=session` in
+  the launch environment (declared by the manifest), no Claude channel flag,
+  a pi extension that honours the opt-out (`@awebai/pi` 0.3.10 or later,
+  enforced as a conditional requirement with a version floor), and a briefing
+  and registration of the home with the host wake broker (`aw wake register`).
+  Until an aw that ships `aw wake` exists (aweb-abil), session mode REFUSES
+  to spawn rather than leave an instance that nothing wakes: it is for broker
+  qualification only; leave the default otherwise.
+- `identity: { source: "/abs/path/to/legacy/.aw" }`, per soul, explicit and
+  never inferred. The spawned instance becomes the retained seat of that
+  existing identity (same did:aw and address). The aweb service URL comes
+  from the source's `workspace.yaml` (`aweb_url`); a hosted-init source has
+  none, so set `OATS_AWEB_URL` (for example `https://app.aweb.ai/api`) in
+  the spawn environment when the source lacks it: the identity-authority files
+  are copied into the home's `.aw` (never `workspace.yaml` or caches), the
+  coordination binding is reconnected with `aw workspace connect`, and the
+  seat is verified online before the instance is briefed. A lock beside the
+  source (`.aw-retained-seat.json`) refuses a second seat while a holder is
+  live. Retire releases the lock and touches neither the identity nor the
+  source; removing the legacy `.aw` is a human step. Rehearse on a disposable
+  global identity first: a send, a claim and a heartbeat from the new home
+  must all work before any real seat moves.
+
+Requirement rows in a manifest may carry `when: { <setting>: <value> }` (the
+row applies only when the capability's effective setting matches) and
+`minVersion` (the version is read from the package.json under the install
+directory the runtime's listing names; an older or absent manifest fails the
+requirement with the install remedy). `ifInstalled: true` makes an absent
+package satisfy the row, so the floor applies only to an ambient extension.

package/docs/migration-from-oas.md

@@ -29,7 +29,7 @@ version has a supported replacement. When the plan is correct:
 
 ```bash
 oats migrate --from-oas --dir /path/to/scope
-oats doctor --dir /path/to/scope
+oats doctor /path/to/scope
 ```
 
 Run the exact `oats trust <capability> --dir <scope>` commands printed by

package/docs/oats-config.schema.json

@@ -72,6 +72,7 @@
   },
   "type": "object",
   "properties": {
+    "yolo": { "type": "boolean", "description": "Skip Codex/Claude permission prompts. Closest scope wins; soul and launch overrides take precedence." },
     "name": { "type": "string" },
     "team": {
       "type": "object",