@awebai/oats 0.24.7 → 0.24.9

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

@@ -0,0 +1,107 @@
+# OATS v0.24.8 — lifecycle plans, readiness, spawn preview, instance events, and guarded Stop/Remove in the Desktop
+
+Kernel/Pi/Desktop **0.24.8**. Tag `v0.24.8` → the commit carrying these notes
+(the last code change is `508fda04`, PR #69). The npm tarball's `gitHead` is
+the tagged commit; the version-bump commit lands after the tag. All new
+contracts are **advertised**: consumers gate on `oats version --json`
+`features[]` names and the API integers below — never on the version number,
+never by optimistic invocation.
+
+## Kernel — the remaining Desktop-parity seams (K3, K5, K6, K7, K8)
+
+- **Lifecycle plans** (K3, `lifecycleApi: 1`, feature `lifecycle-plans`):
+  `oats instance stop <i> --plan|--apply` and `oats retire <i> --plan`, then the
+  **guarded apply** `oats retire <i> --plan-revision <rev> --idempotency-key <key>
+  [--discard-worktree] [--delete-branch]`. A plan states producer facts (ordered
+  targets deepest-first, session/work facts, recorded children, `midTask:
+  "unknown"` never inferred) under a 24-hex `planRevision`; apply re-reads and
+  refuses `E_PLAN_STALE` (fresh plan attached) when facts moved. Keys replay
+  their own receipt instead of acting twice — stop receipts are stored **per
+  key**, retire receipts survive the home's removal.
+  - **Retention by default** (feature `retire-retention`): a plain retire
+    re-homes the worktree to `<workspace>/.agents/worktrees/<repo>/<branch>`
+    instead of deleting it; `--discard-worktree` removes; `--delete-branch`
+    deletes the branch the tree is **verified** to be on and implies discard.
+    Receipt `retention {worktree: retained|removed|absent, movedTo, branch,
+    recordedBranch, branchDeleted?, branchDeletionSkipped?}`; a failed move is
+    `E_WORK_PRESERVATION_FAILED` with the home kept.
+  - **Children first, kernel-owned.** A guarded retire stops the plan's recorded
+    children (bounded SIGTERM, never escalated) and retains them; a child still
+    running refuses the whole retirement — `E_CHILDREN_RUNNING`, nothing retired.
+  - **Branch deletion is bound to the confirmed branch**: re-verified at deletion,
+    after hooks (which may mutate the tree); a mismatch deletes nothing and
+    reports `branchDeletionSkipped {expected, actual, reason}`.
+  - **Ambiguous parentage is reported, never acted on**: parent edges are bare
+    names; one that resolves to several homes appears under `ambiguous[]`
+    (`plan.ambiguous` on stop, `plan.facts.ambiguous` on retire).
+  - A pre-plan CLI does not understand `--plan` and would retire on it; that is
+    exactly why the feature is advertised — consumers must gate.
+- **Readiness** (K5, `readinessApi: 1`): `oats readiness [--soul] [--home]
+  [--verify-signatures] [--policy] --json` — the quartet
+  installed · trusted · configured · enrolled, each `pass|fail|unknown|not-applicable`
+  with items `{subject, required, reason, producer, evidence, remedy}`;
+  `summary.ready` is never vacuous. Signatures are `unknown` unless
+  `--verify-signatures` (an explicit one-commit fetch; `verified|unsigned|invalid`
+  with the signer named). Enrolled = workspace-member admission.
+- **Enforced child policy** (K5): soul `children: {spawn: bool}`, spawn
+  `--allow-child-spawns|--no-child-spawns`, recorded as `instance.json`
+  `policy.childSpawns {allowed, origin}`; a spawn with `--parent` under an off
+  policy refuses `E_CHILD_SPAWNS_DISABLED`. `inspect --json` souls carry
+  `declarations.children`; capability rows carry `commit`.
+- **Spawn preview** (K6, `spawnPreviewApi: 1`): `oats spawn … --preview --json`
+  states the decision — instance name, home, worktree, branch, base `{ref, oid}`,
+  runtime/model/launch config, work mode, composition sources, policy — without
+  creating anything. `--base <ref>` picks the base; `@native-default` names the
+  runtime's own default explicitly.
+- **Instance events** (K7, `eventsApi: 1`, feature `instance-events`):
+  `oats instance events <i> [--limit] [--since] --json` — typed, producer-
+  attributed lifecycle events (spawned, launched, restarted, stopped,
+  stop-refused, retire-planned, retired, worktree-retained, branch-deleted,
+  child-spawn-refused, recomposed) from the home's log and the workspace's
+  retained copy; truncation and unreadable lines are visible, never smoothed.
+- **Schedule run history** (K8, `scheduleApi: 2`, feature `schedule-history`):
+  schedules report `recentRuns` — settled runs only, producer order, ≤ 50.
+- **Instruction refresh** (feature `session-recompose`): `oats session recompose
+  --home <abs> [--dry-run] --json` recomposes a **live** home's `AGENTS.md`
+  from its current soul with the same composer spawn used; previous text is
+  retained beside it, `instance.json` and a `recomposed` event record it,
+  nothing is restarted. An operator action for when a role changes and a
+  respawn is not possible or wanted.
+- Remote workspaces: `oats instance git|diff` reach a remote instance through
+  the negotiated route (K1 remote), refusing rather than guessing where no
+  route exists.
+
+## Desktop (parity slices 2b and 2c)
+
+- **2b — Connections.** Settings → Connections with an inline "Connect
+  GitHub" (device flow through `gh`, credential custody stays with `gh`; the
+  auth pane is a closed key set with redaction). The Git & GitHub panel gains an
+  observation-bound PR card: informational, correlated to the exact K1
+  revision/branch/remote, never authority. Forge connections are an **ADE
+  integration**, not a capability.
+- **2c — Stop and Remove.** The instance menu offers *Stop…* and *Remove
+  instance…*; both open a plan-backed confirmation showing the kernel's exact
+  targets, skipped/ambiguous children, session and work facts, the real branch
+  (recorded-branch drift noted separately) and retained-by-default choices.
+  One guarded local route; the plan is read from the CLI, each confirmation
+  gets an opaque reference, the idempotency key is minted on the first
+  confirmation and kept for that intent's retries, one apply at a time; lost
+  responses are shown as **unknown outcome**, never "no effect". Stale plans
+  require a new confirmation; a refused child stop names the child. The old
+  unguarded retire route now answers `E_PLAN_REQUIRED`.
+- Everything above is **unavailable** (not hidden, not guessed) when the
+  installed CLI does not advertise the corresponding feature.
+
+## Also
+
+- Lessons recorded: consumers gate on advertised features, never on
+  optimistic invocation; a declaration that suppresses a default must be
+  enforced; read-only Git observation is a security boundary.
+- Verification budget: one full gate per change is PR CI; locally only the
+  affected suites. Desktop-only changes run the Desktop suites plus the
+  focused suite.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.8`, then `oats doctor`. Desktops pinned to an
+older CLI keep working; new controls appear as the CLI's advertised features do.

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

@@ -0,0 +1,67 @@
+# OATS v0.24.9 — readiness pins, side-effect-free spawn preview (API 2), process-group safety, Desktop Readiness view
+
+Kernel/Pi/Desktop **0.24.9**. Tag `v0.24.9` → the commit carrying these notes;
+the version-bump commit lands after the tag. Consumers gate on `oats version
+--json` `features[]` names and API integers — never on the version.
+
+## Kernel
+
+- **Spawn preview API 2** (feature `spawn-preview-2`, `spawnPreviewApi: 2`).
+  API 1 previews **wrote before they returned** — a refused child spawn appended
+  an event to the parent, a Herdr backend could be started, an unknown soul
+  could be imported from an importable def — and nothing bound a later spawn to
+  the previewed decision. API 2: a preview touches nothing, success or refusal
+  (proven by a byte-identical deployment tree); `spawn --agents-root <abs>`
+  binds the exact root with no fallback and the preview echoes `subject` as
+  given; `decision {instance, home, branch, base, revision}` + `spawn
+  --expect-decision <rev>` refuses **`E_DECISION_STALE`** with the fresh
+  decision on any drift (no auto-suffix, no silent re-base, nothing created);
+  every native probe shares one bounded preflight budget and is process-group
+  killed on timeout (`preflight {status, budgetMs, elapsedMs}`). **Gate on API
+  2 — API 1 is the pre-fix marker.**
+- **Readiness pins** (`oats readiness`): `configured` is *effective* activation
+  (a capability declared for the soul but disabled is a fail that says so);
+  data-only capabilities (skills/inject, no commands/hooks/env) report trust
+  **not-applicable** — the inspect row carries `health.executableSurface`;
+  every item is typed (`capability {id, level, scope}`, `origin {kind,
+  target}`) and `summary.byCapability[]` regroups the same items with
+  `ownReady` vs `ready` (never ready under a `summary.subjectBlockers[]` item
+  such as unknown membership); `subject.selector` echoes the arguments as given,
+  byte-exact; an unreadable member document is `unknown`, not not-applicable;
+  `readiness --home <captured>` refuses `E_UNSUPPORTED_MODE`; `--agents-root`
+  documented. **Signature verification** (feature `readiness-verify`) is
+  bounded custody: one budget per read, process-group kill, cleanup on
+  SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL=/dev/null`, https/ssh only, a closed
+  `signature.failure.code` — never stderr.
+- **Process-group safety (high).** Bounded-custody code killed a child's
+  process group on timeout with `process.kill(-child.pid)`; a **failed** spawn
+  (binary missing → `ENOENT`) reports `pid: 0`, and `kill(-0)` signals the
+  caller's own process group — `oats readiness --verify-signatures` without
+  `git` would have SIGKILLed the operator's shell/tmux/Desktop backend. One
+  guarded helper now refuses non-positive PIDs at every kill site.
+- **OKF 2.1.3** mirrored and pinned in the official catalog: per-cause `check`
+  reasons, a named remedy when a soul has no `okf.json` (was a raw ENOENT from
+  the required spawn hook), retired drained sources switch their `okf-<id>` job
+  off.
+
+## Desktop
+
+- **Readiness** (frame 09/04): Workspace header entry and first-run
+  invitation; the quartet from `oats readiness` with items, remedies (display
+  only), *View policy*, *Skip for now* (presentation only). Verify signatures
+  and Enrol are shown unavailable with the exact reason until their contracts
+  land. Effective-readiness section per scope on the Capabilities view.
+- **Normalized route classification**: one classifier decides every specialized
+  IPC route from the normalized pathname — dot-segment, percent-encoded,
+  backslash, tab and CRLF aliases can no longer skip a route's frame/epoch
+  guard.
+- Spawn modal: kernel **preview** (API 2) for the instance name, home, worktree,
+  branch and resolved base — *Suggest* asks the kernel for its default
+  candidate; preview-only choices block legacy submission rather than being
+  dropped. Apply companion, attach-knowledge, auto-PR and branch enumeration are
+  named follow-ups, not parity-done.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.9`, then `oats doctor`. Desktops on an older CLI
+show the new controls as unavailable until the CLI advertises them.

package/docs/workspace-adoption.md

@@ -107,7 +107,10 @@ onboarding and legacy roster/knowledge cutover remain separate.
   production store or grants are supplied. An acceptance fixture is parent-owned
   and cannot be counted as production knowledge adoption.
 - Current authored expert editions require knowledge **oats.okf@2.1.2** and
-  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), not optional defaults. These published revisions
+  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), not optional defaults.
+  The official catalog now offers **oats.okf 2.1.3** (per-cause `check` reasons,
+  a named remedy for a soul without `okf.json`, retired sources switch their
+  job off); editions move to it when their owner re-reviews them. These published revisions
   are **not proof that their combined bindings/runtime profile is ready**. The provider
   owner supplies that evidence and any subsequently reviewed compatible revision.
   Do not replace either requirement with none or erase a read edge to launch.

package/docs/workspaces.md

@@ -71,7 +71,7 @@ name: domain-expert
 requires:
   knowledge:
     capability: oats.okf
-    source: git:github.com/awebai/oats-okf@v2.1.2#oats-package
+    source: git:github.com/awebai/oats-okf@v2.1.3#oats-package
 ```
 
 This illustrates software selection, not complete OKF provisioning: the chosen capability also needs its own valid knowledge declaration, bindings and accepted base.