Skip to content

Releases

Worktree Control 0.2.0

Worktree Control 0.2.0 Latest
Latest

Choose a tag to compare

View all tags
@pioootrek pioootrek released this 09 Nov 18:21
v0.2.0
97d0a68
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Worktree Control 0.2.0

2026-11-09

Optional individual accounts with per-project permissions, scoped agent
credentials, an external security fence, Godot verification and Web previews,
verification history, and recorded current state for Knowledge tasks.

The Community package works independently in token and open modes. Account
mode is optional and requires a separate provider, explicit CLI selection and
restart, owner enrollment, and a canonical HTTPS public URL. It never falls
back to token or open access. Both artifacts are MIT licensed, with bundled
third-party notices. Linux x64 is verified; macOS and Windows are unverified.

Install

Confirm availability in the npm version listing:

npm view worktree-control@0.2.0 version
npm install --global worktree-control@0.2.0

Node.js 22 or newer and Git are required. For a new installation, follow the
installation guide.
Existing installations must complete the upgrade below before starting.

Upgrade from 0.1.1

The database moves from schema 28 to schema 49. Stop the sole controller before
the backup, installation and fence steps. Stopping it also ends MCP sessions
and stops the development servers it manages.

  1. While 0.1.1 is still installed, stop the service and make an application
    backup under a new private nested parent outside Git working trees:

    worktree-control service stop
worktree-control service status
umask 077
worktree-control backup create "$HOME/worktree-control-backups/0.1.1-before-0.2.0"

    Confirm the service is stopped. For a foreground controller, stop it with
    Ctrl-C instead. The backup parent must be mode 0700 or absent so the
    command creates it privately. Do not use a plain pre-upgrade data-directory
    copy as the recovery procedure.

  2. Install worktree-control@0.2.0 into the same prefix. Keep the controller
    stopped, run worktree-control auth fence inspect, and continue only if it
    reports schema 28, security_fence_establishment_required and
    establishmentAllowed: true for a store that has never been upgraded.

  3. Run worktree-control auth fence establish --expect <preflight-from-inspect>.
    This applies migrations 29–49 and creates the external security witness.
    Confirm security_fence_current, then check and start the service:

    worktree-control auth status
worktree-control service start
worktree-control service status

    Reconnect clients. The existing mode, installation token,
    owner and agent principals, agent tokens, Knowledge grants and history are
    preserved. Existing agent tokens gain no new permissions.

Use the same data/state directories for every command. The
complete upgrade guide
includes custom paths, prefixes and refusal handling.

There is no supported downgrade; never run 0.1.1 on the migrated database.
To restore the pre-upgrade application backup, keep the controller stopped
and use the 0.2.0 executable:

worktree-control backup restore "$HOME/worktree-control-backups/0.1.1-before-0.2.0"
worktree-control auth fence inspect
worktree-control auth fence resume --expect <new-preflight> --mode token
worktree-control auth token generate

Resume is an explicit recovery decision after inspection. Protected resume
preserves snapshot data but quarantines restored credentials, sessions and
grants, including the installation token. Generate a new installation token
and explicitly reissue agent credentials and grants before restarting. Writes
made after the backup are lost. Installed acceptance covers this restore in
both existing and empty directories. Never remove, replace or copy the
witness to bypass quarantine, or replace the data directory with an older
plain copy. See
recovery.

Optional account provider

The separate GitHub Release asset is
worktree-control-auth-provider-better-auth-proof-0.0.0.tgz. Its historical
package name is @worktree-control/auth-provider-better-auth-proof, package
version 0.0.0, implementation 0.0.0-proof.5, provider contract 5, storage
revision 3. The package remains private: true, is never published to npm
and is never a Community dependency. Identify this release by
compatibleCore.version: 0.2.0, the source commit and the tarball SHA-256 in
worktree-control-provider-provenance.json.

Download all provider companions, including the checksum manifest, provenance,
license, notices, dependency lock and worktree-control-provider-INSTALL.md.
Verify the provenance against the release evidence below, then install into a
new private directory:

sha256sum --check worktree-control-provider-SHA256SUMS
umask 077
PROVIDER_DIR="$HOME/.local/lib/worktree-control-provider-0.2.0"
mkdir -p "$(dirname "$PROVIDER_DIR")"
mkdir "$PROVIDER_DIR"
tar -xzf worktree-control-auth-provider-better-auth-proof-0.0.0.tgz \
  -C "$PROVIDER_DIR" --strip-components=1 --no-same-owner
npm ci --prefix "$PROVIDER_DIR" --omit=dev --ignore-scripts

Use $PROVIDER_DIR/dist/index.js for provider configuration. npm install <tarball> does not preserve the shipped transitive lock. Continue with
account-mode setup
and the provider installation guide.

Verification boundary

Installed acceptance of the integrated route passed for both the public npm
0.1.1 upgrade/recovery baseline and a fresh installation. The separate
production-composition tests passed. Final artifact evidence is identified
below; it must come from the same successful CI run and attempt on the final
merged release commit.

The full provider proof suite is not green. The 2026-11-08 run on
370bac2ea2bcbda98025c76b8e809484293a5140 ended with 1,107 passes, five
historical native/older bounded factor-compatibility failures, zero skips,
and exit 1. Those fixtures are not shipped; the integrated route uses separate
durable replay and guessing-budget controls. The full proof result is distinct
from installed acceptance and production composition. No hardware passkey or
manual visual QA was performed. See
verification status and known limitations
and the changelog.

Release evidence

Evidence Value
Final merged source commit for tag v0.2.0 97d0a68d477db7c36922ea8cb4e4101841e42f21
Successful Verify run URL https://github.com/pioootrek/worktree-control/actions/runs/42664872756
CI run ID / attempt 42664872756 / 1
Exact-artifact public-0.1.1 / fresh acceptance job https://github.com/pioootrek/worktree-control/actions/runs/42664872756/job/129340767952
Community tarball SHA-256 d48e297a26174ca350a9e8ac1171f36dbc0420fa19d59dcffef6ac18af06e6d5
Provider compatibleCore.version 0.2.0
Provider source commit 97d0a68d477db7c36922ea8cb4e4101841e42f21 (must equal final merged commit)
Provider tarball SHA-256 a8262b7b2dabef296b0171ac4e748ddcbf6c886615974e68b4b300d68e6139cc
Provider shipped dependency-lock SHA-256 ca0512dda6d791ee7ab44f49f9eb1c703fc945bfa5923345c187573809df5394

Both portable-package and optional-auth-provider must have clean provenance
for that commit, CI run and attempt. Verify SHA256SUMS and
worktree-control-provider-SHA256SUMS before use. Release artifacts come from
CI; a local rebuild or an earlier commit does not establish these bytes.

Assets 16