@awebai/oats 0.22.17 → 0.23.0

package/docs/release-notes/v0.22.18.md

@@ -0,0 +1,101 @@
+# OATS v0.22.18
+
+Choose how an agent runs without replacing its home. Desktop offers
+**Start…** for stopped instances and **Restart with…** for running
+instances, with harness, model, permissions and named launch
+configurations. The kernel records what each home was started with and
+starts it again the same way.
+
+## Named launch configurations
+
+Define a reusable configuration in a scope's `oats-config.yaml`, or use
+**Manage launch configurations** in Desktop. A configuration chooses `pi`,
+`claude` or `codex`, an optional executable or wrapper, literal arguments,
+environment values or references, a default model and the shared `yolo`
+setting.
+
+```yaml
+launch-configs:
+  codex-personal:
+    runtime: codex
+    args: ["--profile", "personal"]
+    yolo: true
+```
+
+Arguments are passed literally; native configuration files and account
+settings stay under the harness's control. For environment credentials use
+a reference such as `API_KEY: {fromEnv: PERSONAL_KEY}`: the execution host
+resolves it each time the agent starts. The recorded recipe, receipts,
+previews, roster answers and spawn answers do not expose the value (the
+launch itself and its transport necessarily use it). A configuration cannot name the kernel's own launch
+environment or override environment a capability owns.
+
+An existing instance keeps its recorded launch configuration even if the
+scope's definition changes or disappears. Select a named configuration
+explicitly to apply its current definition. Changing only the model or
+permissions keeps the rest of the recorded invocation; choosing a harness
+without a configuration starts that harness's defaults, with no model
+carried across harnesses.
+
+`oats launch-config list | set | remove | preview` author and inspect
+configurations; `oats spawn --launch-config` starts a new instance under
+one; a soul may name a default (`launch-config:` in soul.yaml,
+`oats soul set --launch-config`).
+
+## Restart in place
+
+`oats session start` with a selection validates the requested launch
+(recipe, executable, references, capability preparation, runtime packages)
+and starts a stopped instance; it never stops a running harness. Only
+`oats session restart` does: it runs the same checks first, then sends
+SIGTERM to the harness under the pane's launcher and waits a bounded time
+for it to end; it does not escalate to a forced kill and refuses to launch
+a second harness if it cannot confirm the first has stopped, reporting what
+was signalled and observed. The instance keeps its home, identity, work and
+notes; OATS does not transfer a native conversation between harnesses.
+Save work before restarting.
+
+Capabilities take part through what was captured for the home: a capability
+may declare a `launch` hook to prepare another harness (under the settings
+captured at spawn, with the scope's current manifest and trust); a
+capability that contributed harness-specific arguments and cannot prepare
+the new one refuses the switch. Homes that predate launch recipes are
+converted narrowly from their recorded command when a selection asks for
+it; unrecognized arguments are refused by name.
+
+One limitation, stated rather than hidden: a runtime-package requirement is
+verified with the package manager's controlled list command under the
+launch's environment and executable, which cannot carry a configuration's
+arguments. When such a requirement applies and the configuration passes
+arguments, the launch is not reported verified (`E_LAUNCH_PROBE_UNSUPPORTED`):
+put native configuration a required package must see in a wrapper
+executable or the environment.
+
+```sh
+oats launch-config list --dir /path/to/team
+oats launch-config preview --home /path/to/instance --runtime codex --json
+oats session restart --home /path/to/instance --launch-config codex-personal
+```
+
+Local tmux and Herdr sessions use the same lifecycle operations. Registered
+servers support configuration management and start/restart choices through
+their installed OATS CLI (probe tokens `launch-config`, `session-restart`);
+existing remote homes keep their saved route, and an older kernel is
+refused after the compatibility probe, before any mutation or stop.
+
+## Desktop fixes
+
+Tabs from other workspaces stay hidden. Instance action menus are positioned
+correctly when opened and remain stable through roster refreshes. Failed
+launch preflight checks are shown in the invocation preview, and an accepted
+launch is not presented as a running agent until the terminal is observed.
+
+## Also in this release
+
+- Capture lock (source only; the installed capture service is unchanged):
+  nonce-checked ownership, cleanup of a failed initialization that respects
+  a replacement, release outcomes reported as observed, and the privacy
+  loader's exit no longer leaves a lock behind.
+- A design proposal for managing agents from an iPhone over Tailscale
+  (docs/design/2026-09-07-mobile-agent-management-proposal.md); no
+  implementation ships.

package/docs/release-notes/v0.22.19.md

@@ -0,0 +1,115 @@
+# OATS v0.22.19
+
+Version 0.22.18 was tagged but never published: its hosted gate failed on
+four tests that pass on macOS and fail on Linux (two launch tests calling
+the kernel directly resolved the real harness binary on the test process
+PATH, one launch test spawned zsh, which the runner does not install, and
+one capture-lock test where Linux reused the inode of an unlinked
+directory). The tag stays fixed and unpublished. This release carries the
+same content with the corrections below.
+
+Choose how an agent runs without replacing its home. Desktop offers
+**Start…** for stopped instances and **Restart with…** for running
+instances, with harness, model, permissions and named launch
+configurations. The kernel records what each home was started with and
+starts it again the same way.
+
+## Named launch configurations
+
+Define a reusable configuration in a scope's `oats-config.yaml`, or use
+**Manage launch configurations** in Desktop. A configuration chooses `pi`,
+`claude` or `codex`, an optional executable or wrapper, literal arguments,
+environment values or references, a default model and the shared `yolo`
+setting.
+
+```yaml
+launch-configs:
+  codex-personal:
+    runtime: codex
+    args: ["--profile", "personal"]
+    yolo: true
+```
+
+Arguments are passed literally; native configuration files and account
+settings stay under the harness's control. For environment credentials use
+a reference such as `API_KEY: {fromEnv: PERSONAL_KEY}`: the execution host
+resolves it each time the agent starts. The recorded recipe, receipts,
+previews, roster answers and spawn answers do not expose the value (the
+launch itself and its transport necessarily use it). A configuration cannot name the kernel's own launch
+environment or override environment a capability owns.
+
+An existing instance keeps its recorded launch configuration even if the
+scope's definition changes or disappears. Select a named configuration
+explicitly to apply its current definition. Changing only the model or
+permissions keeps the rest of the recorded invocation; choosing a harness
+without a configuration starts that harness's defaults, with no model
+carried across harnesses.
+
+`oats launch-config list | set | remove | preview` author and inspect
+configurations; `oats spawn --launch-config` starts a new instance under
+one; a soul may name a default (`launch-config:` in soul.yaml,
+`oats soul set --launch-config`).
+
+## Restart in place
+
+`oats session start` with a selection validates the requested launch
+(recipe, executable, references, capability preparation, runtime packages)
+and starts a stopped instance; it never stops a running harness. Only
+`oats session restart` does: it runs the same checks first, then sends
+SIGTERM to the harness under the pane's launcher and waits a bounded time
+for it to end; it does not escalate to a forced kill and refuses to launch
+a second harness if it cannot confirm the first has stopped, reporting what
+was signalled and observed. The instance keeps its home, identity, work and
+notes; OATS does not transfer a native conversation between harnesses.
+Save work before restarting.
+
+Capabilities take part through what was captured for the home: a capability
+may declare a `launch` hook to prepare another harness (under the settings
+captured at spawn, with the scope's current manifest and trust); a
+capability that contributed harness-specific arguments and cannot prepare
+the new one refuses the switch. Homes that predate launch recipes are
+converted narrowly from their recorded command when a selection asks for
+it; unrecognized arguments are refused by name.
+
+One limitation, stated rather than hidden: a runtime-package requirement is
+verified with the package manager's controlled list command under the
+launch's environment and executable, which cannot carry a configuration's
+arguments. When such a requirement applies and the configuration passes
+arguments, the launch is not reported verified (`E_LAUNCH_PROBE_UNSUPPORTED`):
+put native configuration a required package must see in a wrapper
+executable or the environment.
+
+```sh
+oats launch-config list --dir /path/to/team
+oats launch-config preview --home /path/to/instance --runtime codex --json
+oats session restart --home /path/to/instance --launch-config codex-personal
+```
+
+Local tmux and Herdr sessions use the same lifecycle operations. Registered
+servers support configuration management and start/restart choices through
+their installed OATS CLI (probe tokens `launch-config`, `session-restart`);
+existing remote homes keep their saved route, and an older kernel is
+refused after the compatibility probe, before any mutation or stop.
+
+## Desktop fixes
+
+Tabs from other workspaces stay hidden. Instance action menus are positioned
+correctly when opened and remain stable through roster refreshes. Failed
+launch preflight checks are shown in the invocation preview, and an accepted
+launch is not presented as a running agent until the terminal is observed.
+
+## Also in this release
+
+- Capture lock (source only; the installed capture service is unchanged):
+  nonce-checked ownership, cleanup of a failed initialization that respects
+  a replacement, release outcomes reported as observed, and the privacy
+  loader's exit no longer leaves a lock behind. The initializing directory
+  is held open until its owner record is written or its cleanup finishes,
+  preventing its inode from being reused during cleanup; a replacement
+  directory is left alone.
+- Test fixtures: the launch tests resolve their fake harness binaries on the
+  test process PATH and exercise only the shells the host installs; no
+  kernel change.
+- A design proposal for managing agents from an iPhone over Tailscale
+  (docs/design/2026-09-07-mobile-agent-management-proposal.md); no
+  implementation ships.

package/docs/release-notes/v0.23.0.md

@@ -0,0 +1,93 @@
+# OATS v0.23.0
+
+This is the prerequisite kernel release for capability-owned external knowledge
+and independent harvesting. It adds generic directory work and more reliable
+record capture; it does **not** migrate existing knowledge or select a new
+knowledge integration. The bundled `oats.okf` and official catalog pin remain
+**1.6.1**. OKF 2.0 is a separate, subsequent capability release; no new catalog
+pin or bundled v2 runtime is included here.
+
+## Independent directory work
+
+`work: directory` creates an instance-owned ordinary `work/` directory. It does
+not require a Git repository, branch, worktree, or fabricated commit. Existing
+Git work modes retain their semantics. A capability can use directory workers
+for non-Git knowledge custody without making its storage model a kernel policy.
+
+Directory lifecycle checks reject a replaced, missing or symlinked work root
+before launch, and preserve retryable cleanup obligations when compensation
+cannot finish. Hooks receive the running kernel's CLI path. Generic scheduled
+commands no longer inherit another instance's source identity.
+
+## Evidence capture and recall
+
+Record capture distinguishes completed work from skipped, held, incomplete and
+failed attempts. Capture verifies attributed native transcript identity,
+honors native storage roots and recorded launch environments, and includes
+supported nested Claude subagent transcripts. Uncertain discovery, unreadable
+or replaced sources, incomplete tails and lock failures are not certified as
+complete evidence. Large piped recall responses drain stdout before exiting.
+Managed starts now preserve independent, execution-time native record-location
+history, so a later observer's environment cannot silently redirect capture.
+History survives retirement and is not a knowledge bundle. Older or standalone
+sessions without that authority fail closed on `capture --home`; an operator
+can explicitly use `oats capture --current-roots --home <home>` to inventory the
+currently configured roots, but that does not certify all historical locations.
+
+These are evidence-preservation guarantees, not a claim that a model has learned
+from the captured records.
+
+## Optional knowledge-theory authoring resources
+
+`oats.knowledge-theory` 1.0.0 is an optional **Git-distributed OATS package**
+in this repository's self-contained `oats-package/` subtree. It exports
+`knowledge-theory-expert` and the `knowledge-capability-authoring` skill with
+the complete local reference curriculum. The kernel npm tarball ships public
+docs and the CLI, but **excludes** this optional payload entirely. npm omits
+symlinks; a partial copy without the canonical source alias is not a supported
+package. Acquisition does not synthesize aliases or relax integrity semantics.
+
+After this immutable tag is published, acquire through the normal Git package
+route and explicitly opt in for an author soul:
+
+```bash
+oats install git:github.com/awebai/oats@v0.23.0 --dir /path/to/scope
+oats use oats.knowledge-theory --soul <author-soul> --dir /path/to/scope
+```
+
+The default Git package root is `oats-package/`; acquisition locks the resolved
+commit and alone activates nothing. An official catalog pin can follow only
+after the immutable tag exists. No unpublished theory catalog pin is shipped
+in this prerequisite release.
+
+The package has no knowledge-layer binding, mandatory injection, runtime hook,
+command or dependency on OKF. Authors may adopt, adapt or replace the reference
+model. Each selected knowledge capability owns its runtime, reader/capture,
+judgment and delivery instructions. The first external-knowledge design covers
+Git PR delivery and non-Git directory custody; no framework ACL layer is added.
+
+Canonical references are published under
+[the authoring guide](../knowledge-capability-authoring.md) and
+[the reference model](../knowledge-reference/model.md), with byte-identical
+copies in the Git-packaged skill. Installed instances read those local copies,
+not a source checkout or mutable network documentation. Git transport preserves
+the tracked source `CLAUDE.md -> AGENTS.md`; generated instances receive their
+own canonical alias through the unchanged normal composition path.
+
+## Packaging and compatibility
+
+Kernel, Pi adapter and Desktop versions are aligned at 0.23.0, including both
+lockfiles. Desktop still uses CLI API v1; its accepted kernel band is widened
+to `>=0.22.0 <0.24.0`, retaining support for released 0.22.x kernels.
+
+Local, CI and runnerless release checks share the recursive JavaScript
+inventory, including capability libraries, record and optional package scripts.
+Validation checks the optional theory manifests and canonical curriculum parity.
+Pack checks require public docs and reject any optional package bytes in the
+npm kernel. The installed kernel acquires an exact, self-contained Git fixture
+through direct and catalog routes, checks its tracked source alias, then removes
+the fixture checkout. Probes verify local reference closure, alternative-theory
+isolation, discovery, scaffold and retirement in Git and directory scopes without
+launching models. Publication
+remains gated on the exact tag's build/test/smoke results and Desktop artifacts;
+already-versioned candidates remain safe with `--allow-same-version`.

package/docs/souls-and-instances.md

@@ -25,9 +25,10 @@ A soul is durable and committed. It is the part you review, improve, and keep.
 | `kind` | `persistent` for committed agents, `local` for full local souls under `local-agents/` (legacy `tmp` reads as `local`). |
 | `description` | Short role description. |
 | `repo` | Target repo, absolute or relative to the agents root's parent. |
-| `work` | `worktree` or `checkout`. |
+| `work` | `worktree`, `checkout`, `attached`, `workspace`, or `directory`. |
 | `runtime` | `pi` or `claude` — the harness new instances launch on; a spawn can override with `--runtime`. For `claude`, the binary is `claude` unless a local-only `oats-claude-config` file (closest one walking up from the repo; one line naming the binary, e.g. `claude-personal`) selects another — a personal machine preference for account selection, never committed. With the aweb messaging integration active, claude sessions get the `aweb-channel` plugin wired at spawn for real-time push events. |
 | `model` | Optional default model — a `provider/id[:thinking]` pattern or a comma-separated preference list (`github-copilot/x:high, anthropic/x:high`); at spawn the first entry whose provider/model is available wins (pi models probed via `pi --list-models`). For the `claude` runtime the value is translated to what the claude CLI accepts: `anthropic/<id>[:thinking]` becomes the bare `<id>`, aliases and bare `claude-*` ids pass through, other providers' entries are dropped, and nothing usable falls back to claude's own default. A spawn can override it. |
+| `launch-config` | Optional default launch configuration for new instances (a name declared under `launch-configs:` in the scope's config; see docs/design/launch-configurations.md). `oats spawn --launch-config <name|none>` overrides it; `oats soul set --launch-config <name>` / `--no-launch-config` edit it. |
 
 A soul is model-agnostic as an artifact. Its files are plain operating docs,
 skills, and knowledge. `model` is only the default choice for new instances,
@@ -255,6 +256,22 @@ only what the briefing names, keep commits small and attributable. Retiring
 an attached instance never removes the shared tree. The packaged
 `work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
 
+### `directory` — independent execution
+
+`work/` is a new instance-owned directory, not a Git repo or a link to a source.
+Use it explicitly for capability workers that need private execution space
+without Git. `repo` (or `--repo`) supplies configuration context only and may be
+an ordinary directory; without it, the deployment scope is used. An
+`oats-config.yaml` below laptop scope supports package-only deployments before
+any local souls exist. No implicit fallback changes the other modes.
+
+`--work-dir` and `--branch` are rejected. Canonical instructions, skill
+composition, provider trust and runtime preflight still apply. No worktree setup
+runs. Retirement preserves nonempty work in verified recovery storage beside the
+home (`workRecovery.path/work`) before deleting it, including files created by
+hooks; directory work has no disposable-root exemptions. The work-root cannot be
+exchanged for a symlink. Recovery does not replace the worker's delivery protocol.
+
 ### `workspace` — cross-repo coordinator
 
 `work/` is a symlink to the **whole workspace** (the team scope declared by

package/injects/work-directory.md

@@ -0,0 +1,18 @@
+## Work mode: directory
+
+Your `./work` is an **instance-owned execution directory**. It is not a Git
+worktree, a checkout, or a link to the source instance or deployment context.
+The context recorded as `repo` supplies configuration; it grants no permission
+to edit that directory.
+
+- Do task work inside `./work`. No Git repository or branch is created for you;
+  do not initialize a fake repository to satisfy a workflow. Git might discover
+  a containing repository; that does not authorize work in the containing tree.
+- Access external inputs and destinations only as explicitly authorized by the
+  task and active capabilities. This mode does not impose a storage provider or
+  a publication protocol.
+- Keep canonical instructions in the instance's `AGENTS.md`; `CLAUDE.md` is its
+  compatibility symlink. Run OATS lifecycle/capability commands from home.
+- Retirement removes the execution directory only after nonempty work has a
+  verified copy in the reported recovery storage beside the home. Recovery is
+  not publication: deliver your results through the task's own protocol first.