v1.0.0-alpha.2

portable-devshell v1.0.0-alpha.2

This is the second 1.0 prerelease, focused on upgrade safety, Extension-owned persistence and collaboration, and MCP App usability. It is an alpha release for controlled evaluation, not a stable release.

Highlights

1. Host-owned Extension database capability: Extensions use a scoped host-owned SQLite API rather than privately opening their persistent databases. Comment and Agent provider state now use the database capability with lifecycle-aware acquisition, transaction rollback, and sandbox/permission-model tests.
2. Real 0.7.7 upgrade and rollback coverage: the installer snapshots persistent state before replacement. Testspace covers legacy Audit v2-to-v3, Context v1-to-v2, Comment v1-to-v2, and Agent JSON-to-SQLite migration; startup failure, partial migration failure, and unsupported schema paths preserve or restore the prior installation.
3. Agent-work mailing through Comment: Contexts can claim an agent-work identity and exchange queued messages with other agents using the existing Comment and Worker capabilities. Mailing has its own Domain entry and tests with local and Reverse instances, without adding another model-facing MCP tool.
4. MCP App presentation split: an explicit Workspace uses fullscreen mode, while ordinary ToolCalls can show optional compact Inline cards with semantic command, file, and result renderers. The Workspace exposes scoped ToolCall history and paged retained terminal output. Approval/Ask/Wait interactions remain Inline; resource aliases support loading older content-hashed cards.
5. CLI and infrastructure reliability: devshell instance create is supported through the existing CLI/model-command surface instead of a separate MCP tool. ToolCall rewrite keeps host session authority; Web static asset roots and the Core Audit migration scan receive additional path/symlink validation.

Compatibility and operational guidance

• Protocol compatibility is not a replacement guarantee. The installer replaces Control and Worker as an offline unit; its preflight reports Control, Worker, and Frame protocol range mismatches without treating a disconnected prior generation as a live protocol peer. Unsupported persistent schemas and malformed protocol ranges are still rejected.
• Legacy data migration is bounded. Existing 0.7.7-format persistent data is migrated; much older unsupported schemas are not reintroduced. Back up installation and configuration state before upgrading. Failed migration restores the prior version and state, as exercised in Testspace.
• No new MCP provisioning tool. Instance creation remains an existing CLI capability and Mailing reuses Comment. The MCP App's historical resource URI aliases serve the current bundled viewer; this is not an archive of every historical JavaScript/CSS bundle.
• Agent remains separately installed. The Release includes a platform-neutral Agent Extension archive, but not its managed model-provider dependencies.

Verification

• Local source/test TypeScript checks, Domain import rules, ESLint, complete workspace build, package tests and script tests passed on Linux x64. The final package test run exited successfully; the Web suite passed 175/175 in its normal Node 26/JSDOM environment.
• An isolated Linux Testspace used the published v0.7.7 baseline and the alpha.2 candidate. All five upgrade cases passed: successful upgrade, existing Comment target recovery, failed-startup rollback, partial Audit migration rollback across two databases, and unsupported-schema rejection.
• Node 26 still emits an upstream oidc-provider LTS-support warning. Chromium-dependent browser tests on the local test host were skipped because Chromium was unavailable; the GitHub Development CI separately installs Chromium and is required before Release publication.
• Official cross-platform release artifacts, SHA-256 verification, and any release-level CI results are controlled by the GitHub Release workflow; these local checks do not substitute for that workflow.

Refer to docs/development/acceptance.md and docs/development/compatibility.md for the supported test and compatibility contracts.

What's Changed

• fix(mcp): honor forwarded HTTPS on loopback proxies by @Y-M-Zhong in #1
• fix(mcp): recover expired OAuth registration approvals by @Y-M-Zhong in #2
• fix(build): unify Linux workers on cargo zigbuild by @Aromatic05 in #3
• perf: optimize audit storage and Control runtime by @Aromatic05 in #4
• fix: dedupe tmux audit and Workspace wake recovery by @Aromatic05 in #5
• test: repair CI overview fixtures by @Aromatic05 in #6
• fix(workspace): fence PiP remount reconnect loop by @Aromatic05 in #7
• fix(workspace): frame automatic continuation state by @Aromatic05 in #8
• fix(workspace): consume waits completed during agent activity by @Aromatic05 in #9
• fix(workspace): make reentry server authoritative by @Aromatic05 in #10
• fix(installer): fence rollback by runtime generation by @Aromatic05 in #11
• fix(tools): enforce namespace naming contract by @Aromatic05 in #12
• fix(release): close installer and testspace preflight gaps by @Aromatic05 in #13
• fix(release): complete second release audit by @Aromatic05 in #14
• fix(workspace): harden app lifecycle and negotiation by @Aromatic05 in #15
• feat(audit): record MCP tool provenance by @Aromatic05 in #16
• refactor(mcp): move control-plane tools to CLI by @Aromatic05 in #17
• feat(reverse): isolate bulk RPC traffic by @Aromatic05 in #18
• feat(audit): add provenance hot cold lifecycle by @Aromatic05 in #19
• feat(cli): add secret scanning by @Aromatic05 in #20
• feat(cli): add layered skill catalog by @Aromatic05 in #21
• fix(control): bound read workloads by @Aromatic05 in #22

New Contributors

• @Y-M-Zhong made their first contribution in #1
• @Aromatic05 made their first contribution in #3

Full Changelog: https://github.com/Aromatic05/portable-devshell/commits/v1.0.0-alpha.2

v1.0.0-alpha.1

portable-devshell v1.0.0-alpha.1

This is the first 1.0 prerelease, intended for testing the restructured Control, Instance, MCP, and Extension architecture. It is not a stable release or a drop-in, backward-compatible replacement for 0.7.x.

Highlights

1. Explicit lifecycle ownership: Instance owns its Worker supervision, execution, ToolCall ingress and audit lifetime. Control retains its host-level registry and server responsibilities. MCP Server, Protocol Route, OAuth, and MCP App resources have explicit generation, route lease, and teardown boundaries.
2. Domain-based transport and routing: Frame/Envelope/Endpoint communication and domain-specific request, event, and stream surfaces replace retired cross-layer adapters. Clients access the current domain contracts instead of legacy Worker or Control internal APIs.
3. Modern MCP and Web access: the current MCP endpoint and model tool catalog replace retired compatibility paths. Web OAuth2 supports first-party authorization, PKCE, public path prefixes, scoped tokens, and lifecycle-aware listener replacement.
4. Durable Workspace and ToolCall workflows: Comment, Approval, Goal, Todo, task recovery, action receipts, and host reentry follow the current Instance/Extension ownership. ToolCall review and rewrite stages remain explicit, and rejected calls have an audit trail.
5. Real host and release-asset acceptance: Testspace validates local and Reverse Workers, remote attachment, real tools, Web browser, hot replacement, failed-update rollback, and long-running tmux handoff. The release pipeline builds independent application and Worker assets for Linux, macOS, and Windows on x64 and ARM64.

Release-candidate hardening

• TUI startup routing: the route chosen while Control domains initialize now receives its initial load; real Ink Audit/Comment navigation and the Context snapshot contract are covered by platform tests.
• Control cold start and Extension retirement: start readiness accounts for bundled Extension activation; lease-drain tests distinguish candidate validation cleanup from active generation retirement and release held leases before test teardown.
• Agent archive packaging: the platform-neutral portable-devshell-agent.dsext packs from the current Control build output. Linux x64 development CI now exercises this exact archive path ahead of the Release workflow.

Breaking changes and upgrade guidance

• 0.7.x protocol and client compatibility is not promised. Obsolete MCP session, transport, command, and Worker compatibility paths have been removed rather than maintained in parallel. Upgrade the participating components together; do not assume an older Control, Worker, or client can communicate with this alpha.
• Legacy configuration migrations have been retired. The current global configuration schema is version 2 and the current Instance configuration schema is version 4. Do not rely on devshell migrate to convert old global v1 or Instance v2/v3 files. Back up the existing installation and prepare current-schema configuration before using this alpha.
• Do not replace a working production installation during initial evaluation. Use a separate PORTABLE_DEVSHELL_HOME, a separate runtime directory, and loopback-bound private Web/MCP ports until the target environment has passed its own acceptance tests.
• Agent is installed separately. The Core Release carries the platform-neutral portable-devshell-agent.dsext; it does not automatically install Agent or bundle provider runtimes. Install or update the Extension explicitly, and configure the Instance model allowlist as needed.
• Model-side discovery and attachment follow the current contract. The model-facing MCP catalog is fixed; per-Instance model commands are governed by [extensions].model. Reverse Instance discovery and Context attachment use the supported environ_remote command flow. Do not use obsolete instance_connect or legacy MCP group policies.

Verification scope

• Linux x64 prerelease candidate: local lint, typecheck, package and Rust tests, native Worker/installer/Reverse/CLI smokes, and 47 real tmux contract tests passed. A dedicated isolated Testspace passed its 10-command functional matrix and a real 180-second tmux detach boundary.
• Independent physical Linux x64 host: the same verified application archive and statically linked Worker ran on aromatic-server, not the developer machine. Cross-machine MCP v2 tool calls, remote file/terminal/Todo operations, concurrent requests, Chromium WebUI, Instance stop/start, listener hot update, occupied-port rollback, and isolated Control restart were exercised successfully.
• Known constraints: the remote test used loopback-only, no-auth QA listeners. It did not establish remote OAuth2 production-readiness; the server's Node.js 26 runtime also emitted an upstream oidc-provider LTS-support warning. Explicit Instance start was required after the QA Control's deliberate stop/restart.
• Formal release verification: GitHub development CI passed all eight jobs for dev1.0.0-alpha.1-6 at commit cd05884ce2a32f2c2fbd5603197abf2f1117416b (run #38126713049). The official Release workflow (run #38141557504) independently rebuilt and verified the six native targets (linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64, windows-arm64). The published application, Worker, Agent Extension, and installer files carry SHA-256 checksums. Windows target builds do not establish full physical PowerShell/ConPTY interaction coverage.

Refer to docs/development/acceptance.md, docs/development/compatibility.md, docs/operations/configuration.md, and docs/getting-started/installation.md for the current operational contracts and supported release flow.

v0.7.7

portable-devshell v0.7.7

0.7.7 continues the 0.7.x protocol and Extension-boundary freeze while strengthening Agent execution, Windows runtime support, and the operator-facing Web experience. The release freezes semantic Control and Frame protocol negotiation, publishes Agent as an explicitly installed Extension artifact in the Core Release, adds Pi profiles and Subagents, brings persistent pane semantics to Windows, and expands generic Extension-owned control surfaces.

Highlights

1. Control and Frame protocol freeze: Control and Frame now negotiate semantic protocol ranges with the current 1.0.0 contract. The 0.7.6 compatibility paths remain explicit and bounded while devshell update preflights Control, Worker, Frame, Extension, and persistent-state compatibility before activation.
2. Agent profiles and Subagents: the Pi Provider supports Agent Profiles and isolated Subagents, uses the DevShell Agent policy and tool-choice guidance, compacts historical tool output, and defers heavier Agent/tmux tool exposure until the runtime needs it. Pi main-agent startup now follows one runtime path instead of maintaining a separate historical integration, and the managed Pi runtime is updated to 0.99.1.
3. Agent Extension artifact without bundled Provider runtimes: the Core Release ships one platform-neutral portable-devshell-agent.dsext, installed explicitly through the normal Extension lifecycle. Pi and OpenCode runtime dependencies are not release artifacts; they are installed and versioned on the client under their managed Provider prefixes.
4. Extension-owned control surfaces: Extensions can contribute Control routes and generic Web/TUI management pages. Extension runtime state, structured failures, instance lifecycle capability, retirement ownership, and named ToolCall hooks now flow through the public Extension boundaries instead of host-specific adapters.
5. Windows persistent panes and Web polish: the Worker embeds the persistent pane runtime on Windows, normalizes Windows workspace/path semantics, and exercises the long tmux handoff contract on Windows. Web adds conversation row actions and reordering, clearer connection/logout behavior, token visibility control, route-aware titles, reduced-motion handling, and more compact status presentation.

Reliability and validation

• ToolCall review/rewrite hooks are ordered by explicit NNN-name hook names, preserving the review and rewrite stages while giving Extensions a deterministic ordering contract.
• ToolCall rewrite payloads and structured errors stay intact across Extension, MCP, Agent, and sandbox boundaries; Pi surfaces DevShell tool failures without flattening their error metadata.
• File editing normalizes supported compatibility dialects, creates missing target parents where the operation permits it, avoids redundant rereads, and rejects ambiguous Windows-rooted paths instead of guessing their meaning.
• Transport receive credit is restored before window updates, preventing a stalled peer from losing credit during the Frame receive path.
• Windows local activation can roll back safely, OAuth persistence and downgrade output are hardened, and Worker retirement stops the embedded persistent-pane server.
• PORTABLE_DEVSHELL_HOME is now applied consistently to Control and Extension state, so custom DevShell homes also work with explicitly installed Agent state and managed Pi launchers.
• Control rejects unsafe semantic protocol components before business requests, while update preflight reports incompatible protocol ranges and persistent migration rollback blockers before installation is committed.
• Compatibility annotations remain release-gated. The legacy Control integer 1, Worker 7, Frame no-negotiation path, and other declared temporary compatibility debt retain the hard 0.7.10 review/removal deadline.

Upgrade notes

1. Use the normal release installer or devshell update so the application, Worker assets, protocol preflight, and rollback transaction stay aligned.
2. The Core Release includes portable-devshell-agent.dsext, but does not install Agent automatically. Download the artifact from the same release and install or update it with devshell extension install <path> / devshell extension update <path>. Provider runtimes remain client-installed; no .dsprovider artifacts are published.
3. Existing 0.7.6 Control/Worker/Frame peers remain inside their declared compatibility windows, but new integrations should use the semantic protocol ranges rather than the legacy integer/no-negotiation forms.
4. Extension authors targeting the new management and ToolCall surfaces should use Extension API 4.2.0 and Extension schema 1.1.0. ToolCall hooks use deterministic NNN-name ordering.

See docs/development/compatibility.md, docs/concepts/extensions.md, docs/development/acceptance.md, and docs/getting-started/installation.md for the current contracts and release gates.

Full Changelog: v0.7.6...v0.7.7

v0.7.6

portable-devshell v0.7.6

0.7.6 focuses on first-run usability and compatibility lifecycle work while continuing the 0.7.x Core / Extension boundary cleanup. It adds devshell init, explicit update/migration entry points, the Access Extension, OAuth2 approval management, semantic Worker Protocol negotiation, schema-backed Extension configuration, and a release-gated compatibility expiry mechanism.

Highlights

1. First-run initialization: devshell init starts Control, enables MCP for a fresh installation, creates or reuses a local instance, configures OAuth2 approval, starts the instance when enabled, and can hand off directly to Access setup. A newly created local instance uses openai-session Context binding and keeps the Workspace feature switch disabled by default.
2. Access Extension: devshell access provides CLI-first management for Cloudflare Tunnel, SSH reverse access, endpoint status and lifecycle. The bundled Web application is an observation surface in 0.7.6; generic Extension management UI injection is intentionally deferred until the public UI contract is defined.
3. Compatibility lifecycle: devshell migrate provides an explicit persistent-state migration entry point and devshell update [version] reuses the release installer transaction with candidate preflight. Worker Protocol now negotiates semantic protocol versions; Extension API/schema and hostDependencies have independent compatibility versions. Historical compatibility paths are annotated with @compat / @removeAt, checked by CI and the release gate, and all compatibility debt identified in this release has a non-deferrable 0.7.10 deadline.
4. OAuth2 approval management: token and TUI approval modes are available through CLI/TUI/Web connection management, including approval-token rotation without changing instance MCP authentication.

Reliability and validation

• Legacy instance version 2/3 migration preserves the historical implicit contextMode = "explicit" and Workspace-enabled behavior instead of inheriting new fresh defaults.
• Control persistent migration implementations are centralized under packages/control/src/migration/, so old schema support can be audited and retired by its support window instead of remaining mixed into ordinary Store/State paths.
• Access managed cloudflared / frpc downloads use release-pinned assets, SHA-256 verification and versioned caches where managed downloads are supported.
• Access retry backoff is isolated per endpoint, so a fast-recovering endpoint no longer forces unrelated endpoints to retry before their own deadline.
• Worker clients reject malformed or out-of-range negotiated protocol versions while retaining the legacy Worker 7 compatibility adapter. A v0.7.5 numeric-only client continues to receive numeric protocol version 7; semantic-range clients receive the negotiated 1.0.0 protocol version.
• Compatibility expiry is now part of development CI, final acceptance and release validation. The current compatibility debt cannot move its deadline beyond 0.7.10; by that release each path must either be removed or promoted into an intentional stable contract.
• Already-expired v0.7 file/tmux hidden aliases were removed together with their obsolete behavior tests instead of extending their lifetime.
• Config path mutation traverses only own properties, keeping Extension-owned configuration updates fenced from inherited object state even if a future caller bypasses normal path parsing.
• Release installation imports the dedicated Control migration/preflight leaf instead of the full Control barrel. Windows executes that preflight from a temporary .mjs file rather than node -e, passes the candidate module/home through the correct Node script argument positions, and therefore avoids both PowerShell 5.1 native-argument quoting corruption and accidental self-import of the temporary preflight script.
• Control/Frame protocol semantic-version migration remains later 0.7.x freeze work; the compatibility document now distinguishes current 0.7.6 contracts from the target lifecycle.

Upgrade notes

1. Existing global version 1 and instance version 2/3 configuration remains migration input. devshell migrate writes current global version 2 / instance version 4 documents explicitly.
2. Fresh instance defaults are now contextMode = "openai-session" and [workspace].enabled = false. Migrated version 2/3 instances keep the old implicit explicit / Workspace-enabled behavior unless the user changes it later.
3. Use the normal release installer or devshell update so the application, Worker assets and compatibility preflight stay in the same transaction.
4. Access management is intentionally CLI-first in this release. Do not depend on the current Access Web backend as a frozen public Extension management API.

See docs/getting-started/quickstart.md, docs/operations/configuration.md, docs/operations/chatgpt-tunnels.md, and docs/development/compatibility.md for the current contracts.

Full Changelog: v0.7.5...v0.7.6

v0.7.5

Full Changelog: v0.7.4...v0.7.5

v0.7.4

portable-devshell v0.7.4

0.7.4 expands the operator-facing control surfaces and replaces the Worker data plane with the new Transport Frame v1 service architecture. The release also adds machine-readable CLI I/O, improves conversation handling and UI performance, and hardens installation and transport lifecycle edge cases.

Highlights

1. Web control plane: the Web UI can now create instances, perform instance lifecycle operations, edit Control and instance configuration, manage connections, and inspect artifact activity. Destructive operations use explicit confirmations, instance selections are routeable, and conversation visibility preferences are persisted by Control.
2. Structured CLI I/O: devshell --output text|json|jsonl ... provides machine-readable output for automation. Commands that consume JSON can read inline JSON, @file, or stdin via -; streaming commands require jsonl or text output.
3. Transport Frame v1: Worker communication is now byte-oriented and multiplexes typed services over a shared Frame connection. Worker RPC, Reverse RPC, Artifact payload transfer, TCP, and process execution use the common service layer, while Artifact chunk bytes are no longer carried through the RPC data plane.
4. Reverse carrier proxying: Worker enrollment and Reverse transport can use an explicit --proxy, persisted as [reverse].proxyUrl. Anonymous http://, socks5://, and socks5h:// proxy URLs are supported for enrollment, WSS, and SSE/POST carriers.
5. UI and read-model efficiency: Web activity refreshes are scoped, unchanged read-model slices retain identity, TUI render churn is reduced, and Messages navigation is globalized. The redundant TUI Logs page has been removed.

Reliability and validation

• Frame close, late-credit, retired-stream, and bounded-active-stream races are handled explicitly.
• Transport protocol tests now cover typed/routed services and bounded stress acceptance paths.
• The local installer correctly recognizes the current Control daemon identity during replacement.
• Repeated invalid Todo tool use is escalated instead of allowing unbounded retry loops.
• Conversation hidden-state behavior has dedicated persistence and regression coverage.

Upgrade notes

1. Use the normal release installer so the application and Worker assets are upgraded as a matching release set.
2. Existing Reverse connections continue to use their configured carrier unless proxyUrl is set. To route enrollment and Reverse traffic through a proxy, enroll with --proxy <url> or configure [reverse].proxyUrl.
3. CLI automation can opt into --output json for single-result commands or --output jsonl for streaming/multi-record commands. Existing text output remains the default.

See docs/development/transport-protocol.md for the Transport Frame v1 contract and docs/operations/reverse-connections.md for Reverse carrier and proxy behavior.

Full Changelog: v0.7.3...v0.7.4

v0.7.3

Full Changelog: v0.7.2...v0.7.3

v0.7.2

Full Changelog: v0.7.1...v0.7.2

v0.7.1

Full Changelog: v0.7.0...v0.7.1

v0.7.0

portable-devshell v0.7.0

0.7.0 is a major architecture update. Existing v0.6.20 installations can upgrade in place with the normal release installer; running Control and controller-managed instances are restored after replacement.

Upgrade notes

1. Instance configuration is now version 4. Version 2/3 files are migrated automatically. The retired [mcp.tools] group/capability policy is removed during migration.
2. MCP tools/list is a fixed runtime catalog. Instance lifecycle management is no longer exposed as dynamic MCP tools; instance_connect remains the Context attach primitive.
3. Model-facing extensibility now uses the Context-bound devshell available inside bash_run / tmux_run. The bundled default [extensions].model allowlist is artifact, instance, mcp, secret, and skill.
4. Model devshell never falls back to native/builtin commands. Native Control operations such as devshell stop remain unavailable to models unless an explicit model Extension command exists.
5. Artifact management and transfer are provided by the real builtin Artifact Extension. The native devshell artifact ... interface remains available; the old Artifact transfer MCP surface is retired.
6. Instance management remains a native builtin CLI responsibility. The Instance Extension supplies the restricted model-facing inspection/log interface.
7. Extension API v4 adds real sandboxed builtin Extensions, generation-owned capabilities/registrations, public Artifact/Instance capabilities, and invocation-scoped CLI streaming I/O.

If you maintain instance files manually, let 0.7.0 migrate version 2/3 documents once and keep the resulting version 4 structure. Do not reintroduce [mcp.tools]; review [extensions].model instead when controlling model-accessible Extension commands.

See docs/operations/configuration.md, docs/concepts/mcp.md, and docs/concepts/extensions.md for the current contracts.

Full Changelog: v0.6.20...v0.7.0