@awebai/oats 0.39.0 → 0.39.2

package/docs/design/2026-10-01-instance-cloning.md

@@ -0,0 +1,106 @@
+# Instance cloning: the `oats.cloning` package
+
+Status: **DECIDED 2026-10-01** by the maintainer with the steward (the transcript handling revised
+2026-10-02 by the human: "cloning just works"). Shipped as `oats.cloning` 1.0.0
+([awebai/oats-cloning](https://github.com/awebai/oats-cloning)), compatibility `oats >=0.34.0`.
+
+## Context
+[Knowledge theory](../knowledge-theory.md#reusing-working-understanding-context-handoffs-and-cloning)
+accepted cloning in principle and left it open: harvesting preserves individual lessons, not the
+combined working picture of a long-running instance. A clone should carry selected references,
+verified observations and provisional reasoning marked as such, under its own identity, credentials
+and ownership, and copying it promotes nothing to shared knowledge.
+
+## Decision
+1. **A capability, not a kernel change.** Everything cloning needs already exists in the kernel:
+   `oats status` and `instance.json` to find and describe the source, `oats capture`/`oats recall`
+   for its transcript, `oats spawn` with `--relation`/`--relative-to`, the launch flags and `--base`,
+   `--preview` then `--expect-decision`, `oats session upload`/`session start`, and
+   `oats retire --self`. No config key, manifest field, hook variable or lock format changes. The
+   capability has no lifecycle hooks, so it cannot break a composing soul's spawn.
+2. **Three roles.** The *requester* (an instance with the capability, or the operator from the
+   deployment with `--soul oats.cloning/cloner`) runs
+   `oats cloning request <source> --goal … --relation independent|child|sibling|parent`. That spawns
+   a short-lived *cloner* (the package soul `oats.cloning/cloner`, `knowledge: none`), which reads the
+   source (`dossier`), writes a brief and a plan (`/plan-clone`), spawns the *clone* (`spawn`:
+   preview, apply, verify), reports and retires itself. The clone is an ordinary instance of the
+   source's soul; nothing about it is special to the kernel.
+3. **The requester chooses only what is theirs:** the goal, the relation and its anchor (the source
+   by default, never the cloner, which retires), the name, whether the transcript is read, and the
+   work base. `independent` is the kernel's `unrelated` and takes no anchor. The cloner decides what
+   the clone carries, and asks the requester only when a choice is genuinely theirs.
+4. **The clone carries a curated brief, not a copy.** A generated preamble (a provenance block and
+   fixed "you are a clone" text) and the cloner's body under fixed headings: the goal verbatim,
+   what is verified (each with its evidence), decisions and why, working understanding marked
+   provisional, open threads and who owns them, work state, where to look (transcript turn ids are
+   citations), and what was not carried. Inherited material is not new evidence: the clone notes it
+   only after re-verifying it. Its commitments, PRs, threads and children stay with the source
+   unless the brief says they were handed over.
+5. **Read-only on the source, bounded.** `dossier` copies a filtered `instance.json` (never the
+   command, environment, hooks, `capabilityMeta` or any credential locator), `TASK.md`, `STATE.md`,
+   `log.md` and `notes/**/*.md` as regular files contained in the home, with size budgets. It never
+   reads identity material, `.oats*`, attachments or the regenerated `AGENTS.md`. Work state is read
+   with read-only git: branch, HEAD, ahead/behind, commit subjects, changed paths and a diffstat,
+   never diff content; a directory work tree is only listed.
+6. **The transcript is included by default, through a temporary record.** `--transcript exclude`
+   opts out. The cloner captures the source into a private record in its own home
+   (`oats capture --root`, 0700), copies the host's capture ignore list into it (and captures nothing
+   if that list exists but cannot be read), reads it with `oats recall --root`, and deletes it. The
+   host's own record is never written, so a source the host chose not to capture stays uncaptured.
+7. **Security requirements, each tested.**
+   - *Redaction, not refusal.* Before the clone can see anything, `spawn` redacts the whole assembled
+     brief, preamble included, with a fixed set of patterns: PEM private keys, provider tokens and
+     keys, JWTs, Bearer tokens, credentials in URLs, and uppercase assignments such as
+     `API_TOKEN=…` or `PASSWORD: …`. Each match becomes `[redacted:<pattern>]`; the receipt and the
+     answer list `{line, pattern}`, never the value. Where a pattern's boundary is ambiguous it
+     redacts more rather than less. Redaction is pattern-limited: a form no pattern recognises
+     survives it, so the `/plan-clone` exclusions stay the policy and redaction is the seatbelt.
+   - *The brief lives only in the clone's home, mode 0600.* `claude` and `codex` launches pass
+     `TASK.md` as an argument, visible to other local users. So the clone is spawned `--no-launch`
+     with only the preamble and a pointer in its task, the brief is attached with
+     `oats session upload` (0600), `TASK.md` is made 0600, and only then is the session started.
+     `spawn` verifies the modes, the attachment's sha256 and the provenance block byte for byte.
+   - *A fresh messaging identity.* `spawn` never passes identity settings, and after the start checks
+     that the clone's alias is its own instance name and its identity differs from the source's
+     (`E_CLONE_IDENTITY` otherwise; a resident identity tied to the source's is refused before the
+     spawn).
+   - *The plan cannot escalate.* `spawn` enforces that the plan matches the request and the source:
+     the soul, relation, anchor and name; the source's launch settings (yolo and child spawns are never
+     escalated); `oats.okf harvest=off` carried when the source had it, never turned on; a base only
+     for worktree souls.
+8. **Cleanup survives retirement.** Retirement keeps a changed home in recovery storage, so the
+   cloner cannot rely on its home being deleted: once the apply has run, it empties `clone/` except
+   `receipt.json` (which holds no source text), and a later run first removes an earlier run's
+   leftovers. A refusal before the apply deletes the temporary record and keeps the brief and plan
+   for a retry. Known limit: a cloner killed mid-run and then retired from outside leaves its
+   `clone/` (0700) in recovery storage.
+9. **Packaging.** Its own repository and package, `oats.cloning`, mirrored and pinned in this
+   repository like the other official packages, with a member expert soul (`oats-cloning-expert`)
+   beside the package soul. **Not a workspace default:** only the souls that request clones compose
+   it (`oats.cloning: { from: package }`), and it becomes a default later on evidence of use. The
+   workspace pins it as `git:github.com/awebai/oats-cloning@v1.0.0` until every deployment's CLI
+   carries the catalog entry, because a bare version is `E_PACKAGE_MISSING` on a CLI without it.
+
+## Rejected
+- **A raw transcript fork** (resuming or forking the source's harness session). It copies identity
+  statements, home paths, secrets and half-finished reasoning as if settled, is harness-specific,
+  and carries no notion of what is still true. The brief is a curated reading, not a replay.
+- **Copying `notes/` into the clone.** Notes are the source's evidence; copied, they would be
+  harvested a second time as the clone's own.
+- **The brief in `TASK.md`.** World-readable by default and passed on the command line.
+- **A refuse-on-match secret scan.** It stops a clone over one stray token; redaction removes the
+  value and still reports where it was.
+- **An operator consent step per clone** (dropped by the human), and an acknowledgement flag for
+  sources the host does not capture. Both are procedural gates: same-user agents can already read
+  the host record, and the temporary record makes neither necessary.
+- **Shipping inside `oats.framework`** (deployable with a bare pin today). Rejected for a standalone
+  package identity, as the human asked. **A second package inside this repository** was rejected
+  too: a `git:` pin always reads `oats-package/`, so it would carry the costs of both options.
+- **A workspace default** in v1: no evidence yet that every soul needs it.
+
+## Out of scope (v1)
+Cloning across machines or from a retired instance; cloning into a different soul (that is a
+handoff); asking a live source to write its own handoff; carrying work-tree content, uncommitted
+changes, attachments, schedules, joined teams or children; a Desktop "Clone" action; kernel
+provenance fields such as `clonedFrom`; the knowledge harvester skipping inherited material in a
+clone's transcript (the preamble marks it instead).

package/docs/desktop-cli-api.md

@@ -468,6 +468,17 @@ confirmed member (`evidence: {repoKey, workspace, commit}`); `fail` when not
 (the remedy names `oats-membership.yaml`); `unknown` when the workspace could
 not be read. External souls and standalone views are `not-applicable`,
 `required: false` (a standalone item carries `evidence.standaloneReason`).
+A package soul is trusted through the workspace's `packages:` pin, never
+through membership ([the non-collapse rule](workspaces.md#member-tier-vs-package-tier-the-non-collapse-rule)):
+its item is `package <package>/<soul>` (producer `workspace lock`,
+`evidence: {repoKey, workspace, commit, version, integrity, from}` with
+`from.kind: "package"`). It passes when the package is declared and locked
+and ships the soul at the locked commit, and the soul's copy is intact: for
+`--soul`, the copy a spawn would link matches the locked digest; for
+`--home`, the home's copy matches the digest it recorded, and a lock still
+at that commit records the same digest. The copy is digested on every read.
+It fails otherwise, with `code: "E_PACKAGE_INTEGRITY"` on a digest mismatch
+and the remedy naming `oats sync` or a fresh spawn.
 
 **`providers`** (producer `provider binding check`): for each module whose
 manifest declares `binding`, the kernel runs its `binding.check` and relays

package/docs/integrations.md

@@ -41,7 +41,7 @@ arrives from.
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
   oats.okf: v4.1.1
-  oats.aweb: v1.21.0
+  oats.aweb: v1.21.1
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:
@@ -89,7 +89,13 @@ operations in full.
   `knowledge-maintainer` package soul reviews the resulting PRs.
 - **`oats.aweb`** mints a messaging identity for each instance at spawn and
   removes it at retire, contributes the aweb messaging skills, and wires the
-  channel so sessions are woken by mail. `oats aweb roster` lists the team:
+  channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
+  loads the channel plugin with `--dangerously-load-development-channels`,
+  since `aweb-channel` is not on its approved channel list, so every such
+  Claude start waits at Claude Code's
+  development-channels confirmation until someone answers it in the
+  instance's terminal; the start's warnings and readiness say so
+  (`channel-dev-confirmation`). `oats aweb roster` lists the team:
   its membership certificates and workspaces, one entry per alias with its
   sources, status and kind (global identities first), and says when either
   source is incomplete. After `oats server connect`, `oats aweb connect

package/docs/knowledge-theory.md

@@ -230,13 +230,15 @@ Directory bases use their own recoverable publication mechanism. Receipts state
 
 ## Reusing working understanding: context handoffs and cloning
 
-Harvesting preserves individual lessons, not the combined working picture that makes a long-running instance effective; a handoff or clone could carry selected references, verified observations and labeled provisional reasoning, but that is not a knowledge store and copying it promotes nothing. A clone would need its own identity, credentials and ownership, and no protocol for selecting and sharing such context is defined.
+Harvesting preserves individual lessons, not the combined working picture that makes a long-running instance effective. A handoff or clone carries selected references, verified observations and labeled provisional reasoning; that is not a knowledge store, and copying it promotes nothing.
+
+Cloning exists as the official `oats.cloning` package ([souls and instances](souls-and-instances.md#cloning-an-instance)). A clone is a new instance of the source's soul with its own identity, credentials and ownership. What it carries is a curated brief written by a short-lived cloner for the new goal: what was re-verified, with its evidence; decisions and their reasons; working understanding marked provisional; open threads and who owns them; and where to look, with transcript turn ids as citations. The cloner leaves secrets out of the brief, a pattern-based redaction pass catches the common forms that slip through, and the brief is attached to the clone as a 0600 file, never placed in its task text. A clone does not carry the raw transcript, the source's `notes/`, the content of its work tree or its uncommitted changes (a worktree clone starts from the source's committed branch, the soul's default or a requested ref), or its commitments: those stay with the source unless the brief says they were handed over. Inherited material is not new evidence; the clone records it in its own notes only after re-verifying it.
 
 ## Implementation boundaries
 
 The model's settled positions are those above: short- and long-running instances are both legitimate; the default is centralized, per-soul knowledge open to reviewed structural evolution; capabilities own their model and runtime behavior; the doctrine preserves expertise, not code descriptions or task residue; and structural change preserves provenance and running work. These are not CLI flags or configuration schemas.
 
-The default OKF capability implements consultation, capture, independent harvest and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
+The default OKF capability implements consultation, capture, independent harvest and maintainer review; it does not provide automatic per-soul provisioning, a co-located profile, automatic speciation, redirects or context cloning. Context cloning is a separate package, `oats.cloning`, not part of the knowledge capability. Proving the kernel's flexibility needs a genuinely different organization and learning model, not only Git and directory storage within OKF. Updating this document does not migrate existing deployments.
 
 ## Related documentation
 

package/docs/official-catalog.md

@@ -11,9 +11,10 @@ or workspace membership alone does not make a package official.
 |---|---|---|---|
 | `oats.framework` | `oats-framework/v1.5.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.21.0` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
+| `oats.engineering` | `v1.8.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
+| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
 

package/docs/packages.md

@@ -76,7 +76,7 @@ members:
 packages:
   oats.framework: v1.5.0
   oats.okf: v4.1.1
-  oats.aweb: v1.21.0
+  oats.aweb: v1.21.1
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.21.0                         # a catalog version
+oats package add oats.aweb v1.21.1                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```

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

@@ -0,0 +1,42 @@
+# OATS 0.39.1
+
+## Changed
+
+- **oats.aweb 1.21.1: a Claude Code start says that it will wait at Claude
+  Code's development-channels confirmation** (awebai/oats-aweb#44). Under
+  `delivery: channel`, Claude Code loads the `aweb-channel` plugin with
+  `--dangerously-load-development-channels`, because the plugin is not on
+  Claude Code's approved channel list. Claude Code then stops at its "Loading
+  development channels" confirmation before the session starts, and waits
+  until someone answers it in the instance's terminal. Unattended starts
+  (Desktop starts and restarts, automations, successors) waited there with
+  nothing saying so. Now:
+  - every spawn or start that adds the flag carries the warning
+    `channel-dev-confirmation` once;
+  - `oats readiness` reports it, without changing the status, for a home
+    whose last start was Claude Code under `channel`.
+
+  Nothing answers the confirmation on the human's behalf. Launch arguments
+  and settings are unchanged. `--channels` registers only plugins on Claude
+  Code's approved list; for a plugin not on it, Claude Code prints a startup
+  warning and the channel does not register. That list is Anthropic's
+  default, or a Team/Enterprise organization's managed
+  `allowedChannelPlugins`, which replaces the default and requires
+  `channelsEnabled: true`.
+
+## Fixed
+
+- **`oats readiness` no longer fails package souls on membership**
+  (awebai/oats#533). A package soul (`oats.okf/knowledge-maintainer`,
+  `oats.engineering/code-reviewer`, …) failed its `member` check with
+  "member <its package's repository>: not a member of the workspace", and the
+  remedy asked to list the package's repository in `members:`. A package
+  soul is trusted through the workspace's `packages:` pin, never through
+  membership (see [the non-collapse rule](../workspaces.md#member-tier-vs-package-tier-the-non-collapse-rule)).
+  Its `member` item is now `package <package>/<soul>`. It passes when the
+  package is declared and locked, ships the soul at the locked commit, and
+  the soul's copy matches its digest: for `--soul`, the copy a spawn would
+  link against the lock; for `--home`, the home's copy against the digest it
+  recorded, and the lock against that same digest while it still pins the
+  same commit. A mismatch fails with `E_PACKAGE_INTEGRITY`. Member and
+  external souls are unchanged. Spawn already applied this rule.

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

@@ -0,0 +1,64 @@
+# OATS 0.39.2
+
+## Added
+
+- **oats.cloning 1.0.1**, a new official package (catalog entry, workspace
+  member and pin, and the bundled mirror): clone an instance for a new goal.
+  `oats cloning request <source>` spawns the package soul
+  `oats.cloning/cloner`, which reads the source and writes a curated,
+  redacted brief, then spawns the clone with it attached and a fresh
+  identity. The clone gets no raw transcript, notes or work content. See
+  [instance cloning](../design/2026-10-01-instance-cloning.md).
+  - The framework's oats-expert, oats-kernel-expert, oats-desktop-expert,
+    integrations-expert, oats-operator-expert and oats-setup-admin souls take
+    it (`oats.cloning: { from: package }`); there is no workspace default.
+  - The workspace pins it as `git:github.com/awebai/oats-cloning@v1.0.1`
+    until every deployment's CLI carries this catalog entry; then the pin
+    becomes the bare `v1.0.1`.
+  - 1.0.1 over 1.0.0 (the first pin on main): secret assignments are
+    redacted in any case and as JSON or YAML keys (`password=…`,
+    `client_secret: …`, `"PASSWORD": "…"`), a quoted value to its real
+    closing quote. The README states what redaction does not catch, and that
+    under `delivery: channel` a Claude Code cloner or clone waits at Claude
+    Code's development-channels confirmation until a human answers it.
+  - Operators: run `oats sync` to lock the package; new spawns of those
+    souls get the capability. Running instances keep what they were spawned
+    with.
+
+## Changed
+
+- **Desktop: terminal text in the White and Solarized themes renders at the
+  stroke weight of a native macOS terminal with font smoothing.** Chromium
+  draws dark text on a light background lighter, so these themes' terminal text
+  looked fainter than the same font in a native terminal. Each theme now sets
+  its own text weight; Dark is unchanged, and bold text stays bold.
+- **oats.engineering 1.8.0** (catalog and workspace pin, and the bundled
+  mirrors; includes 1.6.0 and 1.7.0):
+  - **New capability `oats.maintainer`**: the whole maintainer job, generic.
+    It covers the overview of what's open, launching work, a direction and
+    architecture gate, review and merge at an exact head, release planning
+    and shipping with a verification checklist, cross-review between peer
+    maintainers, keeping the project clean, and a living roadmap,
+    architectural calls and coherence rules kept in the maintainer's
+    knowledge. Skills: `/maintainer-intake`, `/launch-work`,
+    `/direction-gate`, `/pr-review`, `/plan-release`, `/ship-release`,
+    `/cross-review-peer`, `/keep-it-clean`.
+  - **A maintainer is not an expert; no soul holds both roles.** The
+    maintainer launches work without leading it: `/launch-work` delegates it
+    to a live expert whose work it continues, or spawns the best-suited expert
+    with `--relation unrelated` as the effort's lead, never as its own child.
+    The lead coordinates the developers and experts it needs.
+  - **Knowledge and state.** Maintainers and experts consult their knowledge
+    before deciding, and keep their instance state accurate.
+  - **Experts tell a standing maintainer what they start** when a human
+    launches them directly.
+  - **Experts give unrelated work to a new expert** (1.6.0). New work goes to
+    a live expert only when it continues that expert's work or that expert's
+    context helps. Otherwise the expert spawns a new one: as its child when
+    the work is part of its effort, or with `--relation unrelated` when it is
+    independent, reporting to whoever asked.
+  - **Developers prefer this machine's reviewer override** (1.7.0). When
+    picking the reviewer's model, `/run-the-review-loop` reads what the
+    machine will launch (`launch.effective`, including an `oats-local.yaml`
+    `souls.launch` override), not only the soul's default. It keeps the
+    override when that runs on another harness than the developer's.

package/docs/souls-and-instances.md

@@ -387,6 +387,30 @@ If the workspace has a messaging capability such as aweb, spawned instances
 can also receive identities and coordinate with each other automatically. The
 tasks capability can provide shared work state while messaging provides conversation.
 
+### Cloning an instance
+
+A clone is a new instance of an existing instance's soul that starts from a
+curated brief of what that instance knows, for a new goal. It is not a copy of
+the source's home. Cloning is the official
+[`oats.cloning`](https://github.com/awebai/oats-cloning) package, not a kernel
+verb; a soul that may request clones composes it
+(`oats.cloning: { from: package }`). An instance with the capability runs:
+
+```bash
+oats cloning request <source> --goal-file goal.md --relation independent|child|sibling|parent \
+  [--relative-to <instance>] [--name <slug>] [--transcript exclude] [--base source|default|<ref>]
+```
+
+From the deployment directory the operator adds `--soul oats.cloning/cloner`.
+The relation is required and is the kernel's spawn relation of the clone to the
+anchor (`--relative-to`, the source by default); `independent` is the kernel's
+`unrelated` and takes no anchor. The request spawns a short-lived
+`oats.cloning/cloner`, which reads the source (its home files, work state and,
+unless excluded, its transcript), writes the brief, spawns the clone with its
+own identity, reports and retires itself. Only instances on this host can be
+cloned. [Reusing working understanding](knowledge-theory.md#reusing-working-understanding-context-handoffs-and-cloning)
+says what a clone carries and what it does not.
+
 ### Retire
 
 Retirement runs active capability retire hooks in reverse spawn order before the home disappears. The aweb

package/lib/instance-inspect.mjs

@@ -15,7 +15,7 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, realpat
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
-import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
+import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, soulCopyDigests } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
 import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
@@ -133,7 +133,8 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
     kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent, session: newSessionDefaults(deployment),
     recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
     subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
-    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
+    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
+      ...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
     workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
     modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
     payloads: obj(meta.providers) ? meta.providers : {},
@@ -189,7 +190,8 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
     kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
     soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
-      soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}) },
+      soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}),
+      ...(typeof soulEntry.package === "string" ? { package: { id: soulEntry.package, soul: soulEntry.name, version: soulEntry.version ?? null, commit: soulEntry.commit ?? null, integrity: soulEntry.digest ?? null } } : {}) },
     workspace: { key: discovery?.key ?? null, name: discovery?.workspace?.name ?? null, deployment, commit: discovery?.commit ?? null, standalone: discovery?.standalone === true },
     modules: (res?.modules || []).map((m) => ({ name: m.name, from: m.from ?? null, manifest: m.manifest ?? null, dir: null, module: m })).sort((a, b) => a.name.localeCompare(b.name)),
     payloads: obj(res?.payloads) ? res.payloads : {}, payloadOrigins: obj(res?.payloadOrigins) ? res.payloadOrigins : {}, slots: obj(res?.slots) ? res.slots : Object.fromEntries(LAYERS.map((l) => [l, null])), slotsFrom: obj(res?.slotsFrom) ? res.slotsFrom : {},
@@ -404,6 +406,48 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
     || (res.status === "ready" && res.problems.length)) return invalid();
   return { outcome: "result", result: { status: res.status, problems: codeMessages(res.problems), warnings: codeMessages(res.warnings ?? []) } };
 }
+/** The `member` item of a package soul. A package soul is trusted through the workspace's
+ *  `packages:` pin (the lock's commit and integrity), never through membership: its
+ *  repository is not a member and need not be (docs/workspaces.md, the non-collapse rule).
+ *  It passes when the discovery lists the soul from the lock (the package declared and
+ *  locked, the soul shipped at the locked commit) and the soul's copy is intact: for a
+ *  soul, the copy a spawn would link matches the locked digest; for a home, its copy
+ *  matches the digest it recorded, and a lock still at that commit records the same one.
+ *  A copy is digested every read: a complete copy is reused, never refetched. */
+function packageSoulItem(t, d) {
+  const p = t.soul.package;
+  const subject = `package ${p.id}/${p.soul}`;
+  const from = { kind: "package", package: p.id, version: p.version, commit: p.commit, integrity: p.integrity };
+  const evidence = { repoKey: t.soul.repoKey, workspace: d?.key ?? null, commit: p.commit, version: p.version, integrity: p.integrity, from };
+  if (!d) return item(subject, "unknown", { producer: "workspace discovery", reason: t.discoveryError ? `the workspace could not be read: ${t.discoveryError.message}` : "no workspace observation", evidence });
+  if (d.standalone === true) return item(subject, "not-applicable", { required: false, producer: "workspace discovery", reason: `standalone view (${d.standaloneReason ?? "explicit"}): the workspace's packages: is not read, so the package pin is recorded, not observed`, evidence });
+  const shipped = (d.packageSouls || []).filter((s) => s.package === p.id);
+  const live = shipped.find((s) => s.name === p.soul);
+  if (!live) {
+    return item(subject, "fail", { producer: "workspace lock", evidence,
+      reason: shipped.length ? `the version of ${p.id} locked in this workspace does not ship the soul ${p.soul}` : `${p.id} is not locked in this workspace's packages:`,
+      remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : `declare ${p.id} in the workspace's packages:, then oats sync` });
+  }
+  const integrity = (reason, remedy) => item(subject, "fail", { producer: "workspace lock", code: "E_PACKAGE_INTEGRITY", reason, evidence, remedy });
+  const lockRemedy = "oats sync (a lock that was edited: remove the entry and sync again)";
+  const copy = t.soul.copyError;
+  if (copy?.code === "E_PACKAGE_INTEGRITY") return integrity(copy.message, lockRemedy);
+  const dir = t.soul.soulDir;
+  if (!dir) return item(subject, "unknown", { producer: "workspace lock", reason: "the soul's copy is not available, so its integrity cannot be checked", evidence });
+  const expected = t.home ? "recorded" : "locked";
+  let digests;
+  try { digests = soulCopyDigests(dir); }
+  catch (e) { return integrity(`the soul's copy at ${dir} cannot be digested: ${e.message}`, `move ${dir} aside, then spawn again (a fresh copy is fetched and verified)`); }
+  if (!digests.includes(p.integrity)) {
+    return integrity(`the soul's copy at ${dir} digests ${digests.at(-1)}, not the ${expected} ${p.integrity}${t.home ? "" : " (the lock's)"}`,
+      t.home ? `the copy changed after its spawn, and a spawn reuses it: move ${dir} aside, then spawn a new instance of ${p.id}/${p.soul} (a fresh copy is fetched and verified against the lock)` : `move ${dir} aside, then spawn again (a fresh copy is fetched and verified against the lock); if the lock was edited: ${lockRemedy}`);
+  }
+  if (t.home && live.commit === p.commit && live.digest !== p.integrity) {
+    return integrity(`the lock records ${live.digest} for the same commit ${String(p.commit).slice(0, 12)}; this home recorded ${p.integrity} at its spawn`, lockRemedy);
+  }
+  return item(subject, "pass", { producer: "workspace lock", evidence });
+}
+
 /** The total time the providers check may take in one readiness read. */
 export const PROVIDER_CHECK_BUDGET_MS = 60_000;
 
@@ -430,9 +474,11 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
   }
   configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t));
   // member — the soul's member repository is a confirmed member of the workspace
-  // (oats-membership.yaml backlink observed over the remotes).
+  // (oats-membership.yaml backlink observed over the remotes); a package soul's is its
+  // package instead (packageSoulItem).
   const d = t.discovery;
-  if (t.soul.external) member.push(item(`soul ${t.soul.name}`, "not-applicable", { required: false, producer: "workspace discovery", reason: "an external soul is declared by the workspace; it has no member repository", evidence: { repoKey: t.soul.repoKey } }));
+  if (t.soul.package) member.push(packageSoulItem(t, d));
+  else if (t.soul.external) member.push(item(`soul ${t.soul.name}`, "not-applicable", { required: false, producer: "workspace discovery", reason: "an external soul is declared by the workspace; it has no member repository", evidence: { repoKey: t.soul.repoKey } }));
   else if (!d) member.push(item(`member ${t.soul.repoKey ?? "?"}`, "unknown", { producer: "workspace discovery", reason: t.discoveryError ? `the workspace could not be read: ${t.discoveryError.message}` : "no workspace observation", evidence: { repoKey: t.soul.repoKey } }));
   // A standalone view is an allowed mode (decision 10): membership cannot be confirmed
   // there by definition, so it is not a readiness requirement (as for an external soul).

package/lib/instance-resolution.mjs

@@ -16,7 +16,7 @@
  *
  *  Nothing here reads `oats-config.yaml`, an installed-capability directory or a
  *  per-soul `source:` — those do not exist in this model. */
-import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
 import { oatsError } from "./errors.mjs";
 import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace } from "./workspace.mjs";
@@ -25,7 +25,7 @@ import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, record
 import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
-import { fetchRemoteTree } from "./remote.mjs";
+import { contentDigest, fetchRemoteTree } from "./remote.mjs";
 import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -232,6 +232,19 @@ async function fetchSoulSource(prepared, dest) {
   if (!existsSync(join(dest, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(dest, "CLAUDE.md"));
 }
 
+/** The digests a soul copy may carry as its source was fetched (fetchSoulSource): the copy itself, and,
+ *  when it holds the CLAUDE.md → AGENTS.md alias, the copy without it, since fetchSoulSource adds that
+ *  alias to a source that has none. A package soul's copy is intact when one of them is its digest. */
+export function soulCopyDigests(dir) {
+  const options = { allowSymlinks: SOUL_ALIAS_SYMLINK };
+  const alias = join(dir, "CLAUDE.md");
+  let aliased = false;
+  try { aliased = lstatSync(alias).isSymbolicLink() && readlinkSync(alias) === "AGENTS.md"; } catch { aliased = false; }
+  const digests = [contentDigest(dir, options)];
+  if (aliased) digests.push(contentDigest(dir, { ...options, omit: (rel) => rel === "CLAUDE.md" }));
+  return digests;
+}
+
 /** A preview's soul source. A preview writes NOTHING in the deployment (K6b), so it
  *  never populates the per-commit cache or moves the `soul` pointer: it reads the
  *  cache entry for the prepared commit when one is already complete, else fetches

package/lib/remote.mjs

@@ -2139,7 +2139,8 @@ function createDigest() {
 }
 
 /** Same digest as fetchRemoteTree, computed over a local directory. Symlinks and
- * non-regular entries are refused (E_REMOTE_TREE_UNSAFE); a missing dir → E_REMOTE_PATH_MISSING. */
+ * non-regular entries are refused (E_REMOTE_TREE_UNSAFE); a missing dir → E_REMOTE_PATH_MISSING.
+ * `omit(relPath, absPath)` → true leaves an entry out (what a copy gained after its fetch). */
 function posixNormalize(p) {
   const out = [];
   for (const seg of p.split("/")) { if (!seg || seg === ".") continue; if (seg === "..") { if (out.length && out.at(-1) !== "..") out.pop(); else out.push(".."); } else out.push(seg); }
@@ -2155,7 +2156,7 @@ function posixNormalize(p) {
  */
 export const OATS_ALIAS_SYMLINK = (relPath) => typeof relPath === "string" && (relPath === "CLAUDE.md" || relPath.endsWith("/CLAUDE.md"));
 
-export function contentDigest(dir, { allowSymlinks = null } = {}) {
+export function contentDigest(dir, { allowSymlinks = null, omit = null } = {}) {
   if (typeof dir !== "string" || !isAbsolute(dir)) throw fail("E_REPO_REF", "contentDigest requires an absolute directory path", { path: dir });
   let st;
   try { st = lstatSync(dir); } catch { throw fail("E_REMOTE_PATH_MISSING", `${dir} does not exist`, { path: dir }); }
@@ -2165,6 +2166,7 @@ export function contentDigest(dir, { allowSymlinks = null } = {}) {
     for (const name of readdirSync(abs)) {
       if (!rel && name === ".git") continue; // a local checkout's metadata is not content
       const p = join(abs, name), r = rel ? `${rel}/${name}` : name, s = lstatSync(p);
+      if (typeof omit === "function" && omit(r, p)) continue;
       if (s.isSymbolicLink()) {
         // Refused by default (contract §1). The same narrow opt-in fetchRemoteTree
         // honours (a relative, non-escaping alias such as CLAUDE.md → AGENTS.md)

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.21.0",
+      "ref": "v1.21.1",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -28,7 +28,12 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.5.0",
+      "ref": "v1.8.0",
+      "path": "oats-package"
+    },
+    "oats.cloning": {
+      "url": "https://github.com/awebai/oats-cloning.git",
+      "ref": "v1.0.1",
       "path": "oats-package"
     },
     "oats.framework": {
@@ -65,6 +70,7 @@
     "oats.okf-maintenance": "oats.okf",
     "oats.engineering-expert": "oats.engineering",
     "oats.developer": "oats.engineering",
-    "oats.code-review": "oats.engineering"
+    "oats.code-review": "oats.engineering",
+    "oats.maintainer": "oats.engineering"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",