OAS v0.19.0

OAS v0.19.0

One release built from one tag: @oas-framework/oas@0.19.0,
@oas-framework/pi@0.19.0, and OAS Desktop 0.19.0 in this GitHub Release.

This release introduces distribution packages, exact OAS-managed instance
curricula, canonical primary-checkout instance homes, and the package/profile
setup flow needed for independently published official capabilities.

Distribution packages

An OAS package is now the acquisition, integrity, update, and review unit above
independently targetable capabilities. A Git repository may contain ordinary
development content and one or more package payloads; the selected payload path
is part of the source and lock contract.

# Git/catalog sources default to the contained oas-package/ directory.
oas install https://github.com/example/project.git@v1.0.0

# Select another contained directory, or the repository root explicitly.
oas install 'https://github.com/example/project.git@v1.0.0#dist/oas'
oas install 'https://github.com/example/root-package.git@v1.0.0#.'

# A local path always names the exact package root.
oas install ../project/oas-package

Lock v2 records source, exact commit, selected path, integrity, dependency
closure, exported capabilities, and per-capability executable approvals. Bare
oas install restores the exact locked graph; it never advances a branch,
catalog selector, package path, or dependency closure. Updating remains
explicit:

oas update <package-id>

Acquisition installs and hashes only the selected payload subtree. Repository
CI, documentation, owner souls, sibling packages, and source-control metadata
are not installed. If root .git metadata later appears inside a managed
artifact, it is treated as source drift and invalidates trust rather than being
an approval-invisible exclusion.

Package config profiles and workspace setup

Packages may ship complete reference oas-config.yaml profiles. Adoption is
explicit and produces an editable local snapshot:

oas init --package <package-source> [--config <profile>] --dir <workspace>
oas install --dir <workspace>

The first command acquires and exact-locks the full package closure, validates
the selected profile against its capability providers, and writes the snapshot.
The second command reconciles the team boundary and nested repository locks.
Package updates never rewrite an adopted config; normal targeting, exclusions,
settings, and closer repository overrides remain authoritative.

Missing host commands and runtime packages remain a separate consent decision.
Human and JSON plans show every ordered argv step before anything executes.
Spawn verifies required runtime packages but never installs them.

Exact OAS-managed instance curriculum

For each soul, the scoped config cascade now determines the complete
OAS-managed skill and instruction set. Active capability resources are
enumerated before scaffolding, copied into the canonical instance tree, and
asserted against the expected composition. Missing, untrusted, duplicate, or
uncontained active resources fail closed instead of producing a half-configured
agent.

Canonical instance resources are:

<instance-home>/.agents/skills/
<instance-home>/.claude/skills -> ../.agents/skills
<instance-home>/AGENTS.md
<instance-home>/CLAUDE.md -> AGENTS.md

Runtime posture is deliberately provider-specific and recorded in
instance.json:

• Pi suppresses ambient skills, context files, and prompt templates while
  preserving operator-configured extensions.
• Claude Code preserves the operator's native user/repository settings,
  skills, plugins, MCP, hooks, and memory; OAS adds its canonical composed
  resources without exclusion flags.

The guarantee is exact OAS-managed composition, not identical ambient behavior
across providers.

Canonical instance homes and the home/work boundary

Instance homes now live under the soul-owning repository's primary checkout,
even when spawn is invoked from a linked worktree or from an agent's work/.
Unresolvable placement fails closed before creating anything.

Every runtime and lifecycle hook receives the absolute OAS_INSTANCE_HOME.
Generated instructions distinguish the two operational surfaces:

• instance home contains instructions, task, soul reference, provenance,
  selected skills, and episodic state; OAS lifecycle and active-capability
  commands run there;
• <instance-home>/work is the repository or workspace view where permitted
  reading, editing, Git, builds, tests, and commits happen.

OAS performs resolved-path containment checks and rechecks the created home
before writing credentials or running hooks. The deployment agents directory
must still be operator-owned and not writable by untrusted local processes.

Required hooks, runtime requirements, and safe rollback

Capability spawn hooks may declare required: true. A required hook that cannot
establish its contract fails the spawn. If compensation cannot finish, OAS
retains a versioned quarantine containing the credential and original cleanup
metadata; oas retire retries and verifies outstanding cleanup before deleting
the home. --force remains the explicit operator escape hatch.

Requirement consent now supports runtime-scoped Pi packages and Claude plugins,
including multi-step marketplace registration plans. JSON and human output show
the same exact ordered steps.

Existing 0.18 capability installations

Upgrading the kernel does not force a capability migration. Existing valid
v1 locks, installed official capability artifacts, config activation, and trust
continue to work in 0.19.0.

The guided command is included:

oas migrate --official --recursive --dry-run --dir <team-root>
oas migrate --official --recursive --dir <team-root>

It remains held until the official package catalog and immutable package tags
are published. That catalog/default redirect ships in the planned 0.19.1
follow-up. Until then, oas doctor explains that the legacy capabilities remain
supported. Migration preserves config files and capability IDs, leaves custom,
owned, and path capabilities untouched, and never transfers executable trust
silently.

Legacy kernel-marketplace capabilities may still reference framework-hoisted
resources. Those paths now anchor at the declaring capability's canonical
marketplace directory and remain contained by the installed kernel. Valid older
installed+locked capabilities continue working across a kernel upgrade.

OAS Desktop

Desktop accepts the matching 0.19 CLI through Desktop CLI API v1
(>=0.18.0 <0.20.0) instead of rejecting its own release and degrading to
observation-only mode. Compatibility and recovery copy are derived from one
runtime contract rather than repeated literals.

Desktop also includes the accumulated 0.18.x post-release work: cluster-aware
agent navigation, persistent editor-style terminal groups, Quick Open for souls,
runtime-scoped model suggestions, improved spawn readiness handoff, and the
existing editable shortcut system.

Downloads

Platform	Artifacts
macOS arm64 (Apple Silicon)	DMG + ZIP
macOS x64 (Intel)	DMG + ZIP
Linux x64	AppImage + DEB

macOS artifacts are ad-hoc signed, not Developer ID signed or notarized. First
launch may require right-click → Open, or Open Anyway in System Settings.
Verify assets with SHA256SUMS.txt and the GitHub build-provenance attestations.
Windows and Linux arm64 are not supported in this release.

Install or update

npm install -g @oas-framework/oas@0.19.0
pi install npm:@oas-framework/pi@0.19.0

The kernel, Pi adapter, and Desktop publish from the same tag and should stay on
matching versions. Official OAS capability packages are published separately
after released-kernel consumer probes; this release does not claim that their
catalog entries are live yet.