@desplega.ai/agent-env 0.0.0-stage → 0.3.0

package/docs/agent-swarm.md

@@ -0,0 +1,146 @@
+# Agent Swarm with agent-env
+
+Run the real API and dashboard from an Agent Swarm checkout.
+Copy two configuration files, provide a private test credential, and run `agent-env up`.
+The Compose setup job installs Linux dependencies before the API and dashboard start.
+
+## Requirements
+
+- Node.js 22 or newer on the host.
+- Docker Engine and Docker Compose with JSON configuration, `config --variables`, and `up --wait`.
+- An Agent Swarm checkout with `bun@1.4.4` in `package.json`.
+- Docker Hub and package registry access for the first installation.
+- Free host ports 4313 and 4574, and approximately 7 GiB for the first installation.
+
+The host needs no Bun or portless installation.
+The example uses `oven/bun:1.4.4` without building application images.
+
+## Start from an Agent Swarm checkout
+
+Run these commands from the checkout.
+Set `AGENT_ENV_REPO` to your agent-env checkout.
+For a global npm installation, use `export AGENT_ENV_REPO="$(npm root -g)/@desplega.ai/agent-env"` instead.
+Do not replace existing configuration files.
+If either destination exists, select another filename and pass `--config` or `--compose-file` explicitly.
+
+```sh
+export AGENT_ENV_REPO=/path/to/agent-env
+cp "$AGENT_ENV_REPO/examples/agent-swarm/agent-env.json" ./agent-env.json
+cp "$AGENT_ENV_REPO/examples/agent-swarm/compose.agent-env.yaml" ./compose.agent-env.yaml
+
+umask 077
+export AGENT_ENV_HOME="$(mktemp -d /tmp/agent-env-swarm-XXXXXX)"
+export AGENT_SWARM_INSTANCE=swarm-example
+node --input-type=module <<'JS'
+import { writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+writeFileSync(`${process.env.AGENT_ENV_HOME}/test.env`,
+  `AGENT_SWARM_API_KEY=${randomBytes(32).toString('hex')}\n` +
+  `AGENT_SWARM_INSTANCE=${process.env.AGENT_SWARM_INSTANCE}\n`, { mode: 0o600 });
+JS
+
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" up --name "$AGENT_SWARM_INSTANCE" \
+  --env-file "$AGENT_ENV_HOME/test.env"
+```
+
+The installed CLI also accepts `agent-env up` in place of the Node invocation.
+`startupTimeoutSeconds: 900` allows the setup job to finish its first installation.
+`--timeout 900` provides the equivalent CLI override.
+
+The source bind points directly at the current checkout.
+The dashboard sees source edits through Vite.
+Restart the API with `down` and `up` after API source edits.
+Docker stores Linux dependencies and Bun downloads in separate named volumes for each instance.
+The setup job uses the checkout's frozen lockfile and hoisted linker configuration.
+It skips lifecycle scripts.
+
+## Verify the real application
+
+Keep the same `AGENT_ENV_HOME` in this shell.
+
+```sh
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" use "$AGENT_SWARM_INSTANCE"
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" list
+node --env-file="$AGENT_ENV_HOME/test.env" \
+  "$AGENT_ENV_REPO/examples/agent-swarm/verify.mjs"
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" logs "$AGENT_SWARM_INSTANCE" --service api
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" logs "$AGENT_SWARM_INSTANCE" --service setup
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" exec "$AGENT_SWARM_INSTANCE" --service api -- \
+  bun --no-env-file -e "fetch('http://127.0.0.1:3013/health').then(r => r.json()).then(console.log)"
+
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" down "$AGENT_SWARM_INSTANCE"
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" up "$AGENT_SWARM_INSTANCE"
+node --env-file="$AGENT_ENV_HOME/test.env" \
+  "$AGENT_ENV_REPO/examples/agent-swarm/verify.mjs" --read-only
+```
+
+The first check writes a value through `PUT /api/kv/_/agent-env-example/persistence`.
+It reads the value through the direct API and the dashboard proxy.
+The second check only reads the retained value after restart.
+Both checks verify authentication, health, dashboard HTML, and the transformed dashboard entry module.
+The check uses HTTP and does not prove browser rendering or interaction.
+
+| Service | Default address |
+| --- | --- |
+| API | `http://swarm-example.localhost:4313` |
+| Dashboard | `http://swarm-example.localhost:4574` |
+| Selected API | `http://localhost:4313` |
+| Selected dashboard | `http://localhost:4574` |
+
+Enter the API address and generated test key in the dashboard's connection form.
+The key remains in the private environment file until you use it.
+The example does not embed the key in browser assets.
+If `.localhost` resolution fails, use `localhost` after `agent-env use`.
+For curl, use `--resolve swarm-example.localhost:4313:127.0.0.1`.
+
+## Configuration and isolation
+
+| Setting | Purpose |
+| --- | --- |
+| `AGENT_SWARM_API_KEY` | Required test credential, generated outside the checkout. |
+| `AGENT_SWARM_INSTANCE` | CORS instance name. Must match `--name`. Default: `swarm-example`. |
+| `AGENT_ENV_HOME` | Separate daemon, private configuration, and saved instance state. |
+| `DATABASE_PATH=/data/agent-swarm.sqlite` | SQLite data in the instance's named volume. |
+| `AGENT_FS_LOCAL_DIR=/data/files` | Local storage in the same isolated data volume. |
+| `CAPABILITIES=core,task,kv,skills,repo` | Excludes the scheduler capability. |
+
+No inference, Slack, tracker, GitHub, or agent-fs credentials are required.
+The API receives only explicit Compose environment values.
+All Bun commands use `--no-env-file`.
+The dashboard starts the checkout's actual Vite configuration with `envDir: false`.
+These settings prevent Bun and Vite from loading existing private `.env` files.
+The explicit `--env-file` selects the generated credential for Compose interpolation.
+
+The file disables heartbeat, runtime pools, automatic titles, integrations, OAuth sweeps, and telemetry.
+It starts no lead or worker containers and does not execute schedules or create tasks.
+Normal API startup seeds schedule definitions, including some marked enabled.
+The scheduler remains disabled because the example excludes the `scheduling` capability.
+The API still runs its normal internal maintenance services.
+Its automatic public model-catalog refresh can contact `models.dev`.
+The Compose network permits outbound traffic, so this example is not an internet sandbox.
+Docker omitted published ports on an internal-only network during verification.
+
+Agent-env isolates container names, the network, all dependency volumes, and the data volume.
+It publishes Docker backend ports only on random loopback ports.
+The configured localhost routes use ports 4313 and 4574.
+The data volume retains SQLite, encryption material, and the page-session secret after `down` and `up`.
+The API mounts source read-only.
+Setup and Vite use a writable source bind, with dependency directories covered by Linux volumes.
+Docker can create empty `node_modules` mountpoint directories in a fresh checkout.
+The setup job does not change the frozen lockfile or package manifests.
+
+## Cleanup
+
+```sh
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" rm "$AGENT_SWARM_INSTANCE" --purge
+node "$AGENT_ENV_REPO/bin/agent-env.mjs" daemon stop
+rm -r "$AGENT_ENV_HOME"
+# Remove only the two configuration files copied for this run.
+rm ./agent-env.json ./compose.agent-env.yaml
+df -h /
+```
+
+Purge removes the instance's containers, network, dependency caches, and data volume.
+The cleanup does not remove shared caches or other Docker resources.
+No custom images need removal.
+If this test alone downloaded the Bun image, remove it with `docker image rm oven/bun:1.4.4`.

package/docs/releases.md

@@ -0,0 +1,207 @@
+# CI and releases
+
+The repository is `desplega-ai/agent-env`. Its default branch is `master`.
+The npm package is `@desplega.ai/agent-env`.
+
+## Ordinary CI
+
+`.github/workflows/ci.yml` runs for every pull request and every push to `master`.
+Public forks need no secrets. Ordinary CI never creates paid cloud resources.
+CI uses public CLI E2E tests. It does not run unit tests.
+
+The package job creates one tarball with `npm pack --ignore-scripts`.
+`scripts/pack.mjs` audits its file list, package identity, version, and executable entry.
+The audit rejects files outside the published directories, credential filenames, and unexpected artifacts.
+Every test job downloads that same tarball and installs it into a temporary prefix.
+No job installs the package globally.
+
+The `CI` job requires all these jobs to succeed:
+
+| Job | Runtime | Real dependencies |
+| --- | --- | --- |
+| Core | Linux and macOS, Node 22 and latest LTS | Git, public CLI |
+| Docker | Linux, latest Node LTS | Docker, HTTP, TCP, TLS, sandbox bridge |
+| Compose | Linux, latest Node LTS | Docker Compose |
+| SSH | Linux, latest Node LTS | Dedicated localhost sshd, Docker, Compose, rsync |
+| S3 | Linux, latest Node LTS | Docker Compose, AWS CLI, disposable SeaweedFS |
+
+The SSH fixture generates new client and host keys for every job.
+The client pins the generated host key and requires strict host verification.
+The fixture starts its own sshd with password authentication disabled.
+PAM handles account checks, which permits key authentication for the runner's password-locked account.
+Its command wrapper isolates the remote workspace.
+The SSH process keeps the real CI user's home.
+It does not change the system SSH configuration or authorized keys.
+
+SeaweedFS uses version `4.52` and a pinned image digest.
+Its S3 port binds only to localhost.
+Each job generates credentials and creates a disposable bucket.
+The tests remove their snapshot prefixes. Cleanup removes the container and its storage.
+
+## Runner contract
+
+The test owner maintains `test/run.mjs` and its suites.
+`npm test` runs core, Docker, and Compose E2E.
+`npm run test:core` runs the subset that requires no Docker.
+CI calls the following commands through `scripts/ci-e2e.sh`:
+
+```sh
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs core
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs docker
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs compose
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs ssh
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs s3
+AGENT_ENV_CLI=/absolute/prefix/node_modules/.bin/agent-env node test/run.mjs cloud
+```
+
+All CLI invocations must use `AGENT_ENV_CLI` when CI supplies it.
+Tests must not import implementation modules or substitute Docker or SSH mocks.
+Tests must create their directories beneath `TMPDIR` and remove their own resources.
+The cloud suite must preserve state if resource cleanup fails.
+
+The wrapper supplies these variables:
+
+| Suite | Variables |
+| --- | --- |
+| All | `AGENT_ENV_CLI`, `AGENT_ENV_HOME`, `TMPDIR`, isolated npm and XDG directories |
+| Docker | `AGENT_ENV_TEST_SANDBOX=1` |
+| SSH | `AGENT_ENV_TEST_SSH=agent-env-ci`, `AGENT_ENV_TEST_SSH_CONFIG` |
+| S3 | `AGENT_ENV_TEST_S3=s3://agent-env-ci/snapshots`, `AGENT_ENV_TEST_S3_ENDPOINT`, temporary AWS credentials |
+| Cloud | `AGENT_ENV_TEST_CLOUD=1`, `HCLOUD_TOKEN` from the protected environment |
+
+The wrapper removes unrelated SSH and S3 settings from the inherited environment.
+Each suite must remove instances, stop daemons, and remove its temporary files.
+The wrapper also attempts cleanup after failure or termination.
+An `always()` workflow step provides another cleanup attempt.
+Cleanup retains recovery files when resource removal fails.
+Cleanup requires the test directory's ownership marker and checks recorded fixture ownership.
+It refuses resources with a different owner and reports failure.
+
+## Automatic release
+
+Merge an increasing version change in `package.json` to `master`.
+The workflow compares the version against `github.event.before`, covering the entire push.
+It does not compare only the final commit's parent.
+Pull request CI also checks version increases against `pull_request.base.sha`.
+A downgrade fails before merge.
+
+The release job requires successful CI from the same workflow and exact commit.
+It publishes the same archive that every E2E job tested.
+It checks these conditions before publishing:
+
+1. The package version contains valid SemVer and increases from the version before the push.
+2. The archive name and version match `package.json` exactly.
+3. A new version exceeds every version already published to npm.
+4. Any existing version contains the exact same archive integrity.
+5. Any existing Git tag points to the tested commit.
+6. Any existing GitHub asset contains the exact same bytes.
+
+npm releases cannot include SemVer build metadata because npm does not preserve it.
+
+After npm confirms the exact version and integrity, the job creates `v<VERSION>` and the GitHub release.
+The version check bypasses registry caches and retries propagation for up to twelve attempts, ten seconds apart.
+If publication fails after npm accepted the archive, the retry verifies its integrity before continuing.
+The GitHub release attaches only the tested `.tgz` file.
+Prereleases use npm's `next` tag and GitHub's prerelease flag.
+Stable releases use npm's `latest` tag.
+Retries preserve existing tags and assets. They never overwrite conflicting releases.
+An already published version must match the archive before the workflow resumes.
+Registry failures stop the release instead of treating the version as absent.
+
+Concurrency queues master runs so a later push cannot discard an earlier version bump.
+GitHub permits up to 100 queued runs per group.
+GitHub documents `queue: max` in its [concurrency reference](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency).
+Actionlint 1.7.12 does not recognize this field yet.
+Run its other checks with `actionlint -ignore 'unexpected key "queue" for "concurrency" section'` until actionlint supports it.
+
+## One-time npm setup
+
+The repository already has access to the organization secret `NPM_TOKEN`.
+No local npm authentication or publication forms part of CI implementation.
+
+OIDC is the default publishing method.
+The release job grants `id-token: write` and requires npm 11.5.1 or later.
+Use npm's [trusted publishing instructions](https://docs.npmjs.com/trusted-publishers/) to configure:
+
+| Setting | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization | `desplega-ai` |
+| Repository | `agent-env` |
+| Workflow filename | `ci.yml` |
+| Environment | Leave empty |
+| Allowed action | Publish |
+
+The initial package may need token authentication before npm exposes its publisher settings.
+To publish an initial version without another version bump, dispatch `CI and release` on `master` with both inputs enabled:
+
+```sh
+gh workflow run ci.yml --repo desplega-ai/agent-env --ref master \
+  -f release=true -f use_npm_token=true
+```
+
+This dispatch still runs every ordinary CI job before it publishes.
+It passes `secrets.NPM_TOKEN` as `NODE_AUTH_TOKEN` only to the release step.
+The release script uses that token only when token publishing is explicitly selected.
+After bootstrap, configure the trusted publisher and dispatch with `use_npm_token` disabled to test OIDC.
+For manual dispatch, this input overrides the repository variable, including an explicit disabled value.
+Remove the token fallback when npm OIDC succeeds.
+If token publishing remains necessary, repository variable `NPM_USE_TOKEN=true` enables it for automatic bumps.
+This repository currently sets that variable for its initial token-based publication.
+The token must permit public publishing under `@desplega.ai`.
+
+To test a version bump before merging:
+
+```sh
+npm version patch --no-git-tag-version
+# Or: npm version minor --no-git-tag-version
+# Or: npm version 0.3.0 --no-git-tag-version
+npm run check
+npm test
+git diff -- package.json
+```
+
+Commit the version change through the normal pull request process.
+Do not create or push a version tag manually.
+The workflow creates the tag after tests and npm verification succeed.
+For a retry without another bump, dispatch `ci.yml` with `release=true` on the same commit.
+Use GitHub's rerun action when `master` has advanced beyond that commit.
+
+## Manual Hetzner E2E
+
+`.github/workflows/hetzner-e2e.yml` runs only through manual dispatch on `master`.
+It creates billed infrastructure only after approval for environment `hetzner-e2e`.
+An administrator must create that protected environment before use.
+Configure required reviewers, prevent approval by the requester, and restrict deployments to `master`.
+Store `HCLOUD_TOKEN` as an environment secret with access to a dedicated test project.
+This implementation does not change GitHub settings.
+
+The job installs a pinned Hetzner CLI archive and checks its SHA-256 digest.
+It tests an audited package through its installed executable with `AGENT_ENV_TEST_CLOUD=1`.
+The suite must remove its server, primary IP, SSH key, volumes, and local state.
+The wrapper and `always()` step attempt recovery with the recorded CLI state.
+Inspect the dedicated Hetzner project after a runner loss or forced cancellation.
+An unavailable runner cannot execute cleanup.
+
+```sh
+gh workflow run hetzner-e2e.yml --repo desplega-ai/agent-env --ref master
+```
+
+## Local package verification
+
+Docker and Compose must work for integration groups.
+The SSH fixture requires Linux, OpenSSH server, rsync, and passwordless sudo.
+The S3 fixture requires AWS CLI v2.
+
+```sh
+work=$(mktemp -d /tmp/agent-env-package-check-XXXXXX)
+node scripts/pack.mjs "$work"
+tarball=$(find "$work" -name '*.tgz' -type f)
+bash scripts/ci-e2e.sh "$tarball" core
+# Run these integration groups on Linux with Docker available:
+bash scripts/ci-e2e.sh "$tarball" docker
+bash scripts/ci-e2e.sh "$tarball" compose
+bash scripts/ci-e2e.sh "$tarball" ssh
+bash scripts/ci-e2e.sh "$tarball" s3
+rm -r "$work"
+```

package/docs/snapshots-and-worktrees.md

@@ -0,0 +1,221 @@
+# Snapshot and Git worktree helpers
+
+These modules provide storage and source helpers for the parent lifecycle code.
+The daemon integrates them with snapshot, restore, and fork commands.
+S3 stores backup archives. It does not store live database files.
+
+## Snapshot API
+
+```js
+import { snapshotInstance, restoreSnapshot } from '../src/snapshots.mjs';
+
+const exported = await snapshotInstance(handle, location, provider, options);
+// { location, manifest }
+
+const restored = await restoreSnapshot(destinationSpec, location, provider, options);
+// { location, manifest, volumes, volumeNames }
+```
+
+`location` is a new local directory or `s3://bucket/nonempty-prefix`.
+The local parent directory must exist.
+An existing local directory or nonempty S3 prefix causes export to fail.
+Restore refuses every existing destination volume, including empty volumes.
+
+The provider must implement `docker(spec, argv, options)` with the Docker provider's command contract.
+It must forward `options.stdio` to the child process for archive commands.
+The helper redirects archive bytes through file descriptors.
+It never converts archive bytes to strings.
+The provider handles local execution, SSH arguments, and command quoting.
+
+Each entry in `handle.services` must identify `container` or a `containers` array of container names or IDs.
+The helper inspects those containers to discover actual volume names and mount targets.
+It does not reconstruct source names from provider naming conventions.
+This supports ordinary Docker handles and Compose handles with multiple containers per service.
+
+All source containers must be stopped or newly created.
+The helper checks their state before and after export.
+Callers must serialize lifecycle operations for the full export or restore operation.
+External Docker operations must also leave these containers and volumes unchanged.
+The helper cannot prevent another Docker client from starting a container during an archive operation.
+
+**Cloud integration:** the parent must wake the host without starting its containers.
+Do not call a cloud resume operation that also starts services before snapshot export.
+Pass the reachable Docker host through the provider's existing command helpers.
+The helpers do not provision, wake, or shut down cloud hosts.
+
+The helper accepts these options:
+
+| Option | Operation | Meaning |
+| --- | --- | --- |
+| `image` | Both | Archive helper image. Default: `busybox:1.37`. |
+| `endpointUrl` | S3 operations | AWS CLI endpoint URL for compatible services. |
+| `awsCommand` | S3 operations | AWS executable path. Default: installed `aws`. |
+| `omitUnsupportedMounts` | Export | Explicitly omit unsupported or shared mounts. Default: reject them. |
+| `volumeNames` | Restore | Map manifest volume IDs, such as `v0`, to fresh Docker volume names. |
+| `destinationHandle` | Restore | Identify existing destination service containers for a stopped-state check. |
+| `composeProject` | Restore | Identify an existing destination Compose project for a stopped-state check. |
+
+The Docker naming fallback checks existing destination containers through `provider.prefix(spec)` when available.
+Compose callers must supply `composeProject` or `destinationHandle` when destination containers already exist.
+Restore returns a unique `restoreId` for safe failure cleanup through `disposeRestoredVolumes`.
+Restore creates volumes only. It does not create containers, copy source files, or start services.
+The parent must attach the returned volumes before service creation.
+
+Without `volumeNames`, restore matches each saved service and mount target against `destinationSpec.services[service].volumes`.
+It calls `provider.volume(spec, service, key)` to obtain the destination name.
+Every saved mount of one source volume must resolve to the same destination name.
+The Compose provider resolves destination volume names and labels through its snapshot hooks.
+The parent must also preserve shared mounts within the same instance through that map.
+
+```js
+const saved = await snapshotInstance(stoppedHandle, '/backups/checkpoint-1', docker);
+const destinationSpec = { ...stoppedHandle.spec, name: 'feature-copy' };
+const restored = await restoreSnapshot(destinationSpec, '/backups/checkpoint-1', docker);
+
+const composed = await restoreSnapshot(destinationSpec, '/backups/checkpoint-1', compose, {
+  composeProject: 'feature-copy',
+  volumeNames: { v0: 'feature-copy_database' },
+});
+```
+
+## Ownership and archive rules
+
+Managed volumes need a matching `agent-env.owner` label or the container's matching `com.docker.compose.project` label.
+Only local Docker volumes without driver options qualify for automated export.
+Volumes attached to any container outside the handle are shared, even when that container is stopped.
+The helper rejects those volumes.
+Providers must not assign managed ownership labels to external volumes.
+
+Bind mounts inside `handle.workspace` or `spec.cwd` are omitted as source files.
+Source files need a separate Git fork or synchronization operation.
+Other bind mounts, tmpfs mounts, external volumes, and shared volumes require separate backup procedures.
+`omitUnsupportedMounts: true` records each omission with its service, target, type, and reason.
+The parent must display these omissions to the caller.
+
+`manifest.json` has format `agent-env-snapshot`, version `1`.
+Each volume record includes its ID, actual source name, service mounts, archive name, SHA-256, and archive byte count.
+One source volume produces one archive, even when several source services mount it.
+The manifest includes only source name, owner, and provider identifiers.
+It does not serialize the specification, container inspection, environment values, or image commands.
+Volume contents can contain application secrets. The manifest exclusion does not redact those files.
+
+Archives use uncompressed tar files.
+Validation streams file bodies and checks tar headers before extraction.
+It supports regular files, directories, internal symbolic links, hard links to earlier files, and GNU long paths.
+It rejects traversal paths, absolute paths, duplicate paths, link traversal, external symbolic links, special files, and unsupported tar extensions.
+Symbolic link cycles and chains longer than 64 links are also unsupported.
+PAX metadata, sparse files, extended attributes, and ACL preservation are outside this format.
+Tar numbers must use octal fields. Base-256 numeric fields are unsupported.
+The default BusyBox image supplies the tested archive behavior.
+
+Restore copies all archives to a private temporary directory.
+It checks every SHA-256, size, and extraction path before creating any volume.
+Staging requires additional local free space for the entire snapshot.
+Restore labels its newly created volumes with a unique claim token.
+Failure cleanup removes only volumes with that token and helper containers with their matching token.
+If Docker prevents cleanup, the error includes `cleanupErrors` for the parent to report.
+Restore never removes a preexisting volume or destination container.
+
+## S3 behavior
+
+The helper uses installed AWS CLI configuration, credentials, region selection, and environment variables.
+It does not accept or store AWS access keys in the manifest.
+An optional `endpointUrl` selects an S3-compatible service.
+
+Export checks the prefix with `s3api list-objects-v2`.
+It uploads each archive with `s3api put-object --if-none-match '*'`.
+It publishes `manifest.json` last with the same condition.
+The storage service must support conditional creation.
+Download uses `s3api get-object` with a local output file.
+
+A failed S3 export can leave partial objects under its new prefix.
+The helper retains them because another writer could own later object versions.
+Choose a new prefix for a retry.
+Inspect and remove partial objects through a separate storage operation.
+The required permissions are object listing, object creation, and object reads.
+This module does not list saved snapshots or delete cloud backups.
+
+## Git API
+
+```js
+import { createWorktree, removeOwnedWorktree } from '../src/worktrees.mjs';
+
+const fork = await createWorktree(sourceSpec, 'feature-copy', {
+  path: '/existing/parent/feature-copy',
+  branch: 'feature/database-copy',
+  ref: 'HEAD',
+  copyChanges: true,
+});
+// { cwd, ownership, omittedPaths }
+
+await removeOwnedWorktree(fork);
+// { removed, branchRetained }
+
+// Explicitly discard files in this owned worktree:
+await removeOwnedWorktree(fork, { dirty: 'discard' });
+```
+
+`sourceSpec` can be a specification with `cwd` or a directory string.
+Git identifies the repository root, common directory, refs, tracked changes, and untracked files.
+The default path is a sibling of the source repository named `destinationName`.
+The default branch is `destinationName`, and the default ref is `HEAD`.
+The helper refuses existing branches, existing paths, and destinations within the source repository.
+The destination parent directory must already exist.
+For a source subdirectory, returned `cwd` preserves that relative location inside the new worktree.
+
+The default fork applies the source's staged and unstaged changes as one working-tree patch.
+It preserves binary bytes, additions, deletions, and executable modes.
+It leaves the source index and source files unchanged.
+A different base ref can cause patch conflicts. The helper then removes its new worktree and branch.
+Set `copyChanges: false` for a clean checkout of the selected ref.
+
+Untracked files come from `git ls-files --others --exclude-standard`.
+Only regular files qualify for copying.
+Credential names, private keys, dependency directories, and common build directories are excluded.
+The same exclusions apply to tracked changes.
+The helper reports excluded candidates in `omittedPaths`.
+Git already excludes ignored files from the untracked candidates.
+The helper does not report those ignored files individually.
+Untracked symbolic links and special files are omitted.
+The selected ref must not track recognized credential files.
+Credential detection uses conservative filename rules. It cannot detect credentials embedded in arbitrary source files.
+Committed build files remain part of the selected ref.
+Submodule working directories and changes within submodules are not copied.
+
+Ownership records reside in `<git-common-dir>/agent-env-worktrees/<token>.json`.
+Persist the returned `ownership` object with the instance record.
+Removal checks that record and Git's current repository, path, and branch.
+It refuses dirty worktrees, including ignored files, unless the caller explicitly selects `dirty: 'discard'`.
+Commit or preserve valuable files before removal.
+Removal retains branches with new commits.
+Failure cleanup reports a `cleanupError` if Git cannot remove the owned resources.
+Callers must serialize Git operations while helpers create or remove a worktree.
+
+The parent coordinates source and volume forks.
+Create the worktree first, set the destination specification's `cwd`, and then create the destination volumes and services.
+If the data fork fails, remove the returned worktree with the explicit discard option.
+That new worktree normally contains the copied source changes and therefore counts as dirty.
+
+## Verification
+
+```sh
+node --check src/snapshots.mjs
+node --check src/worktrees.mjs
+npm run check
+node test/run.mjs features
+AGENT_ENV_TEST_SSH=my-test-host node test/run.mjs ssh
+AGENT_ENV_TEST_S3=s3://test-bucket/prefix node test/run.mjs s3
+```
+
+Set `AGENT_ENV_CLI` to the absolute path of an installed package executable.
+Docker tests require a running Docker host and can download public images.
+Tests use owned temporary containers, volumes, directories, and Git repositories.
+They check restoration, source isolation, Compose volumes, archive checksums, cleanup, conflicts, and credential exclusions through the public CLI.
+S3 tests use a real S3 service. CI provides a disposable SeaweedFS fixture.
+SSH tests use a real server. CI provides a disposable local SSH fixture.
+
+Live integration passed against a temporary SeaweedFS S3 server. Verify each production storage service separately.
+Test export and restore against a temporary bucket or a local S3-compatible server.
+Check the service's conditional write behavior and remove the test objects afterward.
+Live SSH snapshot and restore integration passed on a temporary Hetzner Docker host.
+These checks require actual endpoint credentials or an SSH host that the parent supplies.

package/examples/agent-swarm/README.md

@@ -0,0 +1,5 @@
+# Agent Swarm
+
+Run the real API and dashboard from a local Agent Swarm checkout.
+See [the run guide](../../docs/agent-swarm.md) for commands, isolation, and verification.
+See [verification evidence](VERIFICATION.md) for the tested revision and observed results.

package/examples/agent-swarm/agent-env.json

@@ -0,0 +1,11 @@
+{
+  "provider": "compose",
+  "startupTimeoutSeconds": 900,
+  "compose": {
+    "files": ["compose.agent-env.yaml"],
+    "routes": {
+      "api": { "service": "api", "target": 3013, "port": 4313, "protocol": "http" },
+      "ui": { "service": "ui", "target": 5274, "port": 4574, "protocol": "http" }
+    }
+  }
+}