@awebai/oats 0.22.19 → 0.23.1

package/docs/design/package-runtime-api.md

@@ -81,7 +81,7 @@ this contract remains authoritative).
 2. **Spawn** — `oats spawn <agent> ... --json` with the EXISTING flags:
    `--purpose <slug>` (deterministic derived naming
    `<agent>-<purpose>`; no raw instance-name authority), `--parent`,
-   `--repo`, `--work attached|worktree|checkout|workspace`, `--work-dir`,
+   `--repo`, `--work attached|worktree|checkout|workspace|directory`, `--work-dir`,
    `--branch`, `--model`, `--task`/`--task-file` (owner-only tempfiles:
    mode 0600, removed on every outcome). Existing validation and error codes
    (`E_BAD_ARGS`, `E_PARENT_NOT_FOUND`, `E_SPAWN_FAILED`, ...) are part of
@@ -96,8 +96,8 @@ this contract remains authoritative).
    read their settings (e.g. oats.okf's `harvest-model`) from `OATS_SETTINGS`;
    there is NO public resolved-config read command.
 4. **Consumer rules**: a package command executes the CLI at the exact
-   absolute path the dispatcher provides in the **`OATS_CLI_BIN`** environment
-   variable (part of the dispatch env contract, beside `OATS_SETTINGS`), via
+   absolute path the dispatcher or lifecycle runner provides in the
+   **`OATS_CLI_BIN`** environment variable (beside `OATS_SETTINGS`), via
    `execFile` on that path — **never** by resolving `oats` from `PATH` and
    never through a shell: PATH is not a trusted runtime boundary, and package
    commands run in worktrees where it can be shadowed. The consumer parses
@@ -109,6 +109,180 @@ Error codes are part of the contract: `E_USAGE`, `E_BAD_ARGS`,
 `E_RELATIVE_NOT_FOUND`, `E_RELATIVE_AMBIGUOUS`, `E_CAPABILITY_BLOCKED`,
 `E_CAPABILITY_INACTIVE`.
 
+### Directory execution for capability workers
+
+A worker may explicitly select `work: directory` in its packaged `soul.yaml`,
+pass `--work directory` to spawn, or use `spawnInstance(..., {work: "directory"})`.
+This is a generic execution mode, independent of any knowledge provider.
+Consumers using it must declare the directory-mode release as their
+`compatibility.oats` floor, not the older boundary-v1 floor alone.
+
+- `repo` / `--repo` is an **existing config context directory** in this mode,
+  not a Git requirement or an edit target. Relative paths resolve from the
+  agents root's parent; absent a selector it defaults to that deployment scope.
+  The CLI does not substitute its ambient Git checkout. A configured workspace
+  can discover and spawn declared package agents before it has an `agents/` or
+  `local-agents/` directory. Laptop config alone does not declare a deployment.
+- `<home>/work` is a new, owned directory, not a symlink and not a fake Git
+  repository. The kernel creates no branch, copies no source tree, and does not
+  require Git in a non-Git deployment. Git-owned deployment placement still
+  requires readable Git metadata to establish the canonical home location.
+- `--work-dir` / `workDir` and `--branch` / `branch` are contradictory and
+  rejected with `E_BAD_ARGS`, even if empty or inherited from a caller bug.
+  Directory execution never takes ownership of a caller-selected filesystem
+  path. Existing modes retain their Git/context requirements and semantics;
+  failed Git operations never implicitly fall back to directory execution.
+- Canonical `AGENTS.md` / `CLAUDE.md`, skill composition, provider trust,
+  lifecycle hooks, frozen launch recipes, runtime preflight and no-launch
+  metadata are unchanged. Hooks receive `OATS_WORK=directory`, an empty
+  `OATS_BRANCH`, and the context in `OATS_REPO` / `OATS_CONTEXT` at spawn.
+  Worktree-only setup scripts are not run in this mode.
+- Retirement authenticates directory ownership against the independent spawn
+  baseline. Nonempty execution work is preserved in verified recovery custody
+  (`workRecovery.path/work`, with home bytes under `home/`) before removal;
+  post-hook changes produce another verified snapshot. No work is designated
+  disposable in this initial mode, including hook-created work. Symlinks inside
+  work are copied as links, never followed; an exchanged work-root symlink,
+  unsupported filesystem entry, or unverifiable copy fails closed. Recovery is
+  not provider delivery or publication, and retains the existing single-host,
+  quiesced-runtime safety model rather than a hostile-filesystem atomicity claim.
+
+### Lifecycle and scheduled-command context
+
+Lifecycle hooks receive `OATS_CLI_BIN` as the real, absolute `bin/oats.mjs`
+path belonging to the **running kernel**. This is authored by
+`runLifecycleHooks` itself, including direct core callers; neither ambient
+`OATS_CLI_BIN` nor a caller's `extraEnv.OATS_CLI_BIN` can override it. Spawn
+hooks also receive the known agents root as `OATS_ROOT`, rather than an empty
+value or the ambient caller's root.
+
+Scheduled command execution starts without the invoking instance's identity:
+`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, legacy `OATS_HOME`, the `PI_AGENT_*`
+aliases and `PI_AGENTS_ROOT`, plus kernel-authored soul, root, context, work,
+team, capability, operation, settings and lifecycle metadata are removed.
+The command's explicit cwd and selectors (for example `--soul`) determine
+its dispatch; a scheduler invoked from another home must not select that
+home's frozen capabilities/settings. Host configuration (`HOME`,
+`OATS_HOME_DIR`, package catalog configuration) and ordinary credentials are
+preserved. No job schema or knowledge-provider policy is implied by this
+isolation.
+
+### Native record capture result
+
+`oats capture --home <dir>` (also `turn-record capture --home <dir>` and the
+standalone `capture.mjs`) answers **native JSON**, not a Desktop schema-v1
+`{ok,result}` envelope. Do not add `--json`: `--home` already selects JSON.
+Diagnostics go to stderr, including lock contention without `--quiet`.
+Existing home/owner/appended/session boundary fields remain; the outcome adds:
+
+- `status`: `complete`, `skipped`, `held`, `incomplete`, or `failed` (failure
+  takes priority, then skip/held/incomplete).
+- `complete`: true only for a performed pass with no holds, incomplete source
+  records, unattributed candidates or reported errors.
+  An unchanged performed pass may be complete with `appended: 0`.
+- `skipped`: true when another pass owns the capture lock. `lock` then carries
+  holder/liveness/recovery details; no capture or indexing was performed.
+- `held`: count of sessions the underlying pass held pending a timestamp.
+- `incomplete`: count of source files with pending torn, oversized, invalid
+  UTF-8 or otherwise incomplete records; later complete input can recover.
+- `issues`: optional metadata-only diagnostics identifying source paths and
+  reasons; no record bodies are embedded. `unattributed` candidates also make
+  the pass incomplete rather than silently certifying missing source evidence.
+- `failed`: zero on success, nonzero for a capture/read/index/lock-release
+  failure; `error` describes the failure. `appended: null` on a thrown failure
+  means the number appended before the failure is unknown, not zero.
+- `ignored`: count excluded by configured privacy rules, distinct from a
+  whole-pass skip. Home capture pins exactly attributed source files; sharing
+  a Codex day directory does not authorize capturing unrelated records.
+
+Lock skips, held sessions and incomplete input retain exit status 0 (background reconciliation
+must stay nonfatal on contention); errors and failed lock release exit 1.
+Previously captured visible boundaries may still be returned on a skipped or
+held pass. They are **not** evidence that final capture ran. Consumers requiring
+a final pass must check `complete === true`, not exit status or the presence of
+boundaries alone; older results lacking that field cannot certify a pass.
+
+**Snapshot boundary:** completion describes a performed pass over the exact
+attributed source files, not a promise about future appends. Discovery carries
+an open-descriptor-derived identity and content witness through capture-lock
+acquisition. Capture stages bytes from one descriptor and validates that witness
+and source stability **before appending**: replacement, truncation and prefix
+rewrites fail without appending the replacement's bytes. Same-inode append
+growth is allowed only when the witnessed prefix is unchanged. Discovery/read
+failures and files disappearing during the pass fail closed; pending trailing
+records and unattributed candidates cannot certify completion. A retirement
+consumer must first quiesce its writers and then preserve the captured evidence
+under its own durable-input protocol. `complete:true` alone does not mean a
+harvest was delivered or that a consumer stored those inputs. Configured privacy
+exclusions remain exclusions, not an invitation to copy excluded source bytes.
+
+**Native roots:** managed `--home` capture uses independent execution history,
+not the observer's environment or the latest relaunch recipe. New scaffolds
+initialize `<instances>/.oats-native-record/<sha256(canonical-home)>/history.json`.
+Each managed spawn/start/restart writes a separate pending receipt before
+backend dispatch. Inside the backend shell, under the exact environment prefix
+and cwd that will exec the harness, the native recorder atomically replaces
+that receipt with the effective absolute **record locations** and runtime. Only
+these allowlisted locations, home, start id/time and custody state are saved;
+no environment map, credential reference value, task or argv is persisted.
+The saved `instance.json` command/recipe remains a relaunch **template**, not
+execution evidence: use `oats session start`, not a manual shell replay of it.
+
+Location rules at execution are `CLAUDE_CONFIG_DIR/projects` (default exactly
+`$HOME/.claude/projects`), `PI_CODING_AGENT_DIR/sessions` (default
+`$HOME/.pi/agent/sessions`), and `CODEX_HOME/sessions` (default
+`$HOME/.codex/sessions`). Pi's `--session-dir` wins over
+`PI_CODING_AGENT_SESSION_DIR`, which wins over its agent-dir location; Pi tilde
+paths expand against the effective HOME. Relative paths resolve from the source
+home. Existing symlinks resolve at recording time, including existing ancestors
+of not-yet-created roots. Inherited overrides and resolved `fromEnv` location
+inputs are thereby retained **after backend shell startup**, independently of
+later observer/config/reference changes. The recorder runs before the native
+exec; unsupported explicit Pi `--session` or a receipt write failure refuses
+that exec and leaves pending custody, rather than claiming a default root.
+Wrappers must preserve this native storage contract: arbitrary scripts which
+change storage internally cannot be inferred from their executable name.
+
+History is never replaced by a newer runtime selection, truncated with the
+bounded restart log, or deleted with the source home. Capture unions all
+historically recorded locations for each runtime and still attributes every
+file by its own cwd. Missing/unreadable historical roots, unreadable/invalid
+receipts, and pending/unfinished launches fail closed. A newly scaffolded home
+with no managed launches has an authoritative empty managed-launch inventory.
+A legacy home without that scaffold authority cannot acquire proof of its
+**earlier** roots merely by restarting: later starts retain new locations but
+its history remains incomplete. Do not remove pending/history receipts just
+to get a green capture; recovery requires establishing the source inventory.
+
+Standalone fixtures and explicit legacy inventories can opt into
+`capture --home <dir> --current-roots` (`sourceRoots: "current-env"` in JSON),
+or use `sessionsForHome(home, {roots: {cc: [...], pi: [...], codex: [...]}})`.
+Explicit API roots exclude unspecified formats, and every supplied root must
+exist. The CLI fallback uses current environment plus recorded hook/config
+location overrides; `fromEnv` resolves from that **current** base environment.
+Its `complete:true` certifies only that chosen observer-time inventory, **not**
+all historical roots; do not enable it implicitly for final-capture consumers.
+Normal managed reports say `sourceRoots: "launch-history"`. Background capture
+without `--home` retains observer-time discovery (including `.claude*` profiles)
+and optional absent native defaults. Neither fallback introduces knowledge
+policy into the kernel.
+
+**Claude children:** discovery also enumerates the native
+`<project>/<sessionId>/subagents/*.jsonl` layout, including children whose parent
+transcript is absent. Each child requires its own cwd attribution; neither its
+parent's cwd nor its directory supplies missing attribution. Child streams use
+`cc.<sessionId>.<child-file-stem>` (threads
+`cc:session:<sessionId>.<child-file-stem>`) so identical child filenames under
+different sessions cannot collide. Complete native lines are preserved verbatim;
+torn, unstamped or unattributed child evidence blocks certification, and child
+read/discovery failures fail the pass. Ignore rules run before child opens and
+can match its path, filename, qualified id, native child id or parent session id.
+
+**Piped recall:** native `oats recall` JSON responses drain stdout before process
+termination, including large thread windows and individual `--show` records.
+Consumers must still bound their own reads/buffers (use `--ids-only` for sizing);
+a successful producer does not imply an unbounded consumer buffer.
+
 ### Consumer fixture
 
 The engine ships a consumer fixture driving the full oats.okf pattern

package/docs/desktop-cli-api.md

@@ -18,7 +18,8 @@ prints exactly one JSON object on stdout:
 ```
 
 `version` is the installed package's exact semver (e.g. `0.20.0`).
-Desktop 0.22 accepts `desktopApi === 1` and semver `>=0.22.0 <0.23.0`.
+Desktop 0.23 accepts `desktopApi === 1` and semver `>=0.22.0 <0.24.0`
+(the earlier Desktop 0.22 band was `>=0.22.0 <0.23.0`).
 
 Optional features are negotiated from the probe's `features` array. Starting
 an existing home requires `session-start`; named launch configurations and
@@ -113,7 +114,7 @@ See [launch configuration syntax](configuration.md) and
 | `instance` | string          | new instance name                          |
 | `agent`    | string          | soul/agent name                            |
 | `home`     | string          | absolute instance home path                |
-| `work`     | string          | work mode (worktree/checkout/attached/workspace) |
+| `work`     | string          | work mode (worktree/checkout/attached/workspace/directory) |
 | `branch`   | string \| null  | work branch when applicable                |
 | `launched` | boolean         | whether a tmux window was started          |
 | `warnings` | string[]        | non-fatal warnings (always an array)       |
@@ -138,18 +139,66 @@ subcommand), `E_CAPABILITY_INACTIVE`, `E_CAPABILITY_BLOCKED` (untrusted),
 `E_CAPABILITY_BROKEN`, `E_DUPLICATE_NAMESPACE`, `E_CONFIG_BROKEN` — all still
 exactly one stdout envelope with a nonzero exit.
 
-### `oats okf harvest --json`
+### Knowledge operations and OKF v2
 
-Run with cwd fixed to the resolved instance home. `result` is one of:
+Discover provider-declared operations rather than assuming a particular memory
+format. The knowledge capability's version owns its result shape; CLI API v1
+does not freeze the old OKF v1 `harvest: spawned|skipped` body for every provider.
+See [knowledge](knowledge.md) for the prepared OKF 2.0.0 version scope.
+
+```bash
+oats operation run knowledge:inspect --home /absolute/source-home --json
+oats operation run knowledge:harvest --home /absolute/source-home --json
+```
+
+The operation runner preserves the provider view/action through the ordinary
+operations contract. Direct `oats okf inspect` returns the standard JSON-v1
+success/error envelope. Its result includes:
+
+- `summary`, durable `source`, frozen `owns`, `reads`, `bases`;
+- `acceptedView` (the registered snapshot, not a fresh read), `status` with
+  capture/processing/delivery/acceptance receipts, and `scheduler` diagnostics;
+- `liveMemory: {available, reason, observedAt}` and labeled `documents`.
+
+Live Markdown documents are `Working state (STATE.md)`, `Log (log.md)` and
+sorted `Pending note: <relative-name>`, including nested notes. Missing files
+are omitted; durable receipts follow as a text document. Only a live source
+whose pointer/metadata still matches may supply live memory. Retired, missing,
+reused or unverified homes return durable documents and explicit unavailability.
+Unsafe live documents fail instead of returning a partial success. Inspection is
+read-only and does not capture, refresh, schedule or launch a model.
+
+The explicit preview limit is **256 KiB per document**, with `truncated: true`
+and original `bytes` for larger files. Smaller files are byte-exact. The complete
+JSON envelope drains stdout; consumers must not clip it at a small output-buffer
+limit. Provider `read` returns full Markdown, not this inspection preview.
+
+After the home disappears, operate from durable deployment context:
+
+```bash
+oats okf inspect --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+oats okf refresh --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
+```
+
+Every descriptor-selected read/refresh creates its new view under that source's
+state directory, not the invoking repository or a replacement home.
+
+Direct `oats okf harvest --json` captures notes and record and requests an
+independent directory worker. Representative result shapes (not exhaustive):
+
+```json
+{"status":"running","run":"<run-id>","instance":"<worker-instance>","home":"/absolute/worker-home"}
+```
 
 ```json
-{"harvest":"spawned","instance":"memory-harvest-<slug>","window":"memory-harvest-<slug>"}
-{"harvest":"skipped","reason":"no pending notes"}
+{"status":"empty","processed":true}
 ```
 
-Failure: `{"schemaVersion":1,"ok":false,"error":{"code":"E_HARVEST_FAILED","message":"..."}}`
-with exit 1. Skip reasons are human-readable strings (loop guard, no notes,
-no root, no identity, harvester already running, workspace-mode soul not in a
-git repo).
+An explicit `--no-launch` request can return `status: "ready"` without starting
+a model; existing runs report their current status without starting duplicates.
+Nonzero errors use the ordinary JSON-v1 error envelope. `running`/`ready` are not
+successful knowledge delivery. Inspect and reconcile provider receipts; never
+infer acceptance from a launch or from a worker disappearing.
 
-Contract tests / canonical fixtures: `test/cli-json-contract.test.mjs`.
+Kernel envelope/dispatch tests live in `test/cli-json-contract.test.mjs`;
+provider-specific behavior is qualified against the exported OKF runtime.

package/docs/execution-targets.md

@@ -148,6 +148,22 @@ and never silently applies a new model to an
 already-running harness. A never-launched legacy Herdr home without a saved
 server endpoint requires that endpoint to be configured before it can start;
 it does not fall back to tmux.
+Directory-mode starts and restarts also authenticate the home and owned work
+root against the independent spawn receipt (mode, canonical home, device/inode
+identities). Checks run before resolving mutable home contents, after **each**
+launch hook/preparation and immediately before backend observations, stops,
+allocations and launch-state writes. A missing/file/symlink/exchanged root or
+mode disagreement fails with `E_WORK_INSPECTION_FAILED`; substituted targets
+are neither followed for launch nor removed for lock cleanup. Restore the
+original owned roots before retrying; pending receipts remain with them.
+These pathname checks are not OS-level exclusion against a concurrent hostile
+filesystem mutation between validation and use.
+
+Managed execution also records independent native transcript-location history;
+the recipe remains a template, not provenance. See
+[Native roots](design/package-runtime-api.md)
+for the exact source and standalone-fallback semantics.
+
 The start opens a new harness conversation on the instance's `TASK.md`; the
 instance resumes its work from its own `STATE.md`, as the knowledge protocol
 prescribes.

package/docs/first-team-demo.md

@@ -4,6 +4,10 @@ On 2026-09-05 we installed the published OATS artifacts and used Pi and
 Claude Code workers to fix issues found during a fresh review. The first
 team's work was release preparation in this repository.
 
+> **Historical v1 qualification.** The results below remain evidence for the
+> named versions, not the prepared v2 runtime. Current setup, external ownership
+> and independent delivery are in [the first-team guide](first-team.md).
+
 ## The setup
 
 | Component | Qualified value |
@@ -82,6 +86,7 @@ The run found first-use problems that unit tests alone had not resolved:
 - A combined workspace roster did not make the workspace a spawn scope for
   every child repository. Commands select the owning repository explicitly.
 
-The [first-team guide](first-team.md) includes these setup details. The
+The [first-team guide](first-team.md) now describes the prepared v2 setup;
+these historical v1 outcomes are not v2 acceptance evidence. The
 package owners are responsible for improving their defaults; the kernel
 continues to resolve capabilities through the same replaceable contracts.