Add stacked disk integration coverage and documentation (#1316)

* Add OCI transport and base clone with DiskImageKit

* Address stacked OCI pull review feedback

* Stream file digest hashing

* Lock frozen overlays during push

.ci/build-release.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+
+set -eu
+
+ARCH="$1"
+SCRATCH_PATH=".build/$ARCH"
+OUTPUT_PATH=".build/prebuilt/$ARCH"
+
+swift build \
+  --build-system swiftbuild \
+  --scratch-path "$SCRATCH_PATH" \
+  --arch "$ARCH" \
+  --configuration release \
+  --product tart
+
+BIN_PATH=$(swift build \
+  --build-system swiftbuild \
+  --scratch-path "$SCRATCH_PATH" \
+  --arch "$ARCH" \
+  --configuration release \
+  --show-bin-path)
+
+mkdir -p "$OUTPUT_PATH"
+cp "$BIN_PATH/tart" "$OUTPUT_PATH/tart"

.ci/create-pkg.sh

@@ -2,7 +2,7 @@
 
 set -e
 
-export VERSION="${CIRRUS_TAG:-0}"
+export VERSION="${VERSION:-0}"
 
 mkdir -p .ci/pkg/
 cp .build/arm64-apple-macosx/release/tart .ci/pkg/tart

.ci/set-version.sh

@@ -1,7 +1,11 @@
 #!/bin/sh
 
-TMPFILE=$(mktemp)
-envsubst < Sources/tart/CI/CI.swift > $TMPFILE
-mv $TMPFILE Sources/tart/CI/CI.swift
+set -e
 
-/usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string ${CIRRUS_TAG}" Resources/Info.plist
+: "${VERSION:?VERSION must be set}"
+
+TMPFILE=$(mktemp)
+perl -pe 's/\$\{VERSION\}/$ENV{VERSION}/g' Sources/tart/CI/CI.swift > "$TMPFILE"
+mv "$TMPFILE" Sources/tart/CI/CI.swift
+
+/usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string ${VERSION}" Resources/Info.plist

.ci/sign-release.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+
+set -eu
+
+APP_PATH="dist/tart_darwin_all/tart.app"
+
+if [ "${TART_RELEASE_SNAPSHOT:-false}" = "true" ]; then
+  codesign \
+    --force \
+    --deep \
+    --sign - \
+    --entitlements Resources/tart-dev.entitlements \
+    "$APP_PATH"
+else
+  codesign \
+    --force \
+    --verbose \
+    --sign "Developer ID Application: Cirrus Labs, Inc. (9M2P8L4D89)" \
+    --timestamp \
+    --options runtime \
+    --keychain "$RUNNER_TEMP/build.keychain" \
+    --entitlements Resources/tart-prod.entitlements \
+    "$APP_PATH"
+fi
+
+codesign --verify --strict --verbose=2 "$APP_PATH"
+"$APP_PATH/Contents/MacOS/tart" --version
+
+if [ "${TART_RELEASE_SNAPSHOT:-false}" != "true" ]; then
+  NOTARIZATION_ARCHIVE="$RUNNER_TEMP/tart-notarization.zip"
+
+  ditto -c -k --keepParent "$APP_PATH" "$NOTARIZATION_ARCHIVE"
+  xcrun notarytool submit "$NOTARIZATION_ARCHIVE" \
+    --keychain-profile "notarytool" \
+    --keychain "$RUNNER_TEMP/build.keychain" \
+    --wait \
+    --timeout 20m
+  xcrun stapler staple "$APP_PATH"
+  xcrun stapler validate "$APP_PATH"
+  spctl --assess --type execute --verbose=4 "$APP_PATH"
+fi

.cirrus.yml

@@ -1,7 +1,7 @@
 use_compute_credits: true
 
 task:
-  name: Test on Sequoia
+  name: Test
   alias: test
   persistent_worker:
     labels:
@@ -11,6 +11,8 @@ task:
   build_script:
     - swift build
   test_script:
+    # Add /usr/sbin to PATH, otherwise testDiskutilInfo() fails to locate "diskutil"
+    - export PATH=$PATH:/usr/sbin
     - swift test
   integration_test_script:
     - codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/debug/tart
@@ -21,6 +23,7 @@ task:
     - source venv/bin/activate
     - pip install -r requirements.txt
     - pytest --verbose --junit-xml=pytest-junit.xml
+    - go test -v ./...
   pytest_junit_result_artifacts:
     path: "integration-tests/pytest-junit.xml"
     format: junit
@@ -37,7 +40,7 @@ task:
   name: Lint
   alias: lint
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sequoia
+    image: ghcr.io/cirruslabs/macos-runner:tahoe
   lint_script:
     - swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore --lint --report swiftformat.json .
   always:
@@ -54,103 +57,17 @@ task:
   name: Build ($BUILD_ARCH)
   alias: build
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sequoia
+    image: ghcr.io/cirruslabs/macos-runner:tahoe
   build_script: swift build --arch $BUILD_ARCH --product tart
   sign_script: codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/$BUILD_ARCH-apple-macosx/debug/tart
   binary_artifacts:
     path: .build/$BUILD_ARCH-apple-macosx/debug/tart
 
-task:
-  only_if: $CIRRUS_TAG == '' && ($CIRRUS_USER_PERMISSION == 'write' || $CIRRUS_USER_PERMISSION == 'admin')
-  name: Release (Dry Run)
-  depends_on:
-    - lint
-    - build
-  macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sequoia
-  env:
-    MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
-    AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
-    GITHUB_TOKEN: ENCRYPTED[!98ace8259c6024da912c14d5a3c5c6aac186890a8d4819fad78f3e0c41a4e0cd3a2537dd6e91493952fb056fa434be7c!]
-    GORELEASER_KEY: ENCRYPTED[!9b80b6ef684ceaf40edd4c7af93014ee156c8aba7e6e5795f41c482729887b5c31f36b651491d790f1f668670888d9fd!]
-  setup_script:
-    - cd $HOME
-    - echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
-    - security create-keychain -p password101 build.keychain
-    - security default-keychain -s build.keychain
-    - security unlock-keychain -p password101 build.keychain
-    - security import certificate.p12 -k build.keychain -P password101 -T /usr/bin/codesign -T /usr/bin/pkgbuild
-    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
-    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
-  install_script:
-    - brew install go
-    - brew install mitchellh/gon/gon
-    - brew install --cask goreleaser/tap/goreleaser-pro
-  info_script:
-    - security find-identity -v
-    - xcodebuild -version
-    - swift -version
-  goreleaser_script: goreleaser release --skip=publish --snapshot --clean
-  always:
-    dist_artifacts:
-      path: "dist/*"
-
-task:
-  name: Release
-  only_if: $CIRRUS_TAG != ''
-  depends_on:
-    - lint
-    - test
-    - build
-  macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sequoia
-  env:
-    MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
-    AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
-    GITHUB_TOKEN: ENCRYPTED[!98ace8259c6024da912c14d5a3c5c6aac186890a8d4819fad78f3e0c41a4e0cd3a2537dd6e91493952fb056fa434be7c!]
-    GORELEASER_KEY: ENCRYPTED[!9b80b6ef684ceaf40edd4c7af93014ee156c8aba7e6e5795f41c482729887b5c31f36b651491d790f1f668670888d9fd!]
-    SENTRY_ORG: cirrus-labs
-    SENTRY_PROJECT: persistent-workers
-    SENTRY_AUTH_TOKEN: ENCRYPTED[!9eaf2875d51b113e2f68598441ff8e6b2e53242e48fcb93633bd75a373fbe2e7caa900d837cc92f0b142b65579731644!]
-  setup_script:
-    - cd $HOME
-    - echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
-    - security create-keychain -p password101 build.keychain
-    - security default-keychain -s build.keychain
-    - security unlock-keychain -p password101 build.keychain
-    - security import certificate.p12 -k build.keychain -P password101 -T /usr/bin/codesign -T /usr/bin/pkgbuild
-    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
-    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
-  install_script:
-    - brew install go getsentry/tools/sentry-cli
-    - brew install mitchellh/gon/gon
-    - brew install --cask goreleaser/tap/goreleaser-pro
-  info_script:
-    - security find-identity -v
-    - xcodebuild -version
-    - swift -version
-  release_script: goreleaser
-  upload_sentry_debug_files_script:
-    - cd .build/arm64-apple-macosx/release/
-    # Generate and upload symbols
-    - dsymutil tart
-    - sentry-cli debug-files upload tart.dSYM/
-    - SENTRY_PROJECT=tart sentry-cli debug-files upload tart.dSYM/
-    # Bundle and upload sources
-    - sentry-cli debug-files bundle-sources tart.dSYM
-    - sentry-cli debug-files upload tart.src.zip
-    - SENTRY_PROJECT=tart sentry-cli debug-files upload tart.src.zip
-  create_sentry_release_script:
-    - export SENTRY_RELEASE="tart@$CIRRUS_TAG"
-    - sentry-cli releases new $SENTRY_RELEASE
-    - sentry-cli releases set-commits $SENTRY_RELEASE --auto
-    - sentry-cli releases finalize $SENTRY_RELEASE
-
 task:
   name: Deploy Documentation
   only_if: $CIRRUS_BRANCH == 'main'
   container:
-    image: ghcr.io/cirruslabs/mkdocs-material-insiders:latest
+    image: ghcr.io/squidfunk/mkdocs-material:latest
     registry_config: ENCRYPTED[!cf1a0f25325aa75bad3ce6ebc890bc53eb0044c02efa70d8cefb83ba9766275a994b4831706c52630a0692b2fa9cfb9e!]
   env:
     DEPLOY_TOKEN: ENCRYPTED[!45ed45666558902ed1c2400add734ec063103bec31841847e8c8764802fca229bfa6d85c690e16ad159e047574b48793!]

.editorconfig

@@ -4,3 +4,8 @@ root = true
 indent_style = space
 indent_size = 2
 insert_final_newline = true
+
+[integration-tests/**]
+indent_style = unset
+indent_size = unset
+insert_final_newline = unset

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build_cached:
+    name: Build tart (cached)
+    runs-on: xcode-27
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build
+        run: |
+          export COMPILATION_CACHE_ENABLE_CACHING=YES
+          export COMPILATION_CACHE_REMOTE_SERVICE_PATH="$HOME/.cirruslabs/omni-cache.sock"
+          export COMPILATION_CACHE_ENABLE_PLUGIN=YES
+          export COMPILATION_CACHE_ENABLE_INTEGRATED_QUERIES=YES
+          export COMPILATION_CACHE_ENABLE_DETACHED_KEY_QUERIES=YES
+          export SWIFT_ENABLE_COMPILE_CACHE=YES
+          export SWIFT_ENABLE_EXPLICIT_MODULES=YES
+          export SWIFT_USE_INTEGRATED_DRIVER=YES
+          export CLANG_ENABLE_COMPILE_CACHE=YES
+          export CLANG_ENABLE_MODULES=YES
+          swift build --build-system swiftbuild --product tart
+
+  build_no_cache:
+    name: Build tart (no cache)
+    runs-on: xcode-27
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build
+        run: swift build --build-system swiftbuild --product tart

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  merge_group:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: xcode-27
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: integration-tests/go.mod
+          cache-dependency-path: integration-tests/go.sum
+      - name: Build
+        run: swift build --build-system swiftbuild
+      - name: Run unit tests
+        run: |
+          export PATH="$PATH:/usr/sbin"
+          swift test --build-system swiftbuild
+      # The Python suite boots Tart VMs, but hosted ARM macOS runners do not support nested virtualization.
+      - name: Run OpenTelemetry integration tests
+        run: |
+          bin_path="$(swift build --build-system swiftbuild --show-bin-path)"
+          codesign --sign - --entitlements Resources/tart-dev.entitlements --force "$bin_path/tart"
+          cd integration-tests
+          PATH="$bin_path:$PATH" go test -v ./...

.github/workflows/release.yml

@@ -0,0 +1,111 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    if: github.event_name == 'push' && github.repository == 'openai/tart'
+    name: Release
+    runs-on: xcode-27
+    environment: publish
+    timeout-minutes: 90
+    permissions:
+      contents: read
+    env:
+      VERSION: ${{ github.ref_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Import signing certificate
+        env:
+          AC_PASSWORD: ${{ secrets.AC_PASSWORD }}
+          KEYCHAIN_PASSWORD: temporary-password
+          MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }}
+          P12_PASSWORD: password101
+        run: |
+          echo "$MACOS_CERTIFICATE" | base64 --decode > "$RUNNER_TEMP/certificate.p12"
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$RUNNER_TEMP/build.keychain"
+          security set-keychain-settings -lut 21600 "$RUNNER_TEMP/build.keychain"
+          security default-keychain -s "$RUNNER_TEMP/build.keychain"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$RUNNER_TEMP/build.keychain"
+          security import "$RUNNER_TEMP/certificate.p12" \
+            -k "$RUNNER_TEMP/build.keychain" \
+            -P "$P12_PASSWORD" \
+            -T /usr/bin/codesign \
+            -T /usr/bin/pkgbuild
+          security set-key-partition-list \
+            -S apple-tool:,apple:,codesign: \
+            -s \
+            -k "$KEYCHAIN_PASSWORD" \
+            "$RUNNER_TEMP/build.keychain"
+          security list-keychain -d user -s "$RUNNER_TEMP/build.keychain"
+          xcrun notarytool store-credentials "notarytool" \
+            --apple-id "hello@cirruslabs.org" \
+            --team-id "9M2P8L4D89" \
+            --password "$AC_PASSWORD" \
+            --keychain "$RUNNER_TEMP/build.keychain"
+      - name: Create release app token for this repo
+        id: app-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          permission-contents: write
+      - name: Create release app token for homebrew-tools
+        id: tap-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: openai
+          repositories: homebrew-tools
+          permission-contents: write
+          permission-pull-requests: write
+      - name: Release
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        with:
+          distribution: goreleaser-pro
+          version: "~> v2"
+          args: release --clean
+        env:
+          GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ steps.tap-token.outputs.token }}
+
+  snapshot:
+    if: github.event_name == 'workflow_dispatch'
+    name: Release (Dry Run)
+    runs-on: xcode-27
+    timeout-minutes: 90
+    permissions:
+      contents: read
+    env:
+      TART_RELEASE_SNAPSHOT: "true"
+      VERSION: snapshot
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Build snapshot
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        with:
+          distribution: goreleaser-pro
+          version: "~> v2"
+          args: release --skip=publish --snapshot --clean
+      - name: Upload snapshot artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: tart-snapshot
+          path: dist/*

.goreleaser.yml

@@ -5,8 +5,8 @@ project_name: tart
 before:
   hooks:
     - .ci/set-version.sh
-    - swift build --arch arm64 --configuration release --product tart
-    - swift build --arch x86_64 --configuration release --product tart
+    - sh .ci/build-release.sh arm64
+    - sh .ci/build-release.sh x86_64
 
 builds:
   - id: tart
@@ -19,26 +19,33 @@ builds:
       - amd64
     binary: tart.app/Contents/MacOS/tart
     prebuilt:
-      path: '.build/{{- if eq .Arch "arm64" }}arm64{{- else }}x86_64{{ end }}-apple-macosx/release/tart'
+      path: '.build/prebuilt/{{- if eq .Arch "arm64" }}arm64{{- else }}x86_64{{ end }}/tart'
 
 universal_binaries:
   - name_template: tart.app/Contents/MacOS/tart
     replace: true
     hooks:
-      post: gon gon.hcl
+      post:
+        - mkdir -p dist/tart_darwin_all/tart.app/Contents/Resources
+        - cp Resources/embedded.provisionprofile dist/tart_darwin_all/tart.app/Contents/
+        - cp Resources/Info.plist dist/tart_darwin_all/tart.app/Contents/
+        - cp "Resources/actool/UPW Tart.icns" "Resources/actool/Assets.car" dist/tart_darwin_all/tart.app/Contents/Resources/
+        - cmd: .ci/sign-release.sh
+          output: true
 
 archives:
   - name_template: "{{ .ProjectName }}"
     files:
-      - src: Resources/embedded.provisionprofile
-        dst: tart.app/Contents
-        strip_parent: true
-      - src: Resources/Info.plist
-        dst: tart.app/Contents
-        strip_parent: true
-      - src: Resources/AppIcon.png
-        dst: tart.app/Contents/Resources
-        strip_parent: true
+      - src: dist/tart_darwin_all/tart.app/Contents/Info.plist
+        dst: tart.app/Contents/Info.plist
+      - src: dist/tart_darwin_all/tart.app/Contents/embedded.provisionprofile
+        dst: tart.app/Contents/embedded.provisionprofile
+      - src: dist/tart_darwin_all/tart.app/Contents/Resources/UPW Tart.icns
+        dst: tart.app/Contents/Resources/UPW Tart.icns
+      - src: dist/tart_darwin_all/tart.app/Contents/Resources/Assets.car
+        dst: tart.app/Contents/Resources/Assets.car
+      - src: dist/tart_darwin_all/tart.app/Contents/_CodeSignature/CodeResources
+        dst: tart.app/Contents/_CodeSignature/CodeResources
       - LICENSE
 
 release:
@@ -46,9 +53,14 @@ release:
 
 brews:
   - name: tart
+    directory: Formula
     repository:
-      owner: cirruslabs
-      name: homebrew-cli
+      owner: openai
+      name: homebrew-tools
+      token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
+      branch: "tart-{{ .Version }}"
+      pull_request:
+        enabled: true
     caveats: |
       Tart has been installed. You might want to reduce the default DHCP lease time
       from 86,400 to 600 seconds to avoid DHCP shortage when running lots of VMs daily:
@@ -56,15 +68,19 @@ brews:
         sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.InternetSharing.default.plist bootpd -dict DHCPLeaseTimeSecs -int 600
 
       See https://tart.run/faq/#changing-the-default-dhcp-lease-time for more details.
-    homepage: https://github.com/cirruslabs/tart
-    license: "Fair Source"
+    homepage: https://github.com/openai/tart
+    license: FSL-1.1-ALv2
     description: Run macOS and Linux VMs on Apple Hardware
     skip_upload: auto
     dependencies:
-      - "cirruslabs/cli/softnet"
+      - "openai/tools/softnet"
     install: |
       libexec.install Dir["*"]
       bin.write_exec_script "#{libexec}/tart.app/Contents/MacOS/tart"
-      generate_completions_from_executable(libexec/"tart.app/Contents/MacOS/tart", "--generate-completion-script")
     custom_block: |
-      depends_on :macos => :ventura
+      on_macos do
+        depends_on :macos => :ventura
+      end
+      def post_install
+        generate_completions_from_executable(libexec/"tart.app/Contents/MacOS/tart", "--generate-completion-script")
+      end

CONTRIBUTING.md

@@ -20,7 +20,7 @@ Table of Contents
 ```
 ## How to Create an Issue/Enhancement
 
-1. Go to the [Issue page](https://github.com/cirruslabs/tart/issues) of the repository
+1. Go to the [Issue page](https://github.com/openai/tart/issues) of the repository
 2. Click on the "New Issue" button
 3. Provide a descriptive title and detailed description of the issue or enhancement you're suggesting
 4. Submit the issue

LICENSE

@@ -1,45 +1,105 @@
-Fair Source License, version 0.9
+# Functional Source License, Version 1.1, ALv2 Future License
 
-Copyright (C) 2023 Cirrus Labs, Inc.
+## Abbreviation
 
-Licensor: Cirrus Labs, Inc.
+FSL-1.1-ALv2
 
-Software: Tart
+## Notice
 
-Use Limitation: 100 users. User is defined as a single core of a central processing unit (CPU) used by the product.
-The Use Limitation does not apply to CPUs installed in devices used by a single individual.
+Copyright 2022-2026 OpenAI
 
-License Grant. Licensor hereby grants to each recipient of the
-Software ("you") a non-exclusive, non-transferable, royalty-free and
-fully-paid-up license, under all of the Licensor's copyright and
-patent rights, to use, copy, distribute, prepare derivative works of,
-publicly perform and display the Software, subject to the Use
-Limitation and the conditions set forth below.
+## Terms and Conditions
 
-Use Limitation. The license granted above allows use by up to the
-number of users per entity set forth above (the "Use Limitation"). For
-determining the number of users, "you" includes all affiliates,
-meaning legal entities controlling, controlled by, or under common
-control with you. If you exceed the Use Limitation, your use is
-subject to payment of Licensor's then-current list price for licenses.
+### Licensor ("We")
 
-Conditions. Redistribution in source code or other forms must include
-a copy of this license document to be provided in a reasonable
-manner. Any redistribution of the Software is only allowed subject to
-this license.
+The party offering the Software under these Terms and Conditions.
 
-Trademarks. This license does not grant you any right in the
-trademarks, service marks, brand names or logos of Licensor.
+### The Software
 
-DISCLAIMER. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OR
-CONDITION, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. LICENSORS HEREBY DISCLAIM ALL LIABILITY, WHETHER IN
-AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE.
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
 
-Termination. If you violate the terms of this license, your rights
-will terminate automatically and will not be reinstated without the
-prior written consent of Licensor. Any such termination will not
-affect the right of others who may have received copies of the
-Software from you.
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

PROFILING.md

@@ -7,7 +7,7 @@ Perhaps, the easiest, but not the most comprehensive way to tell what's going on
 In the example below, you will run `tart pull` via `time(1)` to gather generalized CPU, I/O and memory usage metrics:
 
 ```shell
-/usr/bin/time -l tart pull ghcr.io/cirruslabs/macos-sequoia-base:latest
+/usr/bin/time -l tart pull ghcr.io/cirruslabs/macos-tahoe-base:latest
 ```
 
 **Note:** you need to specify a full path to `time(1)` binary, otherwise the shell's built-in `time` command will be invoked, which doesn't have the `-l` command-line argument.
@@ -48,7 +48,7 @@ To use it, make sure that [Xcode](https://developer.apple.com/xcode/resources/)
 Once done, you can create a CPU profile of `tart pull`:
 
 ```shell
-xctrace record --template "CPU Profiler" --target-stdout - --launch -- /opt/homebrew/bin/tart pull ghcr.io/cirruslabs/macos-sequoia-base:latest
+xctrace record --template "CPU Profiler" --target-stdout - --launch -- /opt/homebrew/bin/tart pull ghcr.io/cirruslabs/macos-tahoe-base:latest
 ```
 
 Now that `xctrace(1)` is running, you'll see the `tart pull`-related output first, and once finished, the following line will appear:

Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "668bad809d4882f75f097e66a12a6dbc8e61ec998f1800a7e09439c854fadda1",
+  "originHash" : "061dfe6cdf4e6dbf32b51c5e7023c4ae69726dcafb42a35b34e5489b0338c17f",
   "pins" : [
     {
       "identity" : "antlr4",
@@ -13,19 +13,19 @@
     {
       "identity" : "cirruslabs_tart-guest-agent_apple_swift",
       "kind" : "remoteSourceControl",
-      "location" : "https://buf.build/gen/swift/git/1.28.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_apple_swift.git",
+      "location" : "https://buf.build/gen/swift/git/1.33.3-20260114140118-bd09c26a260f.1/cirruslabs_tart-guest-agent_apple_swift.git",
       "state" : {
-        "revision" : "ccfae5de1917cdb0d7c5000008fa5ed0bad032bf",
-        "version" : "1.28.2-00000000000000-17d7dedafb88.1"
+        "revision" : "5c49a653f4b003161077d194bc708b7373628c99",
+        "version" : "1.33.3-20260114140118-bd09c26a260f.1"
       }
     },
     {
       "identity" : "cirruslabs_tart-guest-agent_grpc_swift",
       "kind" : "remoteSourceControl",
-      "location" : "https://buf.build/gen/swift/git/1.24.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_grpc_swift.git",
+      "location" : "https://buf.build/gen/swift/git/1.27.1-20260114140118-bd09c26a260f.1/cirruslabs_tart-guest-agent_grpc_swift.git",
       "state" : {
-        "branch" : "1.24.2-00000000000000-17d7dedafb88.1",
-        "revision" : "b8421f137325fe8de737ff5b61238f6f2131b2a8"
+        "branch" : "main",
+        "revision" : "4935078c2fe2508360843596d71a1f844ce639a6"
       }
     },
     {
@@ -42,8 +42,35 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/grpc/grpc-swift.git",
       "state" : {
-        "revision" : "8c5e99d0255c373e0330730d191a3423c57373fb",
-        "version" : "1.24.2"
+        "revision" : "8f57f68b9d247fe3759fa9f18e1fe919911e6031",
+        "version" : "1.27.1"
+      }
+    },
+    {
+      "identity" : "opentelemetry-swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/open-telemetry/opentelemetry-swift",
+      "state" : {
+        "branch" : "main",
+        "revision" : "ed37be9525081509ab62410d38b705c2b3f0d5a4"
+      }
+    },
+    {
+      "identity" : "opentelemetry-swift-core",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/open-telemetry/opentelemetry-swift-core.git",
+      "state" : {
+        "revision" : "240c8d5e36c3c7b774ed961325369f0b1f2c965f",
+        "version" : "2.3.0"
+      }
+    },
+    {
+      "identity" : "opentracing-objc",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/undefinedlabs/opentracing-objc",
+      "state" : {
+        "revision" : "18c1a35ca966236cee0c5a714a51a73ff33384c1",
+        "version" : "0.5.2"
       }
     },
     {
@@ -55,15 +82,6 @@
         "version" : "0.1.0"
       }
     },
-    {
-      "identity" : "sentry-cocoa",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/getsentry/sentry-cocoa",
-      "state" : {
-        "revision" : "65b3d2a7608685e8d4a37c68fa2c64f28d0b537e",
-        "version" : "8.51.1"
-      }
-    },
     {
       "identity" : "swift-algorithms",
       "kind" : "remoteSourceControl",
@@ -87,8 +105,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-atomics.git",
       "state" : {
-        "revision" : "cd142fd2f64be2100422d658e7411e39489da985",
-        "version" : "1.2.0"
+        "revision" : "b601256eab081c0f92f059e12818ac1d4f178ff7",
+        "version" : "1.3.0"
       }
     },
     {
@@ -123,8 +141,17 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-log.git",
       "state" : {
-        "revision" : "9cb486020ebf03bfa5b5df985387a14a98744537",
-        "version" : "1.6.1"
+        "revision" : "2778fd4e5a12a8aaa30a3ee8285f4ce54c5f3181",
+        "version" : "1.9.1"
+      }
+    },
+    {
+      "identity" : "swift-metrics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-metrics.git",
+      "state" : {
+        "revision" : "0743a9364382629da3bf5677b46a2c4b1ce5d2a6",
+        "version" : "2.7.1"
       }
     },
     {
@@ -132,8 +159,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio.git",
       "state" : {
-        "revision" : "34d486b01cd891297ac615e40d5999536a1e138d",
-        "version" : "2.83.0"
+        "revision" : "233f61bc2cfbb22d0edeb2594da27a20d2ce514e",
+        "version" : "2.93.0"
       }
     },
     {
@@ -186,8 +213,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-protobuf.git",
       "state" : {
-        "revision" : "ebc7251dd5b37f627c93698e4374084d98409633",
-        "version" : "1.28.2"
+        "revision" : "c169a5744230951031770e27e475ff6eefe51f9d",
+        "version" : "1.33.3"
       }
     },
     {
@@ -261,6 +288,15 @@
         "branch" : "master",
         "revision" : "e03289289155b4e7aa565e32862f9cb42140596a"
       }
+    },
+    {
+      "identity" : "thrift-swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/undefinedlabs/Thrift-Swift",
+      "state" : {
+        "revision" : "18ff09e6b30e589ed38f90a1af23e193b8ecef8e",
+        "version" : "1.1.2"
+      }
     }
   ],
   "version" : 3

Package.swift

@@ -17,15 +17,17 @@ let package = Package(
     .package(url: "https://github.com/antlr/antlr4", exact: "4.13.2"),
     .package(url: "https://github.com/apple/swift-atomics.git", .upToNextMajor(from: "1.2.0")),
     .package(url: "https://github.com/nicklockwood/SwiftFormat", from: "0.53.6"),
-    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.51.1"),
     .package(url: "https://github.com/cfilipov/TextTable", branch: "master"),
     .package(url: "https://github.com/sersoft-gmbh/swift-sysctl.git", from: "1.8.0"),
     .package(url: "https://github.com/orchetect/SwiftRadix", from: "1.3.1"),
     .package(url: "https://github.com/groue/Semaphore", from: "0.0.8"),
     .package(url: "https://github.com/fumoboy007/swift-retry", from: "0.2.3"),
     .package(url: "https://github.com/jozefizso/swift-xattr", from: "3.0.0"),
-    .package(url: "https://github.com/grpc/grpc-swift.git", .upToNextMajor(from: "1.24.2")),
-    .package(url: "https://buf.build/gen/swift/git/1.24.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_grpc_swift.git", revision: "1.24.2-00000000000000-17d7dedafb88.1"),
+    .package(url: "https://github.com/grpc/grpc-swift.git", .upToNextMajor(from: "1.27.0")),
+    .package(url: "https://buf.build/gen/swift/git/1.27.1-20260114140118-bd09c26a260f.1/cirruslabs_tart-guest-agent_grpc_swift.git", branch: "main"),
+    .package(url: "https://github.com/open-telemetry/opentelemetry-swift", branch: "main"),
+    .package(url: "https://github.com/open-telemetry/opentelemetry-swift-core", from: "2.3.0"),
+
   ],
   targets: [
     .executableTarget(name: "tart", dependencies: [
@@ -35,7 +37,6 @@ let package = Package(
       .product(name: "SwiftDate", package: "SwiftDate"),
       .product(name: "Antlr4Static", package: "Antlr4"),
       .product(name: "Atomics", package: "swift-atomics"),
-      .product(name: "Sentry", package: "sentry-cocoa"),
       .product(name: "TextTable", package: "TextTable"),
       .product(name: "Sysctl", package: "swift-sysctl"),
       .product(name: "SwiftRadix", package: "SwiftRadix"),
@@ -44,6 +45,10 @@ let package = Package(
       .product(name: "XAttr", package: "swift-xattr"),
       .product(name: "GRPC", package: "grpc-swift"),
       .product(name: "Cirruslabs_TartGuestAgent_Grpc_Swift", package: "cirruslabs_tart-guest-agent_grpc_swift"),
+      .product(name: "OpenTelemetryApi", package: "opentelemetry-swift-core"),
+      .product(name: "OpenTelemetrySdk", package: "opentelemetry-swift-core"),
+      .product(name: "OpenTelemetryProtocolExporterHTTP", package: "opentelemetry-swift"),
+      .product(name: "ResourceExtension", package: "opentelemetry-swift"),
     ], exclude: [
       "OCI/Reference/Makefile",
       "OCI/Reference/Reference.g4",

README.md

@@ -1,4 +1,4 @@
-<img src="https://github.com/cirruslabs/tart/raw/main/Resources/TartSocial.png"/>
+<img src="https://github.com/openai/tart/raw/main/Resources/TartSocial.png"/>
 
 *Tart* is a virtualization toolset to build, run and manage macOS and Linux virtual machines (VMs) on Apple Silicon.
 Built by CI engineers for your automation needs. Here are some highlights of Tart:
@@ -8,67 +8,52 @@ Built by CI engineers for your automation needs. Here are some highlights of Tar
 * Use Tart Packer Plugin to automate VM creation.
 * Easily integrates with any CI system.
 
-Tart powers [Cirrus Runners](https://cirrus-runners.app/)
-service — a drop-in replacement for the standard GitHub-hosted runners, offering 2-3 times better performance for a fraction of the price.
-
-<p align="center">
-  <a href="https://cirrus-runners.app/?utm_source=github&utm_medium=referral" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/CirrusRunnersForGHA.png" height="65"/>
-  </a>
-</p>
-
 Many companies are using Tart in their internal setups. Here are just a few of them:
 
 <p align="center">
   <a href="https://atlassian.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Atlassian.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Atlassian.png" height="65"/>
   </a>
   <a href="https://www.figma.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Figma.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Figma.png" height="65"/>
   </a>
   <a href="https://mullvad.net/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Mullvad.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Mullvad.png" height="65"/>
   </a>
   <a href="https://krisp.ai/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Krisp.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Krisp.png" height="65"/>
   </a>
   <a href="https://testingbot.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/TestingBot.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/TestingBot.png" height="65"/>
   </a>
   <a href="https://symflower.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Symflower.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Symflower.png" height="65"/>
   </a>
   <a href="https://transloadit.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Transloadit.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Transloadit.png" height="65"/>
   </a>
   <a href="https://cirrus-ci.org/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/CirrusCI.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/CirrusCI.png" height="65"/>
   </a>
   <a href="https://www.pitsdatarecovery.net/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/PITSGlobalDataRecoveryServices.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/PITSGlobalDataRecoveryServices.png" height="65"/>
   </a>
   <a href="https://expo.dev/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Expo.png" height="65"/>
+    <img src="https://github.com/openai/tart/raw/main/Resources/Users/Expo.png" height="65"/>
   </a>
 </p>
 
-**Note:** If your company or project is using Tart please consider [sharing with the community](https://github.com/cirruslabs/tart/discussions/857).
-
-<p align="center">
-  <a href="https://aws.amazon.com/marketplace/pp/prodview-qczco34wlkdws?utm_source=github&utm_medium=referral" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/AWSMarkeplaceLogo.png" height="90"/>
-  </a>
-</p>
+**Note:** If your company or project is using Tart please consider [sharing with the community](https://github.com/openai/tart/discussions/857).
 
 ## Usage
 
 Try running a Tart VM on your Apple Silicon device running macOS 13.0 (Ventura) or later (will download a 25 GB image):
 
 ```bash
-brew install cirruslabs/cli/tart
+brew install openai/tools/tart
 tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base
 tart run tahoe-base
 ```
 
-Please check the [official documentation](https://tart.run) for more information and/or feel free to use [discussions](https://github.com/cirruslabs/tart/discussions)
+Please check the [official documentation](https://tart.run) for more information and/or feel free to use [discussions](https://github.com/openai/tart/discussions)
 for remaining questions.

Resources/Info.plist

@@ -7,15 +7,17 @@
 	<key>CFBundleDisplayName</key>
 	<string>Tart</string>
 	<key>CFBundleIdentifier</key>
-	<string>org.cirruslabs.tart</string>
+	<string>com.github.cirruslabs.tart</string>
 	<key>CFBundleExecutable</key>
 	<string>tart</string>
-  <key>LSApplicationCategoryType</key>
-  <string>public.app-category.developer-tools</string>
-	<key>CFBundleIconFiles</key>
-	<array>
-		<string>AppIcon.png</string>
-	</array>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>LSApplicationCategoryType</key>
+	<string>public.app-category.developer-tools</string>
+	<key>CFBundleIconFile</key>
+	<string>UPW Tart</string>
+	<key>CFBundleIconName</key>
+	<string>UPW Tart</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoads</key>

Resources/UPW Tart.icon/icon.json

@@ -0,0 +1,140 @@
+{
+  "fill" : "automatic",
+  "groups" : [
+    {
+      "blend-mode" : "normal",
+      "blur-material" : 0.5,
+      "layers" : [
+        {
+          "hidden" : false,
+          "image-name-specializations" : [
+            {
+              "value" : "4.4-–-layer.png"
+            },
+            {
+              "idiom" : "square",
+              "value" : "UPW Tart L4.png"
+            }
+          ],
+          "name" : "UPW Tart L4"
+        }
+      ],
+      "opacity" : 1,
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 1
+      },
+      "specular" : true,
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.25
+      }
+    },
+    {
+      "layers" : [
+        {
+          "image-name-specializations" : [
+            {
+              "value" : "3.3-–-layer.png"
+            },
+            {
+              "idiom" : "square",
+              "value" : "UPW Tart L3.png"
+            }
+          ],
+          "name" : "UPW Tart L3",
+          "position-specializations" : [
+            {
+              "idiom" : "square",
+              "value" : {
+                "scale" : 1,
+                "translation-in-points" : [
+                  0,
+                  0
+                ]
+              }
+            }
+          ]
+        }
+      ],
+      "shadow" : {
+        "kind" : "none",
+        "opacity" : 1
+      },
+      "specular" : false,
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.25
+      }
+    },
+    {
+      "blur-material" : null,
+      "layers" : [
+        {
+          "image-name-specializations" : [
+            {
+              "value" : "2.2-–-layer.png"
+            },
+            {
+              "idiom" : "square",
+              "value" : "UPW Tart L2.png"
+            }
+          ],
+          "name" : "UPW Tart L2"
+        }
+      ],
+      "position-specializations" : [
+        {
+          "idiom" : "square",
+          "value" : {
+            "scale" : 1,
+            "translation-in-points" : [
+              0,
+              0
+            ]
+          }
+        }
+      ],
+      "shadow" : {
+        "kind" : "none",
+        "opacity" : 1
+      },
+      "specular" : true,
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.25
+      }
+    },
+    {
+      "layers" : [
+        {
+          "image-name-specializations" : [
+            {
+              "value" : "1.1-–-layer.png"
+            },
+            {
+              "idiom" : "square",
+              "value" : "UPW Tart L1.png"
+            }
+          ],
+          "name" : "UPW Tart L1"
+        }
+      ],
+      "shadow" : {
+        "kind" : "layer-color",
+        "opacity" : 0.5
+      },
+      "specular" : true,
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.25
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}

Resources/actool/Info.plist

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIconFile</key>
+	<string>UPW Tart</string>
+	<key>CFBundleIconName</key>
+	<string>UPW Tart</string>
+</dict>
+</plist>

Sources/tart/CI/CI.swift

@@ -1,5 +1,5 @@
 struct CI {
-  private static let rawVersion = "${CIRRUS_TAG}"
+  private static let rawVersion = "${VERSION}"
 
   static var version: String {
     rawVersion.expanded() ? rawVersion : "SNAPSHOT"

Sources/tart/Commands/Clone.swift

@@ -31,6 +31,12 @@ struct Clone: AsyncParsableCommand {
   @Flag(help: .hidden)
   var deduplicate: Bool = false
 
+  @Flag(help: "create a stacked disk that uses the source image as an immutable base")
+  var stacked: Bool = false
+
+  @Option(help: ArgumentHelp("limit automatic pruning to n gigabytes", valueName: "n"))
+  var pruneLimit: UInt = 100
+
   func validate() throws {
     if newName.contains("/") {
       throw ValidationError("<new-name> should be a local name")
@@ -42,16 +48,45 @@ struct Clone: AsyncParsableCommand {
   }
 
   func run() async throws {
-    let ociStorage = VMStorageOCI()
-    let localStorage = VMStorageLocal()
+    let ociStorage = try VMStorageOCI()
+    let localStorage = try VMStorageLocal()
+    let remoteName = try? RemoteName(sourceName)
 
-    if let remoteName = try? RemoteName(sourceName), !ociStorage.exists(remoteName) {
+    if stacked {
+      guard remoteName != nil else {
+        throw ValidationError("--stacked requires a remote image")
+      }
+      try DiskImageStack.requireSupport()
+    }
+
+    if let remoteName, try !ociStorage.hasUsableCachedImageForClone(remoteName, requireManifest: stacked) {
       // Pull the VM in case it's OCI-based and doesn't exist locally yet
       let registry = try Registry(host: remoteName.host, namespace: remoteName.namespace, insecure: insecure)
-      try await ociStorage.pull(remoteName, registry: registry, concurrency: concurrency, deduplicate: deduplicate)
+      var resolvedManifest: (manifest: OCIManifest, data: Data)?
+
+      // Fail before pulling disk content when this host cannot create a writable stacked disk.
+      if !stacked {
+        let (manifest, manifestData) = try await registry.pullManifest(reference: remoteName.reference.value)
+        if manifest.layers.contains(where: { $0.mediaType == asifOverlayMediaType }) {
+          try DiskImageStack.requireSupport()
+        }
+        resolvedManifest = (manifest, manifestData)
+      }
+
+      try await ociStorage.pull(
+        remoteName,
+        registry: registry,
+        concurrency: concurrency,
+        deduplicate: deduplicate,
+        requireManifest: stacked,
+        resolvedManifest: resolvedManifest
+      )
     }
 
     let sourceVM = try VMStorageHelper.open(sourceName)
+    if sourceVM.isStackedVM || sourceVM.isStackedCachedImage {
+      try DiskImageStack.requireSupport()
+    }
     let tmpVMDir = try VMDirectory.temporary()
 
     // Lock the temporary VM directory to prevent it's garbage collection
@@ -63,9 +98,28 @@ struct Clone: AsyncParsableCommand {
       let lock = try FileLock(lockURL: Config().tartHomeDir)
       try lock.lock()
 
+      let sourceState = try sourceVM.state()
       let generateMAC = try localStorage.hasVMsWithMACAddress(macAddress: sourceVM.macAddress())
-        && sourceVM.state() != .Suspended
-      try sourceVM.clone(to: tmpVMDir, generateMAC: generateMAC)
+        && sourceState != .Suspended
+
+      if stacked {
+        guard sourceVM.isStandalone else {
+          throw ValidationError("--stacked cannot use an image that already has a stacked disk")
+        }
+        guard try VMConfig(fromURL: sourceVM.configURL).os == .darwin else {
+          throw ValidationError("--stacked currently supports only macOS images")
+        }
+        try sourceVM.cloneAsStackedBase(to: tmpVMDir, generateMAC: generateMAC)
+      } else if sourceVM.isStackedCachedImage {
+        try sourceVM.cloneStacked(to: tmpVMDir, copyWritableOverlay: false, generateMAC: generateMAC)
+      } else if sourceVM.isStackedVM {
+        guard sourceState == .Stopped else {
+          throw RuntimeError.VMConfigurationError("VM \"\(sourceName)\" must be stopped before cloning")
+        }
+        try sourceVM.cloneStacked(to: tmpVMDir, copyWritableOverlay: true, generateMAC: generateMAC)
+      } else {
+        try sourceVM.clone(to: tmpVMDir, generateMAC: generateMAC)
+      }
 
       try localStorage.move(newName, from: tmpVMDir)
 
@@ -75,12 +129,26 @@ struct Clone: AsyncParsableCommand {
       // is not actually claiming new space until the VM is started and it writes something to disk.
       //
       // So, once we clone the VM let's try to claim the rest of space for the VM to run without errors.
-      let unallocatedBytes = try sourceVM.sizeBytes() - sourceVM.allocatedSizeBytes()
-      if unallocatedBytes > 0 {
-        try Prune.reclaimIfNeeded(UInt64(unallocatedBytes), sourceVM)
+      if sourceVM.isStandalone {
+        let unallocatedBytes = try sourceVM.sizeBytes() - sourceVM.allocatedSizeBytes()
+        // Avoid reclaiming an excessive amount of disk space.
+        let reclaimBytes = min(unallocatedBytes, Int(pruneLimit) * 1024 * 1024 * 1024)
+        if reclaimBytes > 0 {
+          try Prune.reclaimIfNeeded(UInt64(reclaimBytes), sourceVM)
+        }
+      } else if sourceVM.isStackedVM || sourceVM.isStackedCachedImage {
+        let clonedVM = try localStorage.open(newName)
+        // A stacked clone owns only its writable overlay locally, but that
+        // overlay may grow to the full guest-visible disk block layout at
+        // runtime. Reclaim against the clone so it is not pruned itself.
+        let unallocatedBytes = try clonedVM.diskSizeBytes() - clonedVM.allocatedSizeBytes()
+        let reclaimBytes = min(unallocatedBytes, Int(pruneLimit) * 1024 * 1024 * 1024)
+        if reclaimBytes > 0 {
+          try Prune.reclaimIfNeeded(UInt64(reclaimBytes), clonedVM)
+        }
       }
     }, onCancel: {
-      try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+      try? tmpVMDir.removeFromDisk()
     })
   }
 }

Sources/tart/Commands/Exec.swift

@@ -1,6 +1,5 @@
 import ArgumentParser
 import Foundation
-import NIOPosix
 import GRPC
 import Cirruslabs_TartGuestAgent_Grpc_Swift
 
@@ -41,19 +40,12 @@ struct Exec: AsyncParsableCommand {
       throw RuntimeError.VMNotRunning(name)
     }
 
-    // Create a gRPC channel connected to the VM's control socket
-    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
-    defer {
-      try! group.syncShutdownGracefully()
-    }
-
-    let channel = try GRPCChannelPool.with(
-      target: .unixDomainSocket(vmDir.controlSocketURL.path()),
-      transportSecurity: .plaintext,
-      eventLoopGroup: group,
-    )
-    defer {
-      try! channel.close().wait()
+    // Change the current working directory to a VM's base directory
+    // to work around Unix domain socket 104 byte limitation [1]
+    //
+    // [1]: https://blog.8-p.info/en/2020/06/11/unix-domain-socket-length/
+    if let baseURL = vmDir.controlSocketURL.baseURL {
+      FileManager.default.changeCurrentDirectoryPath(baseURL.path())
     }
 
     // Switch controlling terminal into raw mode when remote pseudo-terminal is requested
@@ -71,7 +63,10 @@ struct Exec: AsyncParsableCommand {
 
     // Execute a command in a running VM
     do {
-      try await execute(channel)
+      let controlSocketPath = vmDir.controlSocketURL.relativePath
+      try await withGuestAgentChannel(unixDomainSocketPath: controlSocketPath) { channel in
+        try await execute(channel)
+      }
     } catch let error as GRPCConnectionPoolError {
       throw RuntimeError.Generic("Failed to connect to the VM using its control socket: \(error.localizedDescription), is the Tart Guest Agent running?")
     }
@@ -87,11 +82,13 @@ struct Exec: AsyncParsableCommand {
         $0.args = Array(command.dropFirst(1))
         $0.interactive = interactive
         $0.tty = tty
-        $0.terminalSize = .with {
-          let (width, height) = try! Term.GetSize()
+        if tty {
+          $0.terminalSize = .with {
+            let (width, height) = try! Term.GetSize()
 
-          $0.cols = UInt32(width)
-          $0.rows = UInt32(height)
+            $0.cols = UInt32(width)
+            $0.rows = UInt32(height)
+          }
         }
       })
     })
@@ -132,6 +129,11 @@ struct Exec: AsyncParsableCommand {
               let data = handle.availableData
 
               if data.isEmpty {
+                // EOF: unregister the handler, otherwise the fd stays permanently
+                // "readable" and Foundation re-invokes us in a tight loop, burning
+                // 100% of a core for the rest of the command's lifetime
+                handle.readabilityHandler = nil
+
                 continuation.finish()
               } else {
                 continuation.yield(data)

Sources/tart/Commands/Get.swift

@@ -5,9 +5,9 @@ fileprivate struct VMInfo: Encodable {
   let OS: OS
   let CPU: Int
   let Memory: UInt64
-  let Disk: Int
+  let Disk: HumanReadableByteCount
   let DiskFormat: String
-  let Size: String
+  let Size: HumanReadableByteCount
   let Display: String
   let Running: Bool
   let State: String
@@ -27,7 +27,19 @@ struct Get: AsyncParsableCommand {
     let vmConfig = try VMConfig(fromURL: vmDir.configURL)
     let memorySizeInMb = vmConfig.memorySize / 1024 / 1024
 
-    let info = VMInfo(OS: vmConfig.os, CPU: vmConfig.cpuCount, Memory: memorySizeInMb, Disk: try vmDir.sizeGB(), DiskFormat: vmConfig.diskFormat.rawValue, Size: String(format: "%.3f", Float(try vmDir.allocatedSizeBytes()) / 1000 / 1000 / 1000), Display: vmConfig.display.description, Running: try vmDir.running(), State: try vmDir.state().rawValue)
+    let info = VMInfo(
+      OS: vmConfig.os,
+      CPU: vmConfig.cpuCount,
+      Memory: memorySizeInMb,
+      Disk: HumanReadableByteCount(try vmDir.diskSizeBytes()) { $0 / 1000 / 1000 / 1000 },
+      DiskFormat: vmConfig.diskFormat.rawValue,
+      Size: HumanReadableByteCount(try vmDir.allocatedSizeBytes()) {
+        String(format: "%.3f", Float($0) / 1000 / 1000 / 1000)
+      },
+      Display: vmConfig.display.description,
+      Running: try vmDir.running(),
+      State: try vmDir.state().rawValue
+    )
     print(format.renderSingle(info))
   }
 }

Sources/tart/Commands/IP.swift

@@ -2,7 +2,6 @@ import ArgumentParser
 import Foundation
 import Network
 import SystemConfiguration
-import Sentry
 
 enum IPResolutionStrategy: String, ExpressibleByArgument, CaseIterable {
   case dhcp, arp, agent
@@ -69,7 +68,15 @@ struct IP: AsyncParsableCommand {
           throw RuntimeError.Generic("Cannot perform IP resolution via Tart Guest Agent when control socket URL is not set")
         }
 
-        if let ip = try await AgentResolver.ResolveIP(controlSocketURL) {
+        // Change the current working directory to a VM's base directory
+        // to work around Unix domain socket 104 byte limitation [1]
+        //
+        // [1]: https://blog.8-p.info/en/2020/06/11/unix-domain-socket-length/
+        if let baseURL = controlSocketURL.baseURL {
+          FileManager.default.changeCurrentDirectoryPath(baseURL.path())
+        }
+
+        if let ip = try await AgentResolver.ResolveIP(controlSocketURL.relativePath) {
           return ip
         }
       }

Sources/tart/Commands/Import.swift

@@ -17,10 +17,13 @@ struct Import: AsyncParsableCommand {
   }
 
   func run() async throws {
-    let localStorage = VMStorageLocal()
+    let localStorage = try VMStorageLocal()
 
     // Create a temporary VM directory to which we will load the export file
     let tmpVMDir = try VMDirectory.temporary()
+    defer {
+      try? tmpVMDir.removeFromDisk()
+    }
 
     // Lock the temporary VM directory to prevent it's garbage collection
     // while we're running
@@ -30,6 +33,9 @@ struct Import: AsyncParsableCommand {
     // Populate the temporary VM directory with the export file contents
     print("importing...")
     try tmpVMDir.importFromArchive(path: path)
+    guard tmpVMDir.initialized else {
+      throw RuntimeError.ImportFailed("archive does not contain a runnable VM")
+    }
 
     try await withTaskCancellationHandler(operation: {
       // Acquire a global lock
@@ -45,7 +51,7 @@ struct Import: AsyncParsableCommand {
 
       try lock.unlock()
     }, onCancel: {
-      try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+      try? tmpVMDir.removeFromDisk()
     })
   }
 }

Sources/tart/Commands/List.swift

@@ -5,9 +5,9 @@ import SwiftUI
 fileprivate struct VMInfo: Encodable {
   let Source: String
   let Name: String
-  let Disk: Int
-  let Size: Int
-  let SizeOnDisk: Int
+  let Disk: HumanReadableByteCount
+  let Size: HumanReadableByteCount
+  let Accessed: String
   let Running: Bool
   let State: String
 }
@@ -39,13 +39,29 @@ struct List: AsyncParsableCommand {
 
     if source == nil || source == "local" {
       infos += sortedInfos(try VMStorageLocal().list().map { (name, vmDir) in
-        try VMInfo(Source: "local", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), SizeOnDisk: vmDir.allocatedSizeGB() - vmDir.deduplicatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue)
+        try VMInfo(
+          Source: "local",
+          Name: name,
+          Disk: HumanReadableByteCount(try vmDir.diskSizeBytes()) { $0 / 1000 / 1000 / 1000 },
+          Size: HumanReadableByteCount(try vmDir.allocatedSizeBytes()) { $0 / 1000 / 1000 / 1000 },
+          Accessed: formatAccessDate(try vmDir.accessDate()),
+          Running: vmDir.running(),
+          State: vmDir.state().rawValue
+        )
       })
     }
 
     if source == nil || source == "oci" {
       infos += sortedInfos(try VMStorageOCI().list().map { (name, vmDir, _) in
-        try VMInfo(Source: "OCI", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), SizeOnDisk: vmDir.allocatedSizeGB() - vmDir.deduplicatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue)
+        try VMInfo(
+          Source: "OCI",
+          Name: name,
+          Disk: HumanReadableByteCount(try vmDir.diskSizeBytes()) { $0 / 1000 / 1000 / 1000 },
+          Size: HumanReadableByteCount(try vmDir.allocatedSizeBytes()) { $0 / 1000 / 1000 / 1000 },
+          Accessed: formatAccessDate(try vmDir.accessDate()),
+          Running: vmDir.running(),
+          State: vmDir.state().rawValue
+        )
       })
     }
 
@@ -61,4 +77,16 @@ struct List: AsyncParsableCommand {
   private func sortedInfos(_ infos: [VMInfo]) -> [VMInfo] {
     infos.sorted(by: { left, right in left.Name < right.Name })
   }
+
+  private func formatAccessDate(_ accessDate: Date) -> String {
+    switch format {
+    case .text:
+      let formatter = RelativeDateTimeFormatter()
+      formatter.unitsStyle = .full
+      return formatter.localizedString(for: accessDate, relativeTo: Date())
+    case .json:
+      let formatter = ISO8601DateFormatter()
+      return formatter.string(from: accessDate)
+    }
+  }
 }

Sources/tart/Commands/Login.swift

@@ -64,6 +64,8 @@ struct Login: AsyncParsableCommand {
 }
 
 fileprivate class DictionaryCredentialsProvider: CredentialsProvider {
+  let userFriendlyName = "static dictionary credentials provider"
+
   var credentials: Dictionary<String, (String, String)>
 
   init(_ credentials: Dictionary<String, (String, String)>) {

Sources/tart/Commands/Prune.swift

@@ -1,6 +1,6 @@
 import ArgumentParser
 import Dispatch
-import Sentry
+import OpenTelemetryApi
 import SwiftUI
 import SwiftDate
 
@@ -53,9 +53,9 @@ struct Prune: AsyncParsableCommand {
 
     switch entries {
     case "caches":
-      prunableStorages = [VMStorageOCI(), try IPSWCache()]
+      prunableStorages = [try VMStorageOCI(), try IPSWCache()]
     case "vms":
-      prunableStorages = [VMStorageLocal()]
+      prunableStorages = [try VMStorageLocal()]
     default:
       throw ValidationError("unsupported --entries value, please specify either \"caches\" or \"vms\"")
     }
@@ -81,27 +81,34 @@ struct Prune: AsyncParsableCommand {
   }
 
   static func pruneSpaceBudget(prunableStorages: [PrunableStorage], spaceBudgetBytes: UInt64) throws {
-    let prunables: [Prunable] = try prunableStorages
-      .flatMap { try $0.prunables() }
-      .sorted { try $0.accessDate() > $1.accessDate() }
+    while true {
+      let prunables: [Prunable] = try prunableStorages
+        .flatMap { try $0.prunables() }
+        .sorted { try $0.accessDate() > $1.accessDate() }
 
-    var spaceBudgetBytes = spaceBudgetBytes
-    var prunablesToDelete: [Prunable] = []
+      var remainingBudgetBytes = spaceBudgetBytes
+      var prunableToDelete: Prunable?
 
-    for prunable in prunables {
-      let prunableSizeBytes = UInt64(try prunable.allocatedSizeBytes())
+      for prunable in prunables {
+        let prunableSizeBytes = UInt64(try prunable.allocatedSizeBytes())
 
-      if prunableSizeBytes <= spaceBudgetBytes {
-        // Don't mark for deletion as
-        // there's a budget available
-        spaceBudgetBytes -= prunableSizeBytes
-      } else {
-        // Mark for deletion
-        prunablesToDelete.append(prunable)
+        if prunableSizeBytes <= remainingBudgetBytes {
+          // Don't mark for deletion as there is budget available
+          remainingBudgetBytes -= prunableSizeBytes
+        } else {
+          prunableToDelete = prunable
+          break
+        }
       }
-    }
 
-    try prunablesToDelete.forEach { try $0.delete() }
+      guard let prunableToDelete else {
+        return
+      }
+
+      // Deleting one cached stacked image can change which remaining image
+      // owns shared immutable content. Rebuild before choosing another.
+      try prunableToDelete.delete()
+    }
   }
 
   static func reclaimIfNeeded(_ requiredBytes: UInt64, _ initiator: Prunable? = nil) throws {
@@ -109,9 +116,10 @@ struct Prune: AsyncParsableCommand {
       return
     }
 
-    SentrySDK.configureScope { scope in
-      scope.setContext(value: ["requiredBytes": requiredBytes], key: "Prune")
-    }
+    OpenTelemetry.instance.contextProvider.activeSpan?.setAttribute(
+      key: "prune.required-bytes",
+      value: .int(Int(requiredBytes))
+    )
 
     // Figure out how much disk space is available
     let attrs = try Config().tartCacheDir.resourceValues(forKeys: [
@@ -123,18 +131,14 @@ struct Prune: AsyncParsableCommand {
       UInt64(attrs.volumeAvailableCapacityForImportantUsage!)
     )
 
-    SentrySDK.configureScope { scope in
-      scope.setContext(value: [
-        "volumeAvailableCapacity": attrs.volumeAvailableCapacity!,
-        "volumeAvailableCapacityForImportantUsage": attrs.volumeAvailableCapacityForImportantUsage!,
-        "volumeAvailableCapacityCalculated": volumeAvailableCapacityCalculated
-      ], key: "Prune")
-    }
+    OpenTelemetry.instance.contextProvider.activeSpan?.setAttributes([
+      "prune.volume-available-capacity-bytes": .int(Int(attrs.volumeAvailableCapacity!)),
+      "prune.volume-available-capacity-for-important-usage-bytes": .int(Int(attrs.volumeAvailableCapacityForImportantUsage!)),
+      "prune.volume-available-capacity-calculated": .int(Int(volumeAvailableCapacityCalculated)),
+    ])
 
     if volumeAvailableCapacityCalculated <= 0 {
-      SentrySDK.capture(message: "Zero volume capacity reported") { scope in
-        scope.setLevel(.warning)
-      }
+      OpenTelemetry.instance.contextProvider.activeSpan?.addEvent(name: "Zero volume capacity reported")
 
       return
     }
@@ -148,42 +152,51 @@ struct Prune: AsyncParsableCommand {
     try Prune.reclaimIfPossible(requiredBytes - volumeAvailableCapacityCalculated, initiator)
   }
 
-  private static func reclaimIfPossible(_ reclaimBytes: UInt64, _ initiator: Prunable? = nil) throws {
-    let transaction = SentrySDK.startTransaction(name: "Pruning cache", operation: "prune", bindToScope: true)
-    defer { transaction.finish() }
+  static func reclaimIfPossible(_ reclaimBytes: UInt64, _ initiator: Prunable? = nil) throws {
+    let span = OTel.shared.tracer.spanBuilder(spanName: "prune").startSpan()
+    defer { span.end() }
 
-    let prunableStorages: [PrunableStorage] = [VMStorageOCI(), try IPSWCache()]
-    let prunables: [Prunable] = try prunableStorages
-      .flatMap { try $0.prunables() }
-      .sorted { try $0.accessDate() < $1.accessDate() }
+    let prunableStorages: [PrunableStorage] = [try VMStorageOCI(), try IPSWCache()]
+    let prunables = {
+      try prunableStorages
+        .flatMap { try $0.prunables() }
+        .sorted { try $0.accessDate() < $1.accessDate() }
+    }
 
     // Does it even make sense to start?
-    let cacheUsedBytes = try prunables.map { try $0.allocatedSizeBytes() }.reduce(0, +)
-    if cacheUsedBytes < reclaimBytes {
+    let initialPrunables = try prunables()
+    let initialCacheUsedBytes = try initialPrunables.map { try $0.allocatedSizeBytes() }.reduce(0, +)
+    guard let reclaimBytes = Int(exactly: reclaimBytes), initialCacheUsedBytes >= reclaimBytes else {
       return
     }
 
-    var cacheReclaimedBytes: Int = 0
+    let targetCacheUsedBytes = initialCacheUsedBytes - reclaimBytes
+    var currentCacheUsedBytes = initialCacheUsedBytes
+    let initiatorPath = initiator.map {
+      $0.url.resolvingSymlinksInPath().standardizedFileURL.path
+    }
 
-    var it = prunables.makeIterator()
-
-    while cacheReclaimedBytes <= reclaimBytes {
-      guard let prunable = it.next() else {
+    while currentCacheUsedBytes > targetCacheUsedBytes {
+      // Deleting one cached stacked image can transfer ownership of shared
+      // immutable content to another record without reclaiming those bytes.
+      // Rebuild the candidates after every deletion so automatic pruning
+      // measures the cache that remains rather than a stale ownership snapshot.
+      guard let prunable = try prunables().first(where: {
+        $0.url.resolvingSymlinksInPath().standardizedFileURL.path != initiatorPath
+      }) else {
         break
       }
 
-      if prunable.url == initiator?.url.resolvingSymlinksInPath() {
-        // do not prune the initiator
-        continue
-      }
+      let allocatedSizeBytes = try prunable.allocatedSizeBytes()
 
-      try SentrySDK.span?.setData(value: prunable.allocatedSizeBytes(), key: prunable.url.path)
-
-      cacheReclaimedBytes += try prunable.allocatedSizeBytes()
+      OpenTelemetry.instance.contextProvider.activeSpan?
+        .addEvent(name: "Pruned \(allocatedSizeBytes) bytes for \(prunable.url.path)")
 
       try prunable.delete()
+      currentCacheUsedBytes = try prunables().map { try $0.allocatedSizeBytes() }.reduce(0, +)
     }
 
-    SentrySDK.span?.setMeasurement(name: "gc_disk_reclaimed", value: cacheReclaimedBytes as NSNumber, unit: MeasurementUnitInformation.byte);
+    OpenTelemetry.instance.contextProvider.activeSpan?
+      .addEvent(name: "Reclaimed \(initialCacheUsedBytes - currentCacheUsedBytes) bytes")
   }
 }

Sources/tart/Commands/Pull.swift

@@ -35,7 +35,7 @@ struct Pull: AsyncParsableCommand {
   func run() async throws {
     // Be more liberal when accepting local image as argument,
     // see https://github.com/cirruslabs/tart/issues/36
-    if VMStorageLocal().exists(remoteName) {
+    if try VMStorageLocal().exists(remoteName) {
       print("\"\(remoteName)\" is a local image, nothing to pull here!")
 
       return

Sources/tart/Commands/Push.swift

@@ -31,15 +31,12 @@ struct Push: AsyncParsableCommand {
                                                            discussion: "Can be specified multiple times to attach multiple labels."))
   var labels: [String] = []
 
-  @Option(help: .hidden)
-  var diskFormat: String = "v2"
-
   @Flag(help: ArgumentHelp("cache pushed images locally",
                            discussion: "Increases disk usage, but saves time if you're going to pull the pushed images later."))
   var populateCache: Bool = false
 
   func run() async throws {
-    let ociStorage = VMStorageOCI()
+    let ociStorage = try VMStorageOCI()
     let localVMDir = try VMStorageHelper.open(localName)
     let lock = try localVMDir.lock()
     if try !lock.trylock() {
@@ -72,7 +69,7 @@ struct Push: AsyncParsableCommand {
       let references = remoteNamesForRegistry.map{ $0.reference.value }
 
       let pushedRemoteName: RemoteName
-      // If we're pushing a local OCI VM, check if points to an already existing registry manifest
+      // If we're pushing a cached remote image, check if it points to an existing registry manifest
       // and if so, only upload manifests (without config, disk and NVRAM) to the user-specified references
       if let remoteName = try? RemoteName(localName) {
         pushedRemoteName = try await lightweightPushToRegistry(
@@ -81,18 +78,18 @@ struct Push: AsyncParsableCommand {
           references: references
         )
       } else {
-        pushedRemoteName = try await localVMDir.pushToRegistry(
+        let pushedImage = try await localVMDir.pushToRegistry(
           registry: registry,
           references: references,
           chunkSizeMb: chunkSize,
-          diskFormat: diskFormat,
           concurrency: concurrency,
           labels: parseLabels()
         )
+        pushedRemoteName = pushedImage.name
+
         // Populate the local cache (if requested)
         if populateCache {
-          let expectedPushedVMDir = try ociStorage.create(pushedRemoteName)
-          try localVMDir.clone(to: expectedPushedVMDir, generateMAC: false)
+          try ociStorage.populate(pushedImage.name, from: localVMDir, manifest: pushedImage.manifest)
         }
       }
 
@@ -106,7 +103,7 @@ struct Push: AsyncParsableCommand {
   }
 
   func lightweightPushToRegistry(registry: Registry, remoteName: RemoteName, references: [String]) async throws -> RemoteName {
-    // Is the local OCI VM already present in the registry?
+    // Is the cached remote image already present in the registry?
     let digest = try VMStorageOCI().digest(remoteName)
 
     let (remoteManifest, _) = try await registry.pullManifest(reference: digest)

Sources/tart/Commands/Rename.swift

@@ -17,7 +17,7 @@ struct Rename: AsyncParsableCommand {
   }
 
   func run() async throws {
-    let localStorage = VMStorageLocal()
+    let localStorage = try VMStorageLocal()
 
     if !localStorage.exists(name) {
       throw ValidationError("failed to rename a non-existent local VM: \(name)")

Sources/tart/Commands/Run.swift

@@ -4,7 +4,7 @@ import Darwin
 import Dispatch
 import SwiftUI
 import Virtualization
-import Sentry
+import OpenTelemetryApi
 import System
 
 var vm: VM?
@@ -134,11 +134,12 @@ struct Run: AsyncParsableCommand {
 
   Learn how to create a disk image using Disk Utility here: https://support.apple.com/en-gb/guide/disk-utility/dskutl11888/mac
 
-  To work with block devices, the easiest way is to modify their permissions (e.g. by using "sudo chown $USER /dev/diskX") or to run the Tart binary as root, which affects locating Tart VMs.
+  To work with block devices, the easiest way is to modify their permissions to be accessible to the current user:
 
-  To work around this pass TART_HOME explicitly:
+  sudo chown $USER /dev/diskX
+  tart run macos --disk=/dev/diskX
 
-  sudo TART_HOME="$HOME/.tart" tart run sequoia --disk=/dev/disk0
+  Warning: after running the chown command above, all software running under the current user will be able to access /dev/diskX. If that violates your threat model, we recommend avoiding mounting block devices altogether.
   """, valueName: "path[:options]"), completion: .file())
   var disk: [String] = []
 
@@ -201,15 +202,35 @@ struct Run: AsyncParsableCommand {
                            """))
   var netSoftnet: Bool = false
 
-  @Option(help: ArgumentHelp("Comma-separated list of CIDRs to allow the traffic to when using Softnet isolation\n(e.g. --net-softnet-allow=192.168.0.0/24)", discussion: """
+  @Option(help: ArgumentHelp("Comma-separated list of CIDRs to allow the traffic to when using Softnet isolation (e.g. --net-softnet-allow=192.168.0.0/24)", discussion: """
   This option allows you bypass the private IPv4 address space restrictions imposed by --net-softnet.
 
-  For example, you can allow the VM to communicate with the local network with e.g. --net-softnet-allow=10.0.0.0/16 or to completely disable the destination based restrictions with --net-softnet-allow=0.0.0.0/0.
+  For example, you can allow the VM to communicate with the local network with e.g. --net-softnet-allow=10.0.0.0/16 or with --net-softnet-allow=0.0.0.0/0 to completely disable the destination based restrictions, including VMs bridge isolation.
+
+  When used with --net-softnet-block, the longest prefix match always wins. In case the same prefix is both allowed and blocked, blocking takes precedence.
 
   Implies --net-softnet.
   """, valueName: "comma-separated CIDRs"))
   var netSoftnetAllow: String?
 
+  @Option(help: ArgumentHelp("Comma-separated list of CIDRs to block the traffic to when using Softnet isolation (e.g. --net-softnet-block=66.66.0.0/16)", discussion: """
+  This option allows you to tighten the IPv4 address space restrictions imposed by --net-softnet even further.
+
+  For example --net-softnet-block=0.0.0.0/0 may be used to establish a default deny policy that is further relaxed with --net-softnet-allow.
+
+  When used with --net-softnet-allow, the longest prefix match always wins. In case the same prefix is both allowed and blocked, blocking takes precedence.
+
+  Implies --net-softnet.
+  """, valueName: "comma-separated CIDRs"))
+  var netSoftnetBlock: String?
+
+  @Option(help: ArgumentHelp("Connected Unix stream socket file descriptor to use for the Softnet control channel (e.g. --net-softnet-control-fd=3)", discussion: """
+  This option enables the Softnet control channel on an inherited Unix stream socket. It can be used to dynamically replace Softnet allow and block lists while the VM is running.
+
+  The file descriptor must be greater than 2. Implies --net-softnet.
+  """, valueName: "file descriptor"))
+  var netSoftnetControlFd: Int32?
+
   @Option(help: ArgumentHelp("Comma-separated list of TCP ports to expose (e.g. --net-softnet-expose 2222:22,8080:80)", discussion: """
   Options are comma-separated and are as follows:
 
@@ -265,13 +286,41 @@ struct Run: AsyncParsableCommand {
   #endif
   var noTrackpad: Bool = false
 
+  @Flag(help: ArgumentHelp("Disable the pointer"))
+  var noPointer: Bool = false
+
+  @Flag(help: ArgumentHelp("Disable the keyboard"))
+  var noKeyboard: Bool = false
+
+  #if arch(arm64) && compiler(>=6.4)
+    @Option(help: ArgumentHelp("Provision a macOS guest on first boot using the guest provisioning API", discussion: """
+    Takes a comma-separated list of key=value pairs that configure the initial setup of a macOS guest
+
+    Requires the host to be running macOS 27 (or newer) and only takes effect on the first boot after
+    creation of a macOS 27 (or newer) guest VM.
+
+    Supported keys (matching VZMacGuestProvisioningOptions):
+
+    * fullName=<NAME> — the person's full name to configure
+
+    * username=<USERNAME> — the username for logging into the guest
+
+    * password=<PASSWORD> — the password to configure for the guest
+
+    * logsInAutomatically=true|false — whether to automatically log the person in at startup
+
+    * enablesRemoteLogin=true|false — whether to enable Remote Login (SSH) in the guest
+    """, valueName: "key=value,..."))
+    var provisioningOpts: String?
+  #endif
+
   mutating func validate() throws {
     if vnc && vncExperimental {
       throw ValidationError("--vnc and --vnc-experimental are mutually exclusive")
     }
 
     // Automatically enable --net-softnet when any of its related options are specified
-    if netSoftnetAllow != nil || netSoftnetExpose != nil {
+    if netSoftnetAllow != nil || netSoftnetBlock != nil || netSoftnetExpose != nil || netSoftnetControlFd != nil {
       netSoftnet = true
     }
 
@@ -301,7 +350,7 @@ struct Run: AsyncParsableCommand {
       }
     }
 
-    let localStorage = VMStorageLocal()
+    let localStorage = try VMStorageLocal()
     let vmDir = try localStorage.open(name)
     if try vmDir.state() == .Suspended {
       suspendable = true
@@ -316,8 +365,15 @@ struct Run: AsyncParsableCommand {
       if noTrackpad {
         throw ValidationError("--no-trackpad cannot be used with --suspendable")
       }
+      if noKeyboard {
+        throw ValidationError("--no-keyboard cannot be used with --suspendable")
+      }
+      if noPointer {
+        throw ValidationError("--no-pointer cannot be used with --suspendable")
+      }
     }
 
+
     if noTrackpad {
       let config = try VMConfig.init(fromURL: vmDir.configURL)
       if config.os != .darwin {
@@ -325,6 +381,19 @@ struct Run: AsyncParsableCommand {
       }
     }
 
+    #if arch(arm64) && compiler(>=6.4)
+      if provisioningOpts != nil {
+        if #unavailable(macOS 27) {
+          throw ValidationError("--provisioning-opts requires the host to be running macOS 27 (or newer)")
+        }
+
+        let config = try VMConfig.init(fromURL: vmDir.configURL)
+        if config.os != .darwin {
+          throw ValidationError("--provisioning-opts can only be used with macOS VMs")
+        }
+      }
+    #endif
+
     for disk in disk {
       if disk.hasSuffix("-amd64.iso") {
         throw ValidationError("Seems you have a disk targeting x86 architecture (hence amd64 in the name). Please use an 'arm64' version of the disk.")
@@ -333,8 +402,8 @@ struct Run: AsyncParsableCommand {
   }
 
   @MainActor
-  func run() async throws {
-    let localStorage = VMStorageLocal()
+  func runOnMainThread() throws {
+    let localStorage = try VMStorageLocal()
     let vmDir = try localStorage.open(name)
 
     // Validate disk format support
@@ -381,10 +450,20 @@ struct Run: AsyncParsableCommand {
     // Parse root disk options
     let diskOptions = DiskOptions(rootDiskOpts)
 
+    // Parse guest provisioning options
+    #if arch(arm64) && compiler(>=6.4)
+      let provisioning = try provisioningOpts.map { try GuestProvisioningOptions($0) }
+    #endif
+
+    // Keep these values alive while the VM runs. Some additional disks own a
+    // lock that protects their temporary backing files from Config.gc().
+    let additionalDisks = try additionalDisks()
+    defer { withExtendedLifetime(additionalDisks) {} }
+
     vm = try VM(
       vmDir: vmDir,
       network: userSpecifiedNetwork(vmDir: vmDir) ?? NetworkShared(),
-      additionalStorageDevices: try additionalDiskAttachments(),
+      additionalStorageDevices: additionalDisks.map(\.configuration),
       directorySharingDevices: directoryShares() + rosettaDirectoryShare(),
       serialPorts: serialPorts,
       suspendable: suspendable,
@@ -393,7 +472,9 @@ struct Run: AsyncParsableCommand {
       clipboard: !noClipboard,
       sync: VZDiskImageSynchronizationMode(diskOptions.syncModeRaw),
       caching: VZDiskImageCachingMode(diskOptions.cachingModeRaw),
-      noTrackpad: noTrackpad
+      noTrackpad: noTrackpad,
+      noPointer: noPointer,
+      noKeyboard: noKeyboard
     )
 
     let vncImpl: VNC? = try {
@@ -444,7 +525,11 @@ struct Run: AsyncParsableCommand {
         #endif
 
         do {
-          try await vm!.start(recovery: recovery, resume: resume)
+          #if arch(arm64) && compiler(>=6.4)
+            try await vm!.start(recovery: recovery, resume: resume, provisioning: provisioning)
+          #else
+            try await vm!.start(recovery: recovery, resume: resume)
+          #endif
         } catch let error as VZError {
           if error.code == .virtualMachineLimitExceeded {
             var hint = ""
@@ -485,8 +570,10 @@ struct Run: AsyncParsableCommand {
         }
 
         if #available(macOS 14, *) {
-          Task {
-            try await ControlSocket(vmDir.controlSocketURL).run()
+          let controlSocket = try await ControlSocket(vmDir.controlSocketURL)
+
+          ErrorReportingTask("Failed to run control socket") {
+            try await controlSocket.run()
           }
         }
 
@@ -496,14 +583,15 @@ struct Run: AsyncParsableCommand {
           try vncImpl.stop()
         }
 
+        OTel.shared.flush()
         Foundation.exit(0)
       } catch {
-        // Capture the error into Sentry
-        SentrySDK.capture(error: error)
-        SentrySDK.flush(timeout: 2.seconds.timeInterval)
+        // Capture the error into OpenTelemetry
+        OpenTelemetry.instance.contextProvider.activeSpan?.recordException(error)
 
         fputs("\(error)\n", stderr)
 
+        OTel.shared.flush()
         Foundation.exit(1)
       }
     }
@@ -537,12 +625,14 @@ struct Run: AsyncParsableCommand {
             } else {
               print(RuntimeError.SuspendFailed("this functionality is only supported on macOS 14 (Sonoma) or newer"))
 
+              OTel.shared.flush()
               Foundation.exit(1)
             }
           #endif
         } catch (let e) {
           print(RuntimeError.SuspendFailed(e.localizedDescription))
 
+          OTel.shared.flush()
           Foundation.exit(1)
         }
       }
@@ -554,7 +644,7 @@ struct Run: AsyncParsableCommand {
     signal(SIGUSR2, SIG_IGN)
     let sigusr2Src = DispatchSource.makeSignalSource(signal: SIGUSR2)
     sigusr2Src.setEventHandler {
-      Task {
+      ErrorReportingTask("Failed to request guest OS to stop") {
         print("Requesting guest OS to stop...")
         try vm!.virtualMachine.requestStop()
       }
@@ -594,6 +684,10 @@ struct Run: AsyncParsableCommand {
       softnetExtraArguments += ["--allow", netSoftnetAllow]
     }
 
+    if let netSoftnetBlock = netSoftnetBlock {
+      softnetExtraArguments += ["--block", netSoftnetBlock]
+    }
+
     if let netSoftnetExpose = netSoftnetExpose {
       softnetExtraArguments += ["--expose", netSoftnetExpose]
     }
@@ -601,13 +695,13 @@ struct Run: AsyncParsableCommand {
     if netSoftnet {
       let config = try VMConfig.init(fromURL: vmDir.configURL)
 
-      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: softnetExtraArguments)
+      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: softnetExtraArguments, controlFD: netSoftnetControlFd)
     }
 
     if netHost {
       let config = try VMConfig.init(fromURL: vmDir.configURL)
 
-      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: ["--vm-net-type", "host"] + softnetExtraArguments)
+      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: ["--vm-net-type", "host"] + softnetExtraArguments, controlFD: netSoftnetControlFd)
     }
 
     if netBridged.count > 0 {
@@ -640,9 +734,9 @@ struct Run: AsyncParsableCommand {
     }
   }
 
-  func additionalDiskAttachments() throws -> [VZStorageDeviceConfiguration] {
+  func additionalDisks() throws -> [AdditionalDisk] {
     try disk.map {
-      try AdditionalDisk(parseFrom: $0).configuration
+      try AdditionalDisk(parseFrom: $0)
     }
   }
 
@@ -722,6 +816,11 @@ struct Run: AsyncParsableCommand {
   }
 }
 
+// "tart run" drives an AppKit/SwiftUI run loop and therefore must own the main
+// thread at the top level, so it opts out of Root's asynchronous command path.
+// See Root.main() for the rationale.
+extension Run: MainThreadCommand {}
+
 struct MainApp: App {
   static var suspendable: Bool = false
   static var capturesSystemKeys: Bool = false
@@ -762,13 +861,13 @@ struct MainApp: App {
       CommandGroup(replacing: .appInfo) { AboutTart(config: vm!.config) }
       CommandMenu("Control") {
         Button("Start") {
-          Task { try await vm!.virtualMachine.start() }
+          ErrorReportingTask("Failed to start VM") { try await vm!.virtualMachine.start() }
         }
         Button("Stop") {
-          Task { try await vm!.virtualMachine.stop() }
+          ErrorReportingTask("Failed to stop VM") { try await vm!.virtualMachine.stop() }
         }
         Button("Request Stop") {
-          Task { try vm!.virtualMachine.requestStop() }
+          ErrorReportingTask("Failed to request VM stop") { try vm!.virtualMachine.requestStop() }
         }
         if #available(macOS 14, *) {
           if (MainApp.suspendable) {
@@ -783,6 +882,12 @@ struct MainApp: App {
 }
 
 class AppDelegate: NSObject, NSApplicationDelegate, ObservableObject {
+  func applicationDidFinishLaunching(_ : Notification) {
+    let nsApp = NSApplication.shared
+    nsApp.setActivationPolicy(.regular)
+    nsApp.activate(ignoringOtherApps: true)
+  }
+
   func applicationShouldTerminate(_ sender: NSApplication) -> NSApplication.TerminateReply {
     if (kill(getpid(), MainApp.suspendable ? SIGUSR1 : SIGINT) == 0) {
       return .terminateLater
@@ -854,14 +959,32 @@ struct VMView: NSViewRepresentable {
 
 struct AdditionalDisk {
   let configuration: VZStorageDeviceConfiguration
+  // Retained for as long as the additional disk is attached, so Config.gc()
+  // cannot remove a temporary backing file or stacked-disk directory.
+  private let temporaryDiskLock: FileLock?
 
   init(parseFrom: String) throws {
     let (diskPath, readOnly, syncModeRaw, cachingModeRaw) = Self.parseOptions(parseFrom)
 
-    self.configuration = try Self.craft(diskPath, readOnly: readOnly, syncModeRaw: syncModeRaw, cachingModeRaw: cachingModeRaw)
+    self = try Self.craft(
+      diskPath,
+      readOnly: readOnly,
+      syncModeRaw: syncModeRaw,
+      cachingModeRaw: cachingModeRaw
+    )
   }
 
-  static func craft(_ diskPath: String, readOnly diskReadOnly: Bool, syncModeRaw: String, cachingModeRaw: String) throws -> VZStorageDeviceConfiguration {
+  private init(configuration: VZStorageDeviceConfiguration, temporaryDiskLock: FileLock? = nil) {
+    self.configuration = configuration
+    self.temporaryDiskLock = temporaryDiskLock
+  }
+
+  private static func craft(
+    _ diskPath: String,
+    readOnly diskReadOnly: Bool,
+    syncModeRaw: String,
+    cachingModeRaw: String
+  ) throws -> AdditionalDisk {
     let diskURL = URL(string: diskPath)
 
     if (["nbd", "nbds", "nbd+unix", "nbds+unix"].contains(diskURL?.scheme)) {
@@ -876,7 +999,7 @@ struct AdditionalDisk {
         synchronizationMode: try VZDiskSynchronizationMode(syncModeRaw)
       )
 
-      return VZVirtioBlockDeviceConfiguration(attachment: nbdAttachment)
+      return AdditionalDisk(configuration: VZVirtioBlockDeviceConfiguration(attachment: nbdAttachment))
     }
 
     // Expand the tilde (~) since at this point we're dealing with a local path,
@@ -907,13 +1030,37 @@ struct AdditionalDisk {
       let blockAttachment = try VZDiskBlockDeviceStorageDeviceAttachment(fileHandle: FileHandle(fileDescriptor: fd, closeOnDealloc: true),
                                                                          readOnly: diskReadOnly, synchronizationMode: try VZDiskSynchronizationMode(syncModeRaw))
 
-      return VZVirtioBlockDeviceConfiguration(attachment: blockAttachment)
+      return AdditionalDisk(configuration: VZVirtioBlockDeviceConfiguration(attachment: blockAttachment))
     }
 
     // Support remote VM names in --disk command-line argument
     if let remoteName = try? RemoteName(diskPath) {
       let vmDir = try VMStorageOCI().open(remoteName)
 
+      if vmDir.isStackedCachedImage {
+        // A cached stacked image has no writable top overlay. Create one in a
+        // disposable directory for this additional-disk attachment.
+        let temporaryVMDir = try VMDirectory.temporary()
+        let temporaryVMDirLock = try FileLock(lockURL: temporaryVMDir.baseURL)
+        try temporaryVMDirLock.lock()
+        try vmDir.cloneStacked(
+          to: temporaryVMDir,
+          copyWritableOverlay: false,
+          generateMAC: false
+        )
+        let stack = try temporaryVMDir.diskImageStack()
+        let attachment = try stack.makeAttachment(
+          readOnly: diskReadOnly,
+          cachingMode: try VZDiskImageCachingMode(cachingModeRaw) ?? .automatic,
+          synchronizationMode: try VZDiskImageSynchronizationMode(syncModeRaw)
+        )
+
+        return AdditionalDisk(
+          configuration: VZVirtioBlockDeviceConfiguration(attachment: attachment),
+          temporaryDiskLock: temporaryVMDirLock
+        )
+      }
+
       // Unfortunately, VZDiskImageStorageDeviceAttachment does not support
       // FileHandle, so we can't easily clone the disk, open it and unlink(2)
       // to simplify the garbage collection, so use an intermediate directory.
@@ -926,7 +1073,7 @@ struct AdditionalDisk {
 
       let diskImageAttachment = try VZDiskImageStorageDeviceAttachment(url: clonedDiskURL, readOnly: diskReadOnly)
 
-      return VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment)
+      return AdditionalDisk(configuration: VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment), temporaryDiskLock: lock)
     }
 
     // Error out if the disk is locked by the host (e.g. it was mounted in Finder),
@@ -942,7 +1089,7 @@ struct AdditionalDisk {
       synchronizationMode: try VZDiskImageSynchronizationMode(syncModeRaw)
     )
 
-    return VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment)
+    return AdditionalDisk(configuration: VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment))
   }
 
   static func parseOptions(_ parseFrom: String) -> (String, Bool, String, String) {
@@ -984,6 +1131,81 @@ struct DiskOptions {
   }
 }
 
+struct GuestProvisioningOptions {
+  var fullName: String?
+  var username: String?
+  var password: String?
+  var logsInAutomatically: Bool?
+  var enablesRemoteLogin: Bool?
+
+  init(_ parseFrom: String) throws {
+    for pair in parseFrom.split(separator: ",") {
+      let keyValue = pair.split(separator: "=", maxSplits: 1)
+      guard keyValue.count == 2 else {
+        throw RuntimeError.VMConfigurationError("invalid provisioning option \"\(pair)\", expected key=value")
+      }
+
+      let key = String(keyValue[0])
+      let value = String(keyValue[1])
+
+      switch key {
+      case "fullName":
+        self.fullName = value
+      case "username":
+        self.username = value
+      case "password":
+        self.password = value
+      case "logsInAutomatically":
+        self.logsInAutomatically = try Self.parseBool(key, value)
+      case "enablesRemoteLogin":
+        self.enablesRemoteLogin = try Self.parseBool(key, value)
+      default:
+        throw RuntimeError.VMConfigurationError("unsupported provisioning option \"\(key)\"")
+      }
+    }
+  }
+
+  private static func parseBool(_ key: String, _ value: String) throws -> Bool {
+    switch value {
+    case "true":
+      return true
+    case "false":
+      return false
+    default:
+      throw RuntimeError.VMConfigurationError("invalid value \"\(value)\" for provisioning option \"\(key)\", expected \"true\" or \"false\"")
+    }
+  }
+}
+
+#if arch(arm64) && compiler(>=6.4)
+  @available(macOS 27, *)
+  extension GuestProvisioningOptions {
+    func toVZMacGuestProvisioningOptions() throws -> VZMacGuestProvisioningOptions {
+      let options = VZMacGuestProvisioningOptions()
+
+      if let fullName = fullName {
+        options.fullName = fullName
+      }
+      if let username = username {
+        options.username = username
+      }
+      if let password = password {
+        options.password = password
+      }
+      if let logsInAutomatically = logsInAutomatically {
+        options.logsInAutomatically = logsInAutomatically
+      }
+      if let enablesRemoteLogin = enablesRemoteLogin {
+        options.enablesRemoteLogin = enablesRemoteLogin
+      }
+
+      try options.validate()
+
+      return options
+    }
+  }
+#endif
+
 struct DirectoryShare {
   let name: String?
   let path: URL

Sources/tart/Commands/Set.swift

@@ -14,7 +14,7 @@ struct Set: AsyncParsableCommand {
   @Option(help: "VM memory size in megabytes")
   var memory: UInt64?
 
-  @Option(help: "VM display resolution in a format of <width>x<height>. For example, 1200x800")
+  @Option(help: "VM display resolution in a format of WIDTHxHEIGHT[pt|px]. For example, 1200x800, 1200x800pt or 1920x1080px. Units are treated as hints and default to \"pt\" (points) for macOS VMs and \"px\" (pixels) for Linux VMs when not specified.")
   var display: VMDisplayConfig?
 
   @Flag(inversion: .prefixedNo, help: ArgumentHelp("Whether to automatically reconfigure the VM's display to fit the window"))
@@ -39,6 +39,14 @@ struct Set: AsyncParsableCommand {
 
   func run() async throws {
     let vmDir = try VMStorageLocal().open(name)
+
+    // Replacing disk.img would leave a stacked VM with both disk.img and
+    // overlay.asif, which is not a supported local layout. Reject before
+    // saving any other requested configuration changes.
+    if disk != nil, vmDir.isStackedVM {
+      throw ValidationError("--disk is not supported for VMs with a stacked disk")
+    }
+
     var vmConfig = try VMConfig(fromURL: vmDir.configURL)
 
     if let cpu = cpu {
@@ -56,6 +64,7 @@ struct Set: AsyncParsableCommand {
       if (display.height > 0) {
         vmConfig.display.height = display.height
       }
+      vmConfig.display.unit = display.unit
     }
 
     vmConfig.displayRefit = displayRefit
@@ -88,12 +97,24 @@ struct Set: AsyncParsableCommand {
 
 extension VMDisplayConfig: ExpressibleByArgument {
   public init(argument: String) {
+    var argument = argument
+    var unit: Unit? = nil
+
+    if argument.hasSuffix(Unit.pixel.rawValue) {
+      argument = String(argument.dropLast(Unit.pixel.rawValue.count))
+      unit = Unit.pixel
+    } else if argument.hasSuffix(Unit.point.rawValue) {
+      argument = String(argument.dropLast(Unit.point.rawValue.count))
+      unit = Unit.point
+    }
+
     let parts = argument.components(separatedBy: "x").map {
       Int($0) ?? 0
     }
     self = VMDisplayConfig(
       width: parts[safe: 0] ?? 0,
-      height: parts[safe: 1] ?? 0
+      height: parts[safe: 1] ?? 0,
+      unit: unit,
     )
   }
 }

Sources/tart/Config.swift

@@ -9,7 +9,8 @@ struct Config {
     var tartHomeDir: URL
 
     if let customTartHome = ProcessInfo.processInfo.environment["TART_HOME"] {
-      tartHomeDir = URL(fileURLWithPath: customTartHome)
+      tartHomeDir = URL(fileURLWithPath: customTartHome, isDirectory: true)
+      try Self.validateTartHome(url: tartHomeDir)
     } else {
       tartHomeDir = FileManager.default
         .homeDirectoryForCurrentUser
@@ -32,7 +33,7 @@ struct Config {
         continue
       }
 
-      try FileManager.default.removeItem(at: entry)
+      try VMDirectory(baseURL: entry).removeFromDisk()
 
       try lock.unlock()
     }
@@ -49,4 +50,24 @@ struct Config {
   static func jsonDecoder() -> JSONDecoder {
     JSONDecoder()
   }
+
+  private static func validateTartHome(url: URL) throws {
+    let urlComponents = url.pathComponents
+
+    let descendingURLs = urlComponents.indices.map { i in
+      URL(fileURLWithPath: urlComponents[0...i].joined(separator: "/"))
+    }
+
+    for descendingURL in descendingURLs {
+      if FileManager.default.fileExists(atPath: descendingURL.path) {
+        continue
+      }
+
+      do {
+        try FileManager.default.createDirectory(at: descendingURL, withIntermediateDirectories: false)
+      } catch {
+        throw RuntimeError.Generic("TART_HOME is invalid: \(descendingURL.path) does not exist, yet we can't create it: \(error.localizedDescription)")
+      }
+    }
+  }
 }

Sources/tart/ContentStore.swift

@@ -0,0 +1,192 @@
+import Foundation
+
+enum ContentStoreError: Error, Equatable {
+  case invalidContentDigest(String)
+  case contentDigestMismatch(expected: String, actual: String)
+}
+
+/// Opaque content-addressed storage for immutable reconstructed files.
+///
+/// Stacked disks currently use it for complete base disks and published ASIF
+/// overlays reconstructed from Tart disk chunks. OCI blob digests may differ
+/// across registries, so the key is the full reconstructed-file digest.
+struct ContentStore {
+  private static let digestAlgorithm = "sha256"
+  private static let digestPrefix = "\(digestAlgorithm):"
+
+  let baseURL: URL
+  private let digestDirectoryURL: URL
+  private let pruneLockURL: URL
+
+  init() throws {
+    try self.init(baseURL: Config().tartCacheDir.appendingPathComponent("content", isDirectory: true))
+  }
+
+  init(baseURL: URL) throws {
+    self.baseURL = baseURL
+    self.digestDirectoryURL = baseURL.appendingPathComponent(Self.digestAlgorithm, isDirectory: true)
+    self.pruneLockURL = baseURL.appendingPathComponent(".gc.lock")
+    try FileManager.default.createDirectory(at: digestDirectoryURL, withIntermediateDirectories: true)
+    if !FileManager.default.fileExists(atPath: pruneLockURL.path) {
+      _ = FileManager.default.createFile(atPath: pruneLockURL.path, contents: Data())
+    }
+  }
+
+  /// Serializes reference publication with the final reference check and
+  /// deletion of immutable cache entries across Tart processes.
+  func withPruneLock<T>(_ body: () throws -> T) throws -> T {
+    let lock = try FileLock(lockURL: pruneLockURL)
+    try lock.lock()
+    defer { try? lock.unlock() }
+
+    return try body()
+  }
+
+  /// Waits for any prune already scanning references to finish. After this
+  /// returns, later prune runs can see a reference the caller already wrote.
+  func synchronizePublishedReferences() throws {
+    try withPruneLock {}
+  }
+
+  func contentURL(for contentDigest: String) throws -> URL {
+    try contentURL(for: contentDigest, under: baseURL)
+  }
+
+  /// Returns the canonical path for a digest under an arbitrary content-store
+  /// root without creating directories or lock files.
+  func contentURL(for contentDigest: String, under baseURL: URL) throws -> URL {
+    let digestHex = try validatedDigestHex(contentDigest)
+
+    return baseURL
+      .appendingPathComponent(Self.digestAlgorithm, isDirectory: true)
+      .appendingPathComponent(digestHex)
+  }
+
+  func temporaryContentURL(for contentDigest: String) throws -> URL {
+    let targetURL = try contentURL(for: contentDigest)
+
+    return targetURL.deletingLastPathComponent().appendingPathComponent(".\(UUID().uuidString).tmp")
+  }
+
+  /// Returns a stable staging path so an interrupted registry pull can resume
+  /// reconstructing this content entry on a later attempt.
+  func resumableContentURL(for contentDigest: String) throws -> URL {
+    let targetURL = try contentURL(for: contentDigest)
+
+    return targetURL.deletingLastPathComponent().appendingPathComponent(".\(targetURL.lastPathComponent).partial")
+  }
+
+  /// Returns a stable lock file for serializing reconstruction of one content
+  /// entry. The file is intentionally retained; flock state lives on the file
+  /// descriptor and disappears when the owning process exits.
+  func lockURL(for contentDigest: String) throws -> URL {
+    let targetURL = try contentURL(for: contentDigest)
+
+    let lockURL = targetURL.deletingLastPathComponent().appendingPathComponent(".\(targetURL.lastPathComponent).lock")
+    if !FileManager.default.fileExists(atPath: lockURL.path) {
+      _ = FileManager.default.createFile(atPath: lockURL.path, contents: nil)
+    }
+
+    return lockURL
+  }
+
+  /// Returns an immutable digest-addressed entry without rereading it. Files
+  /// are verified when installed and when deciding whether a pull is a cache
+  /// hit; normal clone/run/push paths trust the store like Tart's disk.img.
+  func contentURLIfPresent(for contentDigest: String) throws -> URL? {
+    let url = try contentURL(for: contentDigest)
+
+    guard FileManager.default.fileExists(atPath: url.path) else {
+      return nil
+    }
+
+    try url.updateAccessDate()
+
+    return url
+  }
+
+  /// Returns a validated cache hit. Corrupt files are treated as misses so a
+  /// later pull can safely rebuild them.
+  func existingContentURL(for contentDigest: String) throws -> URL? {
+    guard let url = try contentURLIfPresent(for: contentDigest) else {
+      return nil
+    }
+
+    guard try Digest.hash(url) == contentDigest else {
+      return nil
+    }
+
+    return url
+  }
+
+  /// Returns immutable content files that no retained cached image or local VM
+  /// references. Callers may prune these like other cache entries.
+  func prunables(excluding referencedContentDigests: Swift.Set<String>) throws -> [URL] {
+    guard let enumerator = FileManager.default.enumerator(
+      at: digestDirectoryURL,
+      includingPropertiesForKeys: [.isRegularFileKey],
+      options: [.skipsSubdirectoryDescendants]
+    ) else {
+      return []
+    }
+
+    return try enumerator.compactMap { element in
+      guard let url = element as? URL,
+            try url.resourceValues(forKeys: [.isRegularFileKey]).isRegularFile == true else {
+        return nil
+      }
+
+      let contentDigest = "\(Self.digestPrefix)\(url.lastPathComponent)"
+      guard (try? validatedDigestHex(contentDigest)) != nil,
+            !referencedContentDigests.contains(contentDigest) else {
+        return nil
+      }
+
+      return url
+    }
+  }
+
+  /// Move a fully reconstructed temporary file into the cache after verifying
+  /// its semantic identity. The caller should create the temporary file with
+  /// temporaryContentURL(for:) or resumableContentURL(for:) so rename stays on
+  /// the same filesystem.
+  func install(_ temporaryURL: URL, contentDigest: String) throws -> URL {
+    let actualDigest = try Digest.hash(temporaryURL)
+    guard actualDigest == contentDigest else {
+      throw ContentStoreError.contentDigestMismatch(expected: contentDigest, actual: actualDigest)
+    }
+
+    let targetURL = try contentURL(for: contentDigest)
+    let lock = try FileLock(lockURL: baseURL)
+    try lock.lock()
+    defer { try? lock.unlock() }
+
+    if let existingURL = try existingContentURL(for: contentDigest) {
+      try? FileManager.default.removeItem(at: temporaryURL)
+      return existingURL
+    }
+
+    if FileManager.default.fileExists(atPath: targetURL.path) {
+      _ = try FileManager.default.replaceItemAt(targetURL, withItemAt: temporaryURL)
+    } else {
+      try FileManager.default.moveItem(at: temporaryURL, to: targetURL)
+    }
+
+    return targetURL
+  }
+
+  private func validatedDigestHex(_ contentDigest: String) throws -> String {
+    guard contentDigest.hasPrefix(Self.digestPrefix) else {
+      throw ContentStoreError.invalidContentDigest(contentDigest)
+    }
+
+    let digestHex = String(contentDigest.dropFirst(Self.digestPrefix.count))
+    let isHex = digestHex.allSatisfy { $0.isHexDigit && !$0.isUppercase }
+
+    guard digestHex.count == 64, isHex else {
+      throw ContentStoreError.invalidContentDigest(contentDigest)
+    }
+
+    return digestHex
+  }
+}

Sources/tart/ControlSocket.swift

@@ -6,30 +6,48 @@ import NIOPosix
 
 @available(macOS 14, *)
 class ControlSocket {
+  typealias ServerChannel = NIOAsyncChannel<NIOAsyncChannel<ByteBuffer, ByteBuffer>, Never>
+
   let controlSocketURL: URL
   let vmPort: UInt32
-  let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+  let eventLoopGroup: MultiThreadedEventLoopGroup
+  let serverChannel: ServerChannel
   let logger: os.Logger = os.Logger(subsystem: "org.cirruslabs.tart.control-socket", category: "network")
 
-  init(_ controlSocketURL: URL, vmPort: UInt32 = 8080) {
+  init(_ controlSocketURL: URL, vmPort: UInt32 = 8080) async throws {
     self.controlSocketURL = controlSocketURL
     self.vmPort = vmPort
-  }
+    let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    self.eventLoopGroup = eventLoopGroup
 
-  func run() async throws {
     // Remove control socket file from previous "tart run" invocations,
     // if any, otherwise we may get the "address already in use" error
     try? FileManager.default.removeItem(atPath: controlSocketURL.path())
 
-    let serverChannel = try await ServerBootstrap(group: eventLoopGroup)
-      .bind(unixDomainSocketPath: controlSocketURL.path()) { childChannel in
-        childChannel.eventLoop.makeCompletedFuture {
-          return try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
-            wrappingChannelSynchronously: childChannel
-          )
-        }
-      }
+    // Change the current working directory to a VM's base directory
+    // to work around Unix domain socket 104 byte limitation [1]
+    //
+    // [1]: https://blog.8-p.info/en/2020/06/11/unix-domain-socket-length/
+    if let baseURL = controlSocketURL.baseURL {
+      FileManager.default.changeCurrentDirectoryPath(baseURL.path())
+    }
 
+    do {
+      self.serverChannel = try await ServerBootstrap(group: eventLoopGroup)
+        .bind(unixDomainSocketPath: controlSocketURL.relativePath) { childChannel in
+          childChannel.eventLoop.makeCompletedFuture {
+            return try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+              wrappingChannelSynchronously: childChannel
+            )
+          }
+        }
+    } catch {
+      try? await eventLoopGroup.shutdownGracefully()
+      throw error
+    }
+  }
+
+  func run() async throws {
     try await withThrowingDiscardingTaskGroup { group in
       try await serverChannel.executeThenClose { serverInbound in
         for try await clientChannel in serverInbound {

Sources/tart/Credentials/CredentialsProvider.swift

@@ -5,6 +5,7 @@ enum CredentialsProviderError: Error {
 }
 
 protocol CredentialsProvider {
+  var userFriendlyName: String { get }
   func retrieve(host: String) throws -> (String, String)?
   func store(host: String, user: String, password: String) throws
 }

Sources/tart/Credentials/DockerConfigCredentialsProvider.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 class DockerConfigCredentialsProvider: CredentialsProvider {
+  let userFriendlyName = "Docker configuration credentials provider"
+
   func retrieve(host: String) throws -> (String, String)? {
     let dockerConfigURL = FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".docker").appendingPathComponent("config.json")
     if !FileManager.default.fileExists(atPath: dockerConfigURL.path) {

Sources/tart/Credentials/EnvironmentCredentialsProvider.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 class EnvironmentCredentialsProvider: CredentialsProvider {
+  let userFriendlyName = "environment variable credentials provider"
+
   func retrieve(host: String) throws -> (String, String)? {
     if let tartRegistryHostname = ProcessInfo.processInfo.environment["TART_REGISTRY_HOSTNAME"],
        tartRegistryHostname != host {

Sources/tart/Credentials/KeychainCredentialsProvider.swift

@@ -1,6 +1,8 @@
 import Foundation
 
 class KeychainCredentialsProvider: CredentialsProvider {
+  let userFriendlyName = "Keychain credentials provider"
+
   func retrieve(host: String) throws -> (String, String)? {
     let query: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
                                 kSecAttrProtocol as String: kSecAttrProtocolHTTPS,

Sources/tart/Credentials/StdinCredentials.swift

@@ -6,6 +6,8 @@ enum StdinCredentialsError: Error {
 }
 
 class StdinCredentials {
+  let userFriendlyName = "standard input credentials provider"
+
   static func retrieve() throws -> (String, String) {
     let user = try readStdinCredential(name: "username", prompt: "User: ", isSensitive: false)
     let password = try readStdinCredential(name: "password", prompt: "Password: ", isSensitive: true)
@@ -13,7 +15,7 @@ class StdinCredentials {
     return (user, password)
   }
 
-  private static func readStdinCredential(name: String, prompt: String, maxCharacters: Int = 1024, isSensitive: Bool) throws -> String {
+  private static func readStdinCredential(name: String, prompt: String, maxCharacters: Int = 8192, isSensitive: Bool) throws -> String {
     var buf = [CChar](repeating: 0, count: maxCharacters + 1 /* sentinel */ + 1 /* NUL */)
     guard let rawCredential = readpassphrase(prompt, &buf, buf.count, isSensitive ? RPP_ECHO_OFF : RPP_ECHO_ON) else {
       throw StdinCredentialsError.CredentialRequired(which: name)

Sources/tart/DiskImageFormat.swift

@@ -21,7 +21,7 @@ enum DiskImageFormat: String, CaseIterable, Codable {
     case .raw:
       return true
     case .asif:
-      if #available(macOS 15, *) {
+      if #available(macOS 26, *) {
         return true
       } else {
         return false

Sources/tart/DiskImageStack.swift

@@ -0,0 +1,304 @@
+import Foundation
+import Virtualization
+
+#if canImport(DiskImageKit)
+  import DiskImageKit
+#endif
+
+/// The logical block layout exposed by a disk image.
+struct DiskImageBlockLayout {
+  let blockSize: UInt64
+  let blockCount: UInt64
+}
+
+enum DiskImageStackError: Error, Equatable, CustomStringConvertible {
+  case unavailable
+  case writableOverlayAlreadyExists(URL)
+  case writableOverlayMissing(URL)
+  case invalidBlockLayout(String)
+  case invalidDiskImage(URL, String)
+
+  var description: String {
+    switch self {
+    case .unavailable:
+      "stacked disks require DiskImageKit on macOS 27 or newer"
+    case .writableOverlayAlreadyExists(let url):
+      "writable overlay already exists: \(url.path)"
+    case .writableOverlayMissing(let url):
+      "writable overlay is missing: \(url.path)"
+    case .invalidBlockLayout(let reason):
+      reason
+    case .invalidDiskImage(let url, let reason):
+      "\(reason): \(url.path)"
+    }
+  }
+}
+
+struct DiskImageStack {
+  /// DiskImageKit-ready paths and block layout after Tart disk chunks have been
+  /// reconstructed into complete immutable files. The writable overlay stays
+  /// private to one VM.
+  let baseURL: URL
+  let baseFormat: DiskImageFormat
+  let immutableOverlayURLs: [URL]
+  let writableOverlayURL: URL
+  let blockSize: UInt64
+  let blockCount: UInt64
+
+  static var isSupported: Bool {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        return true
+      }
+    #endif
+
+    return false
+  }
+
+  static func requireSupport() throws {
+    guard isSupported else {
+      throw DiskImageStackError.unavailable
+    }
+  }
+
+  /// Reads a disk image's current block layout without resolving or validating a
+  /// whole stack. This is used for the VM's private writable overlay, whose
+  /// size may be newer than the pinned immutable parent manifest.
+  static func diskImageBlockLayout(at url: URL) throws -> DiskImageBlockLayout {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        let image = try DiskImage(opening: .open(url: url, mode: .readOnly))
+        return DiskImageBlockLayout(
+          blockSize: UInt64(image.blockSize.rawValue),
+          blockCount: UInt64(image.blockCount)
+        )
+      }
+    #endif
+
+    throw DiskImageStackError.unavailable
+  }
+
+  static func baseBlockLayout(
+    at url: URL,
+    expectedFormat: DiskImageFormat
+  ) throws -> DiskImageBlockLayout {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        let image = try DiskImage(opening: .open(url: url, mode: .readOnly))
+        try validateBase(image, at: url, expectedFormat: expectedFormat)
+
+        return DiskImageBlockLayout(
+          blockSize: UInt64(image.blockSize.rawValue),
+          blockCount: UInt64(image.blockCount)
+        )
+      }
+    #endif
+
+    throw DiskImageStackError.unavailable
+  }
+
+  func createWritableOverlay() throws {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        try createWritableOverlayWithDiskImageKit()
+        return
+      }
+    #endif
+
+    throw DiskImageStackError.unavailable
+  }
+
+  func copyWritableOverlay(to destinationURL: URL) throws {
+    guard !FileManager.default.fileExists(atPath: destinationURL.path) else {
+      throw DiskImageStackError.writableOverlayAlreadyExists(destinationURL)
+    }
+
+    try FileManager.default.copyItem(at: writableOverlayURL, to: destinationURL)
+  }
+
+  func makeAttachment(
+    readOnly: Bool = false,
+    cachingMode: VZDiskImageCachingMode = .automatic,
+    synchronizationMode: VZDiskImageSynchronizationMode = .full
+  ) throws -> VZStorageDeviceAttachment {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        return try attachmentWithDiskImageKit(
+          readOnly: readOnly,
+          cachingMode: cachingMode,
+          synchronizationMode: synchronizationMode
+        )
+      }
+    #endif
+
+    throw DiskImageStackError.unavailable
+  }
+
+  func growWritableOverlay(toBlockCount blockCount: UInt64) throws {
+    #if canImport(DiskImageKit)
+      if #available(macOS 27.0, *) {
+        try growWritableOverlayWithDiskImageKit(toBlockCount: blockCount)
+        return
+      }
+    #endif
+
+    throw DiskImageStackError.unavailable
+  }
+
+  #if canImport(DiskImageKit)
+    @available(macOS 27.0, *)
+    private func createWritableOverlayWithDiskImageKit() throws {
+      guard !FileManager.default.fileExists(atPath: writableOverlayURL.path) else {
+        throw DiskImageStackError.writableOverlayAlreadyExists(writableOverlayURL)
+      }
+
+      let parent = try validatedParentImage()
+      let stackedImage = try parent.appending(.asifLayer(url: writableOverlayURL, type: .overlay))
+      try validateAppendedOverlay(stackedImage, at: writableOverlayURL)
+    }
+
+    @available(macOS 27.0, *)
+    private func attachmentWithDiskImageKit(
+      readOnly: Bool,
+      cachingMode: VZDiskImageCachingMode,
+      synchronizationMode: VZDiskImageSynchronizationMode
+    ) throws -> VZDiskImageStorageDeviceAttachment {
+      guard FileManager.default.fileExists(atPath: writableOverlayURL.path) else {
+        throw DiskImageStackError.writableOverlayMissing(writableOverlayURL)
+      }
+
+      let parent = try validatedParentImage()
+      let writableOverlay = try openOverlay(
+        at: writableOverlayURL,
+        mode: readOnly ? .readOnly : .readWrite
+      )
+      let stackedImage = try append(writableOverlay, to: parent, at: writableOverlayURL)
+      try validateAppendedOverlay(stackedImage, at: writableOverlayURL)
+
+      return try VZDiskImageStorageDeviceAttachment(
+        diskImage: stackedImage,
+        cachingMode: cachingMode,
+        synchronizationMode: synchronizationMode
+      )
+    }
+
+    @available(macOS 27.0, *)
+    private func growWritableOverlayWithDiskImageKit(toBlockCount blockCount: UInt64) throws {
+      guard blockCount > 0, let desiredBlockCount = Int(exactly: blockCount) else {
+        throw DiskImageStackError.invalidBlockLayout("invalid stacked disk block count \(blockCount)")
+      }
+
+      let parent = try validatedParentImage()
+      let overlay = try openOverlay(
+        at: writableOverlayURL,
+        mode: .readWrite
+      )
+      let currentBlockCount = overlay.blockCount
+      let stackedImage = try append(overlay, to: parent, at: writableOverlayURL)
+      try validateAppendedOverlay(stackedImage, at: writableOverlayURL)
+      guard desiredBlockCount >= currentBlockCount else {
+        throw DiskImageStackError.invalidDiskImage(writableOverlayURL, "ASIF overlay block count shrinks the stacked disk")
+      }
+
+      guard let writableOverlay = stackedImage.layers.last else {
+        throw DiskImageStackError.invalidDiskImage(writableOverlayURL, "disk image must be an ASIF overlay")
+      }
+      if desiredBlockCount > currentBlockCount {
+        try writableOverlay.truncate(blockCount: desiredBlockCount)
+      }
+    }
+
+    @available(macOS 27.0, *)
+    private func validatedParentImage() throws -> DiskImage {
+      let expectedBlockSize = try diskImageBlockSize(blockSize)
+      guard blockCount > 0, let expectedBlockCount = Int(exactly: blockCount) else {
+        throw DiskImageStackError.invalidBlockLayout("invalid stacked disk block count \(blockCount)")
+      }
+
+      let baseImage = try DiskImage(opening: .open(url: baseURL, mode: .readOnly))
+      try Self.validateBase(baseImage, at: baseURL, expectedFormat: baseFormat)
+
+      var image = baseImage
+
+      for overlayURL in immutableOverlayURLs {
+        let openedOverlay = try openOverlay(
+          at: overlayURL,
+          mode: .readOnly
+        )
+        let stackedImage = try append(openedOverlay, to: image, at: overlayURL)
+        try validateAppendedOverlay(stackedImage, at: overlayURL)
+        image = stackedImage
+      }
+
+      guard image.blockSize == expectedBlockSize else {
+        throw DiskImageStackError.invalidBlockLayout("immutable disk stack does not match manifest block size")
+      }
+      guard image.blockCount == expectedBlockCount else {
+        throw DiskImageStackError.invalidBlockLayout("immutable disk stack does not match manifest block count")
+      }
+
+      return image
+    }
+
+    @available(macOS 27.0, *)
+    private static func validateBase(
+      _ image: DiskImage,
+      at url: URL,
+      expectedFormat: DiskImageFormat
+    ) throws {
+      let matchesFormat = switch expectedFormat {
+      case .raw:
+        image.format == .raw
+      case .asif:
+        image.format == .asif
+      }
+      guard matchesFormat else {
+        throw DiskImageStackError.invalidDiskImage(url, "base disk format does not match")
+      }
+      guard image.layerType == nil, image.parentUUID == nil else {
+        throw DiskImageStackError.invalidDiskImage(url, "base disk must not be an overlay")
+      }
+      if expectedFormat == .asif && image.layerUUID == nil {
+        throw DiskImageStackError.invalidDiskImage(url, "ASIF base disk is missing a UUID")
+      }
+    }
+
+    @available(macOS 27.0, *)
+    private func openOverlay(
+      at url: URL,
+      mode: OpenConfiguration.Mode
+    ) throws -> DiskImage {
+      let image = try DiskImage(opening: .open(url: url, mode: mode))
+      guard image.format == .asif else {
+        throw DiskImageStackError.invalidDiskImage(url, "overlay must use ASIF format")
+      }
+
+      return image
+    }
+
+    @available(macOS 27.0, *)
+    private func append(_ overlay: DiskImage, to parent: DiskImage, at url: URL) throws -> any StackedImage {
+      do {
+        return try parent.appending(overlay)
+      } catch is IncompatibleStackingError {
+        throw DiskImageStackError.invalidDiskImage(url, "ASIF overlay is incompatible with its parent")
+      }
+    }
+
+    @available(macOS 27.0, *)
+    private func validateAppendedOverlay(_ image: any StackedImage, at url: URL) throws {
+      guard image.layers.last?.layerType == .overlay else {
+        throw DiskImageStackError.invalidDiskImage(url, "disk image must be an ASIF overlay")
+      }
+    }
+
+    @available(macOS 27.0, *)
+    private func diskImageBlockSize(_ value: UInt64) throws -> DiskImage.BlockSize {
+      guard let intValue = Int(exactly: value), let blockSize = DiskImage.BlockSize(rawValue: intValue) else {
+        throw DiskImageStackError.invalidBlockLayout("unsupported stacked disk block size \(value)")
+      }
+
+      return blockSize
+    }
+  #endif
+}

Sources/tart/Diskutil.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+struct ImageInfo: Codable {
+  let sizeInfo: SizeInfo?
+  let size: UInt64?
+
+  enum CodingKeys: String, CodingKey {
+    case sizeInfo = "Size Info"
+    case size = "Size"
+  }
+
+  func totalBytes() throws -> Int {
+    if let totalBytes = self.sizeInfo?.totalBytes {
+      return Int(totalBytes)
+    }
+
+    if let size = self.size {
+      return Int(size)
+    }
+
+    throw RuntimeError.Generic("Could not find size information in disk image info")
+  }
+}
+
+struct SizeInfo: Codable {
+  let totalBytes: UInt64?
+
+  enum CodingKeys: String, CodingKey {
+    case totalBytes = "Total Bytes"
+  }
+}
+
+struct Diskutil {
+  static func imageCreate(diskURL: URL, sizeGB: UInt16) throws {
+    do {
+      _ = try run([
+        "image", "create", "blank",
+        "--format", "ASIF",
+        "--size", "\(sizeGB)G",
+        "--volumeName", "Tart",
+        diskURL.path
+      ])
+    } catch {
+      throw RuntimeError.FailedToCreateDisk("Failed to create ASIF disk image: \(error)")
+    }
+  }
+
+  static func imageInfo(_ diskURL: URL) throws -> ImageInfo {
+    do {
+      let (stdoutData, _) = try run([
+        "image", "info", "--plist",
+        diskURL.path
+      ])
+
+      do {
+        return try PropertyListDecoder().decode(ImageInfo.self, from: stdoutData)
+      } catch {
+        throw RuntimeError.Generic("Failed to parse \"diskutil image info --plist\" output: \(error)")
+      }
+    }
+  }
+
+  private static func run(_ arguments: [String]) throws -> (Data, Data) {
+    guard let diskutilURL = resolveBinaryPath("diskutil") else {
+      throw RuntimeError.Generic("\"diskutil\" binary is not found in PATH")
+    }
+
+    let process = Process()
+    process.executableURL = diskutilURL
+    process.arguments = arguments
+
+    let stdoutPipe = Pipe()
+    process.standardOutput = stdoutPipe
+    let stderrPipe = Pipe()
+    process.standardError = stderrPipe
+
+    do {
+      try process.run()
+    } catch {
+      throw RuntimeError.Generic("\"\(arguments.joined(separator: " "))\" failed: \(error)")
+    }
+    process.waitUntilExit()
+
+    let stdoutData = stdoutPipe.fileHandleForReading.readDataToEndOfFile()
+    let stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()
+
+    if process.terminationStatus != 0 {
+      let stdoutString = String(data: stdoutData, encoding: .utf8) ?? ""
+      let stderrString = String(data: stderrData, encoding: .utf8) ?? ""
+
+      throw RuntimeError.Generic("\"\(arguments.joined(separator: " "))\" failed with exit code \(process.terminationStatus): \(firstNonEmptyLine(stderrString, stdoutString))")
+    }
+
+    return (stdoutData, stderrData)
+  }
+
+  private static func firstNonEmptyLine(_ outputs: String...) -> String {
+    for output in outputs {
+      for line in output.split(separator: "\n", omittingEmptySubsequences: false) {
+        if !line.isEmpty {
+          return String(line)
+        }
+      }
+    }
+
+    return ""
+  }
+}

Sources/tart/Formatter/HumanReadableByteCount.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+struct HumanReadableByteCount: Encodable, CustomStringConvertible {
+  private let byteCount: Int
+  private let jsonValue: any Encodable
+
+  init<JSONValue: Encodable>(_ byteCount: Int, encodedAs: (Int) -> JSONValue) {
+    self.byteCount = byteCount
+    self.jsonValue = encodedAs(byteCount)
+  }
+
+  var description: String {
+    let formatter = MeasurementFormatter()
+    formatter.unitOptions = .naturalScale
+    formatter.unitStyle = .medium
+    formatter.numberFormatter.maximumFractionDigits = 0
+
+    return formatter.string(
+      from: Measurement(value: Double(byteCount), unit: UnitInformationStorage.bytes)
+    )
+  }
+
+  func encode(to encoder: Encoder) throws {
+    try jsonValue.encode(to: encoder)
+  }
+}

Sources/tart/GuestAgentChannel.swift

@@ -0,0 +1,28 @@
+import GRPC
+import NIOPosix
+
+/// Connects to a guest agent's gRPC endpoint over a VM's control socket, runs
+/// `body` with the resulting channel, and closes the channel afterwards on both
+/// the success and error paths.
+///
+/// The connection uses the process-wide singleton event loop group, which must
+/// not be shut down, so there is no group lifecycle to manage here.
+func withGuestAgentChannel<T>(
+  unixDomainSocketPath socketPath: String,
+  _ body: (GRPCChannel) async throws -> T
+) async throws -> T {
+  let channel = try GRPCChannelPool.with(
+    target: .unixDomainSocket(socketPath),
+    transportSecurity: .plaintext,
+    eventLoopGroup: .singletonMultiThreadedEventLoopGroup,
+  )
+
+  do {
+    let result = try await body(channel)
+    try await channel.close().get()
+    return result
+  } catch {
+    try? await channel.close().get()
+    throw error
+  }
+}

Sources/tart/Logging/ProgressObserver.swift

@@ -4,18 +4,28 @@ public class ProgressObserver: NSObject {
   @objc var progressToObserve: Progress
   var observation: NSKeyValueObservation?
   var lastTimeUpdated = Date.now
+  private var lastRenderedLine: String?
 
   public init(_ progress: Progress) {
     progressToObserve = progress
   }
 
   func log(_ renderer: Logger) {
-    renderer.appendNewLine(ProgressObserver.lineToRender(progressToObserve))
+    let initialLine = ProgressObserver.lineToRender(progressToObserve)
+    renderer.appendNewLine(initialLine)
+    lastRenderedLine = initialLine
     observation = observe(\.progressToObserve.fractionCompleted) { progress, _ in
       let currentTime = Date.now
       if self.progressToObserve.isFinished || currentTime.timeIntervalSince(self.lastTimeUpdated) >= 1.0 {
         self.lastTimeUpdated = currentTime
-        renderer.updateLastLine(ProgressObserver.lineToRender(self.progressToObserve))
+        let line = ProgressObserver.lineToRender(self.progressToObserve)
+        // Skip identical renders so non-interactive logs only see new percent values.
+        if line == self.lastRenderedLine {
+          return
+        }
+
+        self.lastRenderedLine = line
+        renderer.updateLastLine(line)
       }
     }
   }

Sources/tart/MACAddressResolver/AgentResolver.swift

@@ -1,42 +1,28 @@
 import Foundation
 import Network
-import NIOPosix
 import GRPC
 import Cirruslabs_TartGuestAgent_Apple_Swift
 import Cirruslabs_TartGuestAgent_Grpc_Swift
 
 class AgentResolver {
-  static func ResolveIP(_ controlSocketURL: URL) async throws -> IPv4Address? {
+  static func ResolveIP(_ controlSocketPath: String) async throws -> IPv4Address? {
     do {
-      return try await resolveIP(controlSocketURL)
-    } catch let error as GRPCConnectionPoolError {
+      return try await resolveIP(controlSocketPath)
+    } catch is GRPCConnectionPoolError {
       return nil
     }
   }
 
-  private static func resolveIP(_ controlSocketURL: URL) async throws -> IPv4Address? {
-    // Create a gRPC channel connected to the VM's control socket
-    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
-    defer {
-      try! group.syncShutdownGracefully()
+  private static func resolveIP(_ controlSocketPath: String) async throws -> IPv4Address? {
+    try await withGuestAgentChannel(unixDomainSocketPath: controlSocketPath) { channel in
+      // Invoke ResolveIP() gRPC method
+      let callOptions = CallOptions(timeLimit: .timeout(.seconds(1)))
+      let agentAsyncClient = AgentAsyncClient(channel: channel)
+      let resolveIPCall = agentAsyncClient.makeResolveIpCall(ResolveIPRequest(), callOptions: callOptions)
+
+      let response = try await resolveIPCall.response
+
+      return IPv4Address(response.ip)
     }
-
-    let channel = try GRPCChannelPool.with(
-      target: .unixDomainSocket(controlSocketURL.path()),
-      transportSecurity: .plaintext,
-      eventLoopGroup: group,
-    )
-    defer {
-      try! channel.close().wait()
-    }
-
-    // Invoke ResolveIP() gRPC method
-    let callOptions = CallOptions(timeLimit: .timeout(.seconds(1)))
-    let agentAsyncClient = AgentAsyncClient(channel: channel)
-    let resolveIPCall = agentAsyncClient.makeResolveIpCall(ResolveIPRequest(), callOptions: callOptions)
-
-    let response = try await resolveIPCall.response
-
-    return IPv4Address(response.ip)
   }
 }

Sources/tart/Network/Softnet.swift

@@ -16,7 +16,18 @@ class Softnet: Network {
 
   let vmFD: Int32
 
-  init(vmMACAddress: String, extraArguments: [String] = []) throws {
+  init(vmMACAddress: String, extraArguments: [String] = [], controlFD: Int32? = nil) throws {
+    var controlFileHandle: FileHandle?
+
+    if let controlFD = controlFD {
+      guard controlFD > STDERR_FILENO else {
+        throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor must be greater than 2")
+      }
+
+      controlFileHandle = FileHandle(fileDescriptor: controlFD, closeOnDealloc: true)
+      try Self.validateControlFD(controlFD)
+    }
+
     let fds = UnsafeMutablePointer<Int32>.allocate(capacity: MemoryLayout<Int>.stride * 2)
 
     let ret = socketpair(AF_UNIX, SOCK_DGRAM, 0, fds)
@@ -33,6 +44,44 @@ class Softnet: Network {
     process.executableURL = try Self.softnetExecutableURL()
     process.arguments = ["--vm-fd", String(STDIN_FILENO), "--vm-mac-address", vmMACAddress] + extraArguments
     process.standardInput = FileHandle(fileDescriptor: softnetFD, closeOnDealloc: false)
+
+    if let controlFileHandle = controlFileHandle {
+      process.arguments! += ["--control-fd", String(STDOUT_FILENO)]
+      process.standardOutput = controlFileHandle
+    }
+  }
+
+  static func validateControlFD(_ fd: Int32) throws {
+    guard fd > STDERR_FILENO else {
+      throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor must be greater than 2")
+    }
+
+    var socketType: Int32 = 0
+    var socketTypeLength = socklen_t(MemoryLayout<Int32>.size)
+    guard getsockopt(fd, SOL_SOCKET, SO_TYPE, &socketType, &socketTypeLength) == 0 else {
+      let details = Errno(rawValue: CInt(errno))
+      throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor is not a socket: \(details)")
+    }
+
+    guard socketType == SOCK_STREAM else {
+      throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor must be a Unix stream socket")
+    }
+
+    var peerAddress = sockaddr_storage()
+    var peerAddressLength = socklen_t(MemoryLayout<sockaddr_storage>.size)
+    let result = withUnsafeMutablePointer(to: &peerAddress) { pointer in
+      pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+        getpeername(fd, $0, &peerAddressLength)
+      }
+    }
+    guard result == 0 else {
+      let details = Errno(rawValue: CInt(errno))
+      throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor is not connected: \(details)")
+    }
+
+    guard peerAddress.ss_family == sa_family_t(AF_UNIX) else {
+      throw SoftnetError.InitializationFailed(why: "Softnet control file descriptor must be a Unix stream socket")
+    }
   }
 
   static func softnetExecutableURL() throws -> URL {
@@ -46,6 +95,8 @@ class Softnet: Network {
   }
 
   func run(_ sema: AsyncSemaphore) throws {
+    defer { try? (process.standardOutput as? FileHandle)?.close() }
+
     try process.run()
 
     monitorTask = Task {

Sources/tart/OCI/Digest.swift

@@ -7,6 +7,8 @@ enum DigestError: Error {
 }
 
 class Digest {
+  private static let fileBufferSize = 4 * 1024 * 1024
+
   var hash: SHA256 = SHA256()
 
   func update(_ data: Data) {
@@ -22,7 +24,10 @@ class Digest {
   }
 
   static func hash(_ url: URL) throws -> String {
-    hash(try Data(contentsOf: url))
+    let file = try FileHandle(forReadingFrom: url)
+    defer { try? file.close() }
+
+    return try hashContents(from: file)
   }
 
   static func hash(_ url: URL, offset: UInt64, size: UInt64) throws -> String {
@@ -36,20 +41,53 @@ class Digest {
       throw DigestError.InvalidOffset
     }
 
-    if (offset + size) > fileSize {
+    if size > fileSize - offset {
       throw DigestError.InvalidSize
     }
 
-    // Read a chunk of size ``size`` at offset ``offset``
-    // and calculate it's digest
+    // Read the requested range incrementally and calculate its digest.
     let fh = try FileHandle(forReadingFrom: url)
-    defer { try! fh.close() }
+    defer { try? fh.close() }
 
     try fh.seek(toOffset: offset)
 
-    let data = try fh.read(upToCount: Int(size))!
+    return try hashContents(from: fh, size: size)
+  }
 
-    return hash(data)
+  /// Streams a file into SHA-256 while keeping Foundation's temporary read
+  /// buffers scoped to one chunk.
+  private static func hashContents(from file: FileHandle, size: UInt64? = nil) throws -> String {
+    let digest = Digest()
+    var remaining = size
+
+    while remaining.map({ $0 > 0 }) ?? true {
+      let didRead = try autoreleasepool { () throws -> Bool in
+        let count = remaining.map {
+          Int(min(UInt64(fileBufferSize), $0))
+        } ?? fileBufferSize
+
+        guard let data = try file.read(upToCount: count), !data.isEmpty else {
+          if remaining != nil {
+            throw DigestError.InvalidSize
+          }
+
+          return false
+        }
+
+        digest.update(data)
+        if let bytesRemaining = remaining {
+          remaining = bytesRemaining - UInt64(data.count)
+        }
+
+        return true
+      }
+
+      if !didRead {
+        break
+      }
+    }
+
+    return digest.finalize()
   }
 }
 

Sources/tart/OCI/Layerizer/Disk.swift

@@ -1,6 +1,6 @@
 import Foundation
 
 protocol Disk {
-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer]
+  static func push(diskURL: URL, mediaType: String, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer]
   static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache?, deduplicate: Bool) async throws
 }

Sources/tart/OCI/Layerizer/DiskV1.swift

@@ -1,75 +0,0 @@
-import Foundation
-import Compression
-
-class DiskV1: Disk {
-  private static let bufferSizeBytes = 4 * 1024 * 1024
-  private static let layerLimitBytes = 500 * 1000 * 1000
-
-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer] {
-    var pushedLayers: [OCIManifestLayer] = []
-
-    // Open the disk file
-    let mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
-    var mappedDiskReadOffset = 0
-
-    // Compress the disk file as a single stream
-    let compressingFilter = try InputFilter(.compress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { (length: Int) -> Data? in
-      // Determine the size of the next chunk
-      let bytesRead = min(length, mappedDisk.count - mappedDiskReadOffset)
-
-      // Read the next uncompressed chunk
-      let data = mappedDisk.subdata(in: mappedDiskReadOffset ..< mappedDiskReadOffset + bytesRead)
-
-      // Advance the offset
-      mappedDiskReadOffset += bytesRead
-
-      // Provide the uncompressed chunk to the compressing filter
-      return data
-    }
-
-    // Cut the compressed stream into layers, each equal exactly ``Self.layerLimitBytes`` bytes,
-    // except for the last one, which may be smaller
-    while let compressedData = try compressingFilter.readData(ofLength: Self.layerLimitBytes) {
-      let layerDigest = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb)
-
-      pushedLayers.append(OCIManifestLayer(
-        mediaType: diskV1MediaType,
-        size: compressedData.count,
-        digest: layerDigest
-      ))
-
-      // Update progress using an absolute value
-      progress.completedUnitCount = Int64(mappedDiskReadOffset)
-    }
-
-    return pushedLayers
-  }
-
-  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil, deduplicate: Bool = false) async throws {
-    if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
-      throw OCIError.FailedToCreateVmFile
-    }
-
-    // Open the disk file
-    let disk = try FileHandle(forWritingTo: diskURL)
-    defer { try! disk.close() }
-
-    // Decompress the layers onto the disk in a single stream
-    let filter = try OutputFilter(.decompress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { data in
-      if let data = data {
-        try disk.write(contentsOf: data)
-      }
-    }
-
-    for diskLayer in diskLayers {
-      try await registry.pullBlob(diskLayer.digest) { data in
-        try filter.write(data)
-
-        // Update the progress
-        progress.completedUnitCount += Int64(data.count)
-      }
-    }
-
-    try filter.finalize()
-  }
-}

Sources/tart/OCI/Layerizer/DiskV2.swift

@@ -22,7 +22,14 @@ class DiskV2: Disk {
   private static let holeGranularityBytes = 4 * 1024 * 1024
   private static let zeroChunk = Data(count: holeGranularityBytes)
 
-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer] {
+  static func push(
+    diskURL: URL,
+    mediaType: String,
+    registry: Registry,
+    chunkSizeMb: Int,
+    concurrency: UInt,
+    progress: Progress
+  ) async throws -> [OCIManifestLayer] {
     var pushedLayers: [(index: Int, pushedLayer: OCIManifestLayer)] = []
 
     // Open the disk file
@@ -63,7 +70,7 @@ class DiskV2: Disk {
           progress.completedUnitCount += Int64(data.count)
 
           return (index, OCIManifestLayer(
-            mediaType: diskV2MediaType,
+            mediaType: mediaType,
             size: compressedData.count,
             digest: compressedDataDigest,
             uncompressedSize: UInt64(data.count),

Sources/tart/OCI/Manifest.swift

@@ -6,13 +6,14 @@ let ociConfigMediaType = "application/vnd.oci.image.config.v1+json"
 
 // Layer media types
 let configMediaType = "application/vnd.cirruslabs.tart.config.v1"
-let diskV1MediaType = "application/vnd.cirruslabs.tart.disk.v1"
 let diskV2MediaType = "application/vnd.cirruslabs.tart.disk.v2"
+let asifOverlayMediaType = "application/vnd.cirruslabs.tart.disk.asif.overlay.v1"
 let nvramMediaType = "application/vnd.cirruslabs.tart.nvram.v1"
 
 // Manifest annotations
 let uncompressedDiskSizeAnnotation = "org.cirruslabs.tart.uncompressed-disk-size"
 let uploadTimeAnnotation = "org.cirruslabs.tart.upload-time"
+let diskBlockSizeAnnotation = "org.cirruslabs.tart.disk.block-size"
 
 // Manifest labels
 let diskFormatLabel = "org.cirruslabs.tart.disk.format"
@@ -20,6 +21,51 @@ let diskFormatLabel = "org.cirruslabs.tart.disk.format"
 // Layer annotations
 let uncompressedSizeAnnotation = "org.cirruslabs.tart.uncompressed-size"
 let uncompressedContentDigestAnnotation = "org.cirruslabs.tart.uncompressed-content-digest"
+let diskFileContentDigestAnnotation = "org.cirruslabs.tart.disk-file-content-digest"
+let diskFileChunkCountAnnotation = "org.cirruslabs.tart.disk-file-chunk-count"
+
+/// The OCI-layer descriptors whose Tart disk chunks reconstruct one complete
+/// base disk or ASIF overlay.
+struct TartDiskFileGroup: Equatable {
+  enum Kind: Equatable {
+    case base
+    case asifOverlay
+  }
+
+  var kind: Kind
+  var chunks: [OCIManifestLayer]
+  /// Whole reconstructed-file digest. Existing flat manifests do not have
+  /// this until a macOS 27 clone normalizes its local manifest copy.
+  var contentDigest: String?
+
+  /// Expected size of the complete disk file reconstructed from these chunks.
+  func uncompressedSize() -> UInt64? {
+    var result: UInt64 = 0
+    for chunk in chunks {
+      guard let size = chunk.uncompressedSize() else {
+        return nil
+      }
+
+      let addition = result.addingReportingOverflow(size)
+      guard !addition.overflow else {
+        return nil
+      }
+      result = addition.partialValue
+    }
+
+    return result
+  }
+}
+
+enum TartDiskRepresentation: Equatable {
+  case flat(base: TartDiskFileGroup)
+  case stacked(base: TartDiskFileGroup, overlays: [TartDiskFileGroup])
+}
+
+enum OCIManifestValidationError: Error, Equatable {
+  case invalidLayout(String)
+  case invalidDiskMetadata(String)
+}
 
 struct OCIManifest: Codable, Equatable {
   var schemaVersion: Int = 2
@@ -64,6 +110,116 @@ struct OCIManifest: Codable, Equatable {
 
     return UInt64(value)
   }
+
+  /// Parse Tart's canonical `config -> disk descriptors -> NVRAM` order.
+  /// A stacked image has a leading `disk.v2` base run followed by one or more
+  /// contiguous ASIF overlay chunk groups.
+  func tartDiskRepresentation() throws -> TartDiskRepresentation {
+    guard layers.filter({ $0.mediaType == configMediaType }).count == 1 else {
+      throw OCIManifestValidationError.invalidLayout("manifest must contain exactly one Tart config descriptor")
+    }
+    guard layers.filter({ $0.mediaType == nvramMediaType }).count == 1 else {
+      throw OCIManifestValidationError.invalidLayout("manifest must contain exactly one NVRAM descriptor")
+    }
+    guard layers.first?.mediaType == configMediaType,
+          layers.last?.mediaType == nvramMediaType else {
+      throw OCIManifestValidationError.invalidLayout("descriptors must be ordered as config, disk chunks, then NVRAM")
+    }
+
+    let diskDescriptors = Array(layers.dropFirst().dropLast())
+    guard !diskDescriptors.isEmpty else {
+      throw OCIManifestValidationError.invalidLayout("manifest has no disk chunks")
+    }
+
+    let baseChunkCount = diskDescriptors.prefix { $0.mediaType == diskV2MediaType }.count
+    guard baseChunkCount > 0 else {
+      throw OCIManifestValidationError.invalidLayout("disk chunks must start with a disk.v2 base")
+    }
+
+    let baseChunks = Array(diskDescriptors.prefix(baseChunkCount))
+    try validateChunkMetadata(baseChunks)
+    guard baseChunks.first?.diskFileChunkCount() == nil,
+          baseChunks.dropFirst().allSatisfy({
+            $0.diskFileContentDigest() == nil && $0.diskFileChunkCount() == nil
+          }) else {
+      throw OCIManifestValidationError.invalidDiskMetadata("base disk metadata must appear only on its first chunk")
+    }
+    let base = TartDiskFileGroup(
+      kind: .base,
+      chunks: baseChunks,
+      contentDigest: baseChunks.first?.diskFileContentDigest()
+    )
+
+    guard baseChunkCount < diskDescriptors.count else {
+      return .flat(base: base)
+    }
+
+    guard base.contentDigest != nil else {
+      throw OCIManifestValidationError.invalidDiskMetadata("a stacked base disk needs a whole-file content digest")
+    }
+
+    var overlays: [TartDiskFileGroup] = []
+    var index = baseChunkCount
+
+    while index < diskDescriptors.count {
+      let first = diskDescriptors[index]
+      guard first.mediaType == asifOverlayMediaType else {
+        throw OCIManifestValidationError.invalidLayout("unsupported disk chunk media type: \(first.mediaType)")
+      }
+      guard let contentDigest = first.diskFileContentDigest(),
+            let chunkCount = first.diskFileChunkCount() else {
+        throw OCIManifestValidationError.invalidDiskMetadata("an ASIF overlay needs a content digest and chunk count")
+      }
+      guard chunkCount > 0, index + chunkCount <= diskDescriptors.count else {
+        throw OCIManifestValidationError.invalidDiskMetadata("ASIF overlay chunk count is invalid")
+      }
+
+      let chunks = Array(diskDescriptors[index..<(index + chunkCount)])
+      guard chunks.allSatisfy({ $0.mediaType == asifOverlayMediaType }) else {
+        throw OCIManifestValidationError.invalidLayout("ASIF overlay chunks must be contiguous")
+      }
+      guard chunks.dropFirst().allSatisfy({ $0.diskFileContentDigest() == nil && $0.diskFileChunkCount() == nil }) else {
+        throw OCIManifestValidationError.invalidDiskMetadata("ASIF overlay metadata must appear only on its first chunk")
+      }
+      try validateChunkMetadata(chunks)
+
+      overlays.append(TartDiskFileGroup(kind: .asifOverlay, chunks: chunks, contentDigest: contentDigest))
+      index += chunkCount
+    }
+
+    return .stacked(base: base, overlays: overlays)
+  }
+
+  /// Returns content-store digests needed to reconstruct this disk stack.
+  func diskContentDigests() throws -> [String] {
+    switch try tartDiskRepresentation() {
+    case .flat(let base):
+      return base.contentDigest.map { [$0] } ?? []
+    case .stacked(let base, let overlays):
+      return ([base] + overlays).compactMap(\.contentDigest)
+    }
+  }
+
+  private func validateChunkMetadata(_ chunks: [OCIManifestLayer]) throws {
+    guard chunks.allSatisfy({ $0.uncompressedSize() != nil && $0.uncompressedContentDigest() != nil }) else {
+      throw OCIManifestValidationError.invalidDiskMetadata("disk chunks need uncompressed size and content digest")
+    }
+  }
+
+  func diskBlockSize() -> UInt64? {
+    annotations?[diskBlockSizeAnnotation].flatMap(UInt64.init)
+  }
+
+  func diskBlockCount() -> UInt64? {
+    guard let diskSize = uncompressedDiskSize(),
+          let blockSize = diskBlockSize(),
+          blockSize > 0,
+          diskSize.isMultiple(of: blockSize) else {
+      return nil
+    }
+
+    return diskSize / blockSize
+  }
 }
 
 struct OCIConfig: Codable {
@@ -122,6 +278,14 @@ struct OCIManifestLayer: Codable, Equatable, Hashable {
     annotations?[uncompressedContentDigestAnnotation]
   }
 
+  func diskFileContentDigest() -> String? {
+    annotations?[diskFileContentDigestAnnotation]
+  }
+
+  func diskFileChunkCount() -> Int? {
+    annotations?[diskFileChunkCountAnnotation].flatMap(Int.init)
+  }
+
   static func == (lhs: Self, rhs: Self) -> Bool {
     return lhs.digest == rhs.digest
   }

Sources/tart/OCI/Registry.swift

@@ -429,8 +429,12 @@ class Registry {
     }
 
     for provider in credentialsProviders {
-      if let (user, password) = try provider.retrieve(host: host) {
-        return (user, password)
+      do {
+        if let (user, password) = try provider.retrieve(host: host) {
+          return (user, password)
+        }
+      } catch (let e) {
+        print("Failed to retrieve credentials using \(provider.userFriendlyName), authentication may fail: \(e)")
       }
     }
     return nil

Sources/tart/OTel.swift

@@ -0,0 +1,64 @@
+import Foundation
+import OpenTelemetryApi
+import OpenTelemetrySdk
+import OpenTelemetryProtocolExporterHttp
+import ResourceExtension
+
+class OTel {
+  let tracerProvider: TracerProviderSdk?
+  let tracer: Tracer
+
+  static let shared = OTel()
+
+  init() {
+    tracerProvider = Self.initializeTracing()
+    tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "tart", instrumentationVersion: CI.version)
+  }
+
+  static func initializeTracing() -> TracerProviderSdk? {
+    guard let _ = ProcessInfo.processInfo.environment["TRACEPARENT"] else {
+      return nil
+    }
+
+    var resource = DefaultResources().get()
+
+    resource.merge(other: Resource(attributes: [
+      SemanticConventions.Service.name.rawValue: .string("tart"),
+      SemanticConventions.Service.version.rawValue: .string(CI.version)
+    ]))
+
+    let spanExporter: SpanExporter
+    if let endpointRaw = ProcessInfo.processInfo.environment["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"],
+       let endpoint = URL(string: endpointRaw) {
+      spanExporter = OtlpHttpTraceExporter(endpoint: endpoint)
+    } else {
+      spanExporter = OtlpHttpTraceExporter()
+    }
+    let spanProcessor = SimpleSpanProcessor(spanExporter: spanExporter)
+    let tracerProvider = TracerProviderBuilder()
+      .add(spanProcessor: spanProcessor)
+      .with(resource: resource)
+      .build()
+
+    OpenTelemetry.registerTracerProvider(tracerProvider: tracerProvider)
+
+    return tracerProvider
+  }
+
+  func flush() {
+    OpenTelemetry.instance.contextProvider.activeSpan?.end()
+
+    guard let tracerProvider else {
+      // No tracing was initialized, so just ending a span is enough
+      return
+    }
+
+    tracerProvider.forceFlush()
+
+    // Work around OpenTelemtry not flushing traces after explicitly asking it to do so
+    //
+    // [1]: https://github.com/open-telemetry/opentelemetry-swift/issues/685
+    // [2]: https://github.com/open-telemetry/opentelemetry-swift/issues/555
+    Thread.sleep(forTimeInterval: .fromMilliseconds(100))
+  }
+}

Sources/tart/Platform/Darwin.swift

@@ -82,7 +82,7 @@ struct UnsupportedHostOSError: Error, CustomStringConvertible {
     func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
       let result = VZMacGraphicsDeviceConfiguration()
 
-      if let hostMainScreen = NSScreen.main {
+      if (vmConfig.display.unit ?? .point) == .point, let hostMainScreen = NSScreen.main {
         let vmScreenSize = NSSize(width: vmConfig.display.width, height: vmConfig.display.height)
         result.displays = [
           VZMacGraphicsDisplayConfiguration(for: hostMainScreen, sizeInPoints: vmScreenSize)

Sources/tart/Root.swift

@@ -1,7 +1,9 @@
 import ArgumentParser
 import Darwin
 import Foundation
-import Sentry
+import OpenTelemetryApi
+import OpenTelemetrySdk
+import OpenTelemetryProtocolExporterHttp
 
 @main
 struct Root: AsyncParsableCommand {
@@ -30,101 +32,160 @@ struct Root: AsyncParsableCommand {
       FQN.self,
     ])
 
-  public static func main() async throws {
+  // Note: main() is intentionally synchronous. Swift's asynchronous main() entry
+  // point implicitly starts an executor that owns the main thread — and since
+  // Swift 6.4 that executor is no longer backed by the Dispatch main queue — so
+  // running an AppKit/SwiftUI run loop nested inside it leaves the main run loop
+  // unable to drain Tasks or DispatchQueue.main, and a VM started via "tart run"
+  // never boots. Keeping main() synchronous lets a command that needs the main
+  // run loop own it at the top level, exactly like a plain SwiftUI app.
+  public static func main() {
     // Add commands that are only available on specific macOS versions
     if #available(macOS 14, *) {
       configuration.subcommands.append(Suspend.self)
     }
 
-    // Ensure the default SIGINT handled is disabled,
-    // otherwise there's a race between two handlers
-    signal(SIGINT, SIG_IGN);
-    // Handle cancellation by Ctrl+C ourselves
-    let task = withUnsafeCurrentTask { $0 }!
-    let sigintSrc = DispatchSource.makeSignalSource(signal: SIGINT)
-    sigintSrc.setEventHandler {
-      task.cancel()
-    }
-    sigintSrc.activate()
+    // Ensure the default SIGINT handler is disabled, otherwise there's a race
+    // between two handlers. We handle cancellation by Ctrl+C ourselves below.
+    signal(SIGINT, SIG_IGN)
 
     // Set line-buffered output for stdout
     setlinebuf(stdout)
 
+    // Parse the command up-front, synchronously, so we can decide who gets to own
+    // the main thread before any concurrency is involved.
+    //
+    // ParsableCommand isn't Sendable, but we only ever hand it to the single task
+    // spawned below and never touch it again afterwards, so transferring it into
+    // that task is safe.
+    nonisolated(unsafe) let command: ParsableCommand
     do {
-      // Parse command
-      var command = try parseAsRoot()
-
-      // Initialize Sentry
-      if let dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"] {
-        SentrySDK.start { options in
-          options.dsn = dsn
-          options.releaseName = CI.release
-          options.tracesSampleRate = Float(
-            ProcessInfo.processInfo.environment["SENTRY_TRACES_SAMPLE_RATE"] ?? "1.0"
-          ) as NSNumber?
-
-          // By default only 5XX are captured
-          // Let's capture everything but 401 (unauthorized)
-          options.enableCaptureFailedRequests = true
-          options.failedRequestStatusCodes = [
-            HttpStatusCodeRange(min: 400, max: 400),
-            HttpStatusCodeRange(min: 402, max: 599)
-          ]
-        }
-      }
-      defer { SentrySDK.flush(timeout: 2.seconds.timeInterval) }
-
-      SentrySDK.configureScope { scope in
-        scope.setExtra(value: ProcessInfo.processInfo.arguments, key: "Command-line arguments")
-      }
-
-      // Enrich future events with Cirrus CI-specific tags
-      if let tags = ProcessInfo.processInfo.environment["CIRRUS_SENTRY_TAGS"] {
-        SentrySDK.configureScope { scope in
-          for (key, value) in tags.split(separator: ",").compactMap({ parseCirrusSentryTag($0) }) {
-            scope.setTag(value: value, key: key)
-          }
-        }
-      }
-
-      // Run garbage-collection before each command (shouldn't take too long)
-      if type(of: command) != type(of: Pull()) && type(of: command) != type(of: Clone()){
-        do {
-          try Config().gc()
-        } catch {
-          fputs("Failed to perform garbage collection!\n\(error)\n", stderr)
-        }
-      }
-
-      // Run command
-      if var asyncCommand = command as? AsyncParsableCommand {
-        try await asyncCommand.run()
-      } else {
-        try command.run()
-      }
+      command = try parseAsRoot()
     } catch {
-      // Not an error, just a custom exit code from "tart exec"
-      if let execCustomExitCodeError = error as? ExecCustomExitCodeError {
-        Foundation.exit(execCustomExitCodeError.exitCode)
-      }
-
-      // Capture the error into Sentry
-      SentrySDK.capture(error: error)
-      SentrySDK.flush(timeout: 2.seconds.timeInterval)
-
-      // Handle a non-ArgumentParser's exception that requires a specific exit code to be set
-      if let errorWithExitCode = error as? HasExitCode {
-        fputs("\(error)\n", stderr)
-
-        Foundation.exit(errorWithExitCode.exitCode)
-      }
-
-      // Handle any other exception, including ArgumentParser's ones
       exit(withError: error)
     }
+
+    if let mainThreadCommand = command as? MainThreadCommand {
+      // This command drives a run loop on the main thread, so run it right here,
+      // letting it own the main thread at the top level.
+      MainActor.assumeIsolated {
+        runOnMainThread(mainThreadCommand)
+      }
+    } else {
+      // Every other command is asynchronous and doesn't touch the main thread, so
+      // drive it from a detached task and let the Dispatch main queue keep the
+      // process alive until the command exits.
+      let task = Task.detached {
+        await runInBackground(command)
+      }
+
+      // Handle cancellation by Ctrl+C ourselves
+      let sigintSrc = DispatchSource.makeSignalSource(signal: SIGINT)
+      sigintSrc.setEventHandler {
+        task.cancel()
+      }
+      sigintSrc.activate()
+
+      dispatchMain()
+    }
   }
 
-  private static func parseCirrusSentryTag(_ tag: String.SubSequence) -> (String, String)? {
+  @MainActor
+  private static func runOnMainThread(_ command: MainThreadCommand) {
+    let span = startCommandSpan(for: command)
+    runGarbageCollection(for: command)
+
+    do {
+      // Enters the run loop and only returns once the command exits via
+      // Foundation.exit(), so the lines below are a best-effort fallback.
+      try command.runOnMainThread()
+    } catch {
+      handleError(error, span: span)
+    }
+
+    span.end()
+    OTel.shared.flush()
+    Foundation.exit(0)
+  }
+
+  private static func runInBackground(_ command: ParsableCommand) async {
+    let span = startCommandSpan(for: command)
+    runGarbageCollection(for: command)
+
+    do {
+      if var asyncCommand = command as? AsyncParsableCommand {
+        try await asyncCommand.run()
+      } else {
+        var command = command
+        try command.run()
+      }
+    } catch {
+      handleError(error, span: span)
+    }
+
+    span.end()
+    OTel.shared.flush()
+    Foundation.exit(0)
+  }
+
+  // Create a root span for the command we're about to run.
+  private static func startCommandSpan(for command: ParsableCommand) -> Span {
+    let span = OTel.shared.tracer.spanBuilder(spanName: type(of: command)._commandName).startSpan()
+    OpenTelemetry.instance.contextProvider.setActiveSpan(span)
+
+    // Enrich root command span with command's arguments
+    let commandLineArguments = ProcessInfo.processInfo.arguments.map { argument in
+      AttributeValue.string(argument)
+    }
+    span.setAttribute(key: "Command-line arguments", value: .array(AttributeArray(values: commandLineArguments)))
+
+    // Enrich root command span with Cirrus CI-specific tags
+    if let tags = ProcessInfo.processInfo.environment["CIRRUS_SENTRY_TAGS"] {
+      for (key, value) in tags.split(separator: ",").compactMap(splitEnvironmentVariable) {
+        span.setAttribute(key: key, value: .string(value))
+      }
+    }
+
+    return span
+  }
+
+  // Run garbage-collection before each command (shouldn't take too long).
+  private static func runGarbageCollection(for command: ParsableCommand) {
+    if type(of: command) != type(of: Pull()) && type(of: command) != type(of: Clone()) {
+      do {
+        try Config().gc()
+      } catch {
+        fputs("Failed to perform garbage collection: \(error)\n", stderr)
+      }
+    }
+  }
+
+  private static func handleError(_ error: Error, span: Span) -> Never {
+    // Not an error, just a custom exit code from "tart exec"
+    if let execCustomExitCodeError = error as? ExecCustomExitCodeError {
+      span.end()
+      OTel.shared.flush()
+      Foundation.exit(execCustomExitCodeError.exitCode)
+    }
+
+    // Capture the error into OpenTelemetry
+    OpenTelemetry.instance.contextProvider.activeSpan?.recordException(error)
+    span.end()
+
+    // Handle a non-ArgumentParser's exception that requires a specific exit code to be set
+    if let errorWithExitCode = error as? HasExitCode {
+      fputs("\(error)\n", stderr)
+
+      OTel.shared.flush()
+      Foundation.exit(errorWithExitCode.exitCode)
+    }
+
+    // Handle any other exception, including ArgumentParser's ones
+    OTel.shared.flush()
+    exit(withError: error)
+  }
+
+  private static func splitEnvironmentVariable(_ tag: String.SubSequence) -> (String, String)? {
     let splits = tag.split(separator: "=", maxSplits: 1)
     if splits.count != 2 {
       return nil
@@ -133,3 +194,10 @@ struct Root: AsyncParsableCommand {
     return (String(splits[0]), String(splits[1]))
   }
 }
+
+// A command that drives an AppKit/SwiftUI run loop and therefore has to own the
+// main thread at the top level, rather than running inside Swift's asynchronous
+// main() executor. See Root.main() for the rationale.
+protocol MainThreadCommand: ParsableCommand {
+  @MainActor func runOnMainThread() throws
+}

Sources/tart/Utils.swift

@@ -1,5 +1,23 @@
 import Foundation
 
+// A fire-and-forget task that reports any thrown error to stderr. An unstructured
+// Task spawned from a synchronous context (a signal handler, a SwiftUI action) has
+// no parent to propagate its error to, so we report it here instead of dropping it.
+struct ErrorReportingTask {
+  let task: Task<Void, Never>
+
+  @discardableResult
+  init(_ context: String, operation: @escaping @Sendable () async throws -> Void) {
+    task = Task {
+      do {
+        try await operation()
+      } catch {
+        fputs("\(context): \(error)\n", stderr)
+      }
+    }
+  }
+}
+
 extension Collection {
   subscript (safe index: Index) -> Element? {
     indices.contains(index) ? self[index] : nil

Sources/tart/VM.swift

@@ -51,7 +51,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
        clipboard: Bool = true,
        sync: VZDiskImageSynchronizationMode = .full,
        caching: VZDiskImageCachingMode? = nil,
-       noTrackpad: Bool = false
+       noTrackpad: Bool = false,
+       noPointer: Bool = false,
+       noKeyboard: Bool = false
   ) throws {
     name = vmDir.name
     config = try VMConfig.init(fromURL: vmDir.configURL)
@@ -62,7 +64,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
     // Initialize the virtual machine and its configuration
     self.network = network
-    configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL,
+    configuration = try Self.craftConfiguration(vmDir: vmDir,
                                                 nvramURL: vmDir.nvramURL, vmConfig: config,
                                                 network: network, additionalStorageDevices: additionalStorageDevices,
                                                 directorySharingDevices: directorySharingDevices,
@@ -73,7 +75,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
                                                 clipboard: clipboard,
                                                 sync: sync,
                                                 caching: caching,
-                                                noTrackpad: noTrackpad
+                                                noTrackpad: noTrackpad,
+                                                noPointer: noPointer,
+                                                noKeyboard: noKeyboard
     )
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
@@ -192,7 +196,8 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
       // Initialize the virtual machine and its configuration
       self.network = network
-      configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, nvramURL: vmDir.nvramURL,
+      configuration = try Self.craftConfiguration(vmDir: vmDir,
+                                                  nvramURL: vmDir.nvramURL,
                                                   vmConfig: config, network: network,
                                                   additionalStorageDevices: additionalStorageDevices,
                                                   directorySharingDevices: directorySharingDevices,
@@ -240,13 +245,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     return try VM(vmDir: vmDir)
   }
 
-  func start(recovery: Bool, resume shouldResume: Bool) async throws {
+  func start(recovery: Bool, resume shouldResume: Bool, provisioning: GuestProvisioningOptions? = nil) async throws {
     try network.run(sema)
 
     if shouldResume {
       try await resume()
     } else {
-      try await start(recovery)
+      try await start(recovery, provisioning: provisioning)
     }
   }
 
@@ -282,10 +287,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   }
 
   @MainActor
-  private func start(_ recovery: Bool) async throws {
+  private func start(_ recovery: Bool, provisioning: GuestProvisioningOptions? = nil) async throws {
     #if arch(arm64)
       let startOptions = VZMacOSVirtualMachineStartOptions()
       startOptions.startUpFromMacOSRecovery = recovery
+      #if compiler(>=6.4)
+        if let provisioning = provisioning, #available(macOS 27, *) {
+          try startOptions.setGuestProvisioning(provisioning.toVZMacGuestProvisioningOptions())
+        }
+      #endif
       try await virtualMachine.start(options: startOptions)
     #else
       try await virtualMachine.start()
@@ -303,7 +313,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   }
 
   static func craftConfiguration(
-    diskURL: URL,
+    vmDir: VMDirectory,
     nvramURL: URL,
     vmConfig: VMConfig,
     network: Network = NetworkShared(),
@@ -316,7 +326,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     clipboard: Bool = true,
     sync: VZDiskImageSynchronizationMode = .full,
     caching: VZDiskImageCachingMode? = nil,
-    noTrackpad: Bool = false
+    noTrackpad: Bool = false,
+    noPointer: Bool = false,
+    noKeyboard: Bool = false
   ) throws -> VZVirtualMachineConfiguration {
     let configuration = VZVirtualMachineConfiguration()
 
@@ -356,8 +368,16 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       configuration.keyboards = platformSuspendable.keyboardsSuspendable()
       configuration.pointingDevices = platformSuspendable.pointingDevicesSuspendable()
     } else {
-      configuration.keyboards = vmConfig.platform.keyboards()
-      if noTrackpad {
+
+      if noKeyboard {
+        configuration.keyboards = []
+      } else {
+        configuration.keyboards = vmConfig.platform.keyboards()
+      }
+
+      if noPointer {
+        configuration.pointingDevices = []
+      } else if noTrackpad {
         configuration.pointingDevices = vmConfig.platform.pointingDevicesSimplified()
       } else {
         configuration.pointingDevices = vmConfig.platform.pointingDevices()
@@ -385,15 +405,25 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     // Storage
-    var attachment = try VZDiskImageStorageDeviceAttachment(
-      url: diskURL,
-      readOnly: false,
-      // When not specified, use "cached" caching mode for Linux VMs to prevent file-system corruption[1]
-      //
-      // [1]: https://github.com/cirruslabs/tart/pull/675
-      cachingMode: caching ?? (vmConfig.os == .linux ? .cached : .automatic),
-      synchronizationMode: sync
-    )
+    // When not specified, use "cached" caching mode for Linux VMs to prevent file-system corruption[1]
+    //
+    // [1]: https://github.com/cirruslabs/tart/pull/675
+    let cachingMode = caching ?? (vmConfig.os == .linux ? .cached : .automatic)
+    let attachment: VZStorageDeviceAttachment
+    if vmDir.isStackedVM {
+      attachment = try vmDir.diskImageStack().makeAttachment(
+        readOnly: false,
+        cachingMode: cachingMode,
+        synchronizationMode: sync
+      )
+    } else {
+      attachment = try VZDiskImageStorageDeviceAttachment(
+        url: vmDir.diskURL,
+        readOnly: false,
+        cachingMode: cachingMode,
+        synchronizationMode: sync
+      )
+    }
 
     var devices: [VZStorageDeviceConfiguration] = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]
     devices.append(contentsOf: additionalStorageDevices)

Sources/tart/VMConfig.swift

@@ -32,14 +32,24 @@ enum CodingKeys: String, CodingKey {
   case hardwareModel
 }
 
-struct VMDisplayConfig: Codable {
+struct VMDisplayConfig: Codable, Equatable {
+  enum Unit: String, Codable {
+    case point = "pt"
+    case pixel = "px"
+  }
+
   var width: Int = 1024
   var height: Int = 768
+  var unit: Unit?
 }
 
 extension VMDisplayConfig: CustomStringConvertible {
   var description: String {
-    "\(width)x\(height)"
+    if let unit {
+      "\(width)x\(height)\(unit.rawValue)"
+    } else {
+      "\(width)x\(height)"
+    }
   }
 }
 

Sources/tart/VMDirectory+Archive.swift

@@ -1,3 +1,4 @@
+import Foundation
 import System
 import AppleArchive
 
@@ -10,6 +11,16 @@ fileprivate let permissions = FilePermissions(rawValue: 0o644)
 // [2]: https://developer.apple.com/documentation/compression/algorithm/lzfse
 extension VMDirectory {
   func exportToArchive(path: String) throws {
+    let temporaryArchive = try stackedArchiveDirectoryIfNeeded()
+    let archiveSourceURL = temporaryArchive?.vmDirectory.baseURL ?? baseURL
+
+    defer {
+      if let temporaryArchive {
+        try? temporaryArchive.lock.unlock()
+        try? temporaryArchive.vmDirectory.removeFromDisk()
+      }
+    }
+
     guard let fileStream = ArchiveByteStream.fileStream(
       path: FilePath(path),
       mode: .writeOnly,
@@ -49,7 +60,7 @@ extension VMDirectory {
       return
     }
 
-    try encodeStream.writeDirectoryContents(archiveFrom: FilePath(baseURL.path), keySet: keySet)
+    try encodeStream.writeDirectoryContents(archiveFrom: FilePath(archiveSourceURL.path), keySet: keySet)
   }
 
   func importFromArchive(path: String) throws {
@@ -92,5 +103,145 @@ extension VMDirectory {
     }
 
     _ = try ArchiveStream.process(readingFrom: decodeStream, writingTo: extractStream)
+
+    if isStackedVM {
+      try restoreStackedArchive()
+    }
   }
+
+  /// Builds a self-contained staging directory for a stacked archive, if this
+  /// directory currently resolves to a stacked VM or cached image.
+  private func stackedArchiveDirectoryIfNeeded() throws -> (vmDirectory: VMDirectory, lock: FileLock)? {
+    guard isStackedVM || isStackedCachedImage else {
+      return nil
+    }
+    try DiskImageStack.requireSupport()
+
+    let contentStore = try ContentStore()
+    let archiveVMDir = try VMDirectory.temporary()
+    let archiveVMDirLock = try FileLock(lockURL: archiveVMDir.baseURL)
+    try archiveVMDirLock.lock()
+
+    do {
+      let stagedSource: (isStackedVM: Bool, contentDigests: [String])? = try contentStore.withPruneLock {
+        () -> (isStackedVM: Bool, contentDigests: [String])? in
+        // OCI tags are mutable symlinks. Resolve one digest record while tag
+        // replacement and cached-image deletion are blocked, then copy every
+        // source-owned file before releasing the lock.
+        let sourceVMDir = VMDirectory(baseURL: baseURL.resolvingSymlinksInPath())
+        guard sourceVMDir.isStackedVM || sourceVMDir.isStackedCachedImage else {
+          throw RuntimeError.ExportFailed("VM changed while preparing export, retry the command")
+        }
+
+        let sourceIsStackedVM = sourceVMDir.isStackedVM
+        let sourceVMLock: PIDLock?
+        if sourceIsStackedVM {
+          let lock = try sourceVMDir.lock()
+          guard try lock.trylock() else {
+            throw RuntimeError.ExportFailed("VM \"\(sourceVMDir.name)\" must be stopped before export")
+          }
+          sourceVMLock = lock
+
+          // Holding the PID lock proves that the VM is not running. A saved
+          // state file is the remaining suspended state that must reject export.
+          guard !FileManager.default.fileExists(atPath: sourceVMDir.stateURL.path) else {
+            try? lock.unlock()
+            throw RuntimeError.ExportFailed("VM \"\(sourceVMDir.name)\" must be stopped before export")
+          }
+        } else {
+          sourceVMLock = nil
+        }
+        defer { try? sourceVMLock?.unlock() }
+
+        try FileManager.default.copyItem(at: sourceVMDir.configURL, to: archiveVMDir.configURL)
+        try FileManager.default.copyItem(at: sourceVMDir.nvramURL, to: archiveVMDir.nvramURL)
+        try FileManager.default.copyItem(at: sourceVMDir.manifestURL, to: archiveVMDir.manifestURL)
+        if sourceIsStackedVM {
+          try FileManager.default.copyItem(at: sourceVMDir.overlayURL, to: archiveVMDir.overlayURL)
+        }
+
+        return (sourceIsStackedVM, try archiveVMDir.diskContentDigests())
+      }
+
+      guard let stagedSource else {
+        try archiveVMDirLock.unlock()
+        try archiveVMDir.removeFromDisk()
+        return nil
+      }
+
+      if !stagedSource.isStackedVM {
+        try archiveVMDir.diskImageStack().createWritableOverlay()
+      }
+
+      // The staged manifest is now an in-progress reference, so immutable
+      // content remains protected while these potentially large copies run
+      // without holding the global prune lock.
+      for contentDigest in stagedSource.contentDigests {
+        guard let sourceURL = try contentStore.existingContentURL(for: contentDigest) else {
+          throw RuntimeError.ExportFailed("VM is missing cached disk content \(contentDigest)")
+        }
+
+        let destinationURL = try contentStore.contentURL(
+          for: contentDigest,
+          under: archiveContentStoreURL(in: archiveVMDir)
+        )
+        try FileManager.default.createDirectory(
+          at: destinationURL.deletingLastPathComponent(),
+          withIntermediateDirectories: true
+        )
+        try FileManager.default.copyItem(at: sourceURL, to: destinationURL)
+      }
+
+      return (archiveVMDir, archiveVMDirLock)
+    } catch {
+      try? archiveVMDirLock.unlock()
+      try? archiveVMDir.removeFromDisk()
+      throw error
+    }
+  }
+
+  /// Restores immutable files from an archive into the shared content store,
+  /// removes the archive-only payload, then validates the resulting stack.
+  private func restoreStackedArchive() throws {
+    try DiskImageStack.requireSupport()
+
+    let contentStore = try ContentStore()
+    // The extracted manifest is already a reference; synchronize publication
+    // with a concurrent prune before installing its immutable content.
+    try contentStore.synchronizePublishedReferences()
+    for contentDigest in try diskContentDigests() {
+      if try contentStore.existingContentURL(for: contentDigest) != nil {
+        continue
+      }
+
+      let archivedContentURL = try contentStore.contentURL(
+        for: contentDigest,
+        under: archiveContentStoreURL(in: self)
+      )
+      guard FileManager.default.fileExists(atPath: archivedContentURL.path) else {
+        throw RuntimeError.ImportFailed("archive is missing disk content \(contentDigest)")
+      }
+
+      let temporaryURL = try contentStore.temporaryContentURL(for: contentDigest)
+      do {
+        try FileManager.default.copyItem(at: archivedContentURL, to: temporaryURL)
+        _ = try contentStore.install(temporaryURL, contentDigest: contentDigest)
+      } catch {
+        try? FileManager.default.removeItem(at: temporaryURL)
+        throw error
+      }
+    }
+
+    try FileManager.default.removeItem(at: archiveContentStoreURL(in: self))
+    try? FileManager.default.removeItem(at: stateURL)
+
+    // Opening the attachment validates the reconstructed immutable stack and
+    // imported writable overlay before the VM enters local storage.
+    _ = try diskImageStack().makeAttachment()
+  }
+
+  private func archiveContentStoreURL(in vmDir: VMDirectory) -> URL {
+    vmDir.baseURL.appendingPathComponent("content", isDirectory: true)
+  }
+
 }

Sources/tart/VMDirectory+DiskImageStack.swift

@@ -0,0 +1,142 @@
+import Foundation
+
+extension VMDirectory {
+  /// Returns content-store digests needed to reconstruct this VM's disk stack.
+  func diskContentDigests() throws -> [String] {
+    let manifest = try OCIManifest(fromJSON: Data(contentsOf: manifestURL))
+    return try manifest.diskContentDigests()
+  }
+
+  func diskImageStack(contentStore providedStore: ContentStore? = nil) throws -> DiskImageStack {
+    let manifest = try OCIManifest(fromJSON: Data(contentsOf: manifestURL))
+    let base: TartDiskFileGroup
+    let overlays: [TartDiskFileGroup]
+
+    switch try manifest.tartDiskRepresentation() {
+    case .flat(let pinnedBase) where pinnedBase.contentDigest != nil:
+      base = pinnedBase
+      overlays = []
+    case .stacked(let stackedBase, let stackedOverlays):
+      base = stackedBase
+      overlays = stackedOverlays
+    default:
+      throw RuntimeError.VMConfigurationError("VM is missing its disk image metadata")
+    }
+    guard let blockSize = manifest.diskBlockSize(),
+          let blockCount = manifest.diskBlockCount() else {
+      throw DiskImageStackError.invalidBlockLayout("disk image metadata is missing block layout")
+    }
+
+    let contentStore = try providedStore ?? ContentStore()
+    let baseURL = try diskImageURL(for: base, contentStore: contentStore)
+    let immutableOverlayURLs = try overlays.map { try diskImageURL(for: $0, contentStore: contentStore) }
+    let config = try VMConfig(fromURL: configURL)
+
+    return DiskImageStack(
+      baseURL: baseURL,
+      baseFormat: config.diskFormat,
+      immutableOverlayURLs: immutableOverlayURLs,
+      writableOverlayURL: overlayURL,
+      blockSize: blockSize,
+      blockCount: blockCount
+    )
+  }
+
+  func cloneStacked(
+    to destination: VMDirectory,
+    copyWritableOverlay: Bool,
+    generateMAC: Bool,
+    contentStore: ContentStore? = nil
+  ) throws {
+    let contentStore = try contentStore ?? ContentStore()
+    try contentStore.withPruneLock {
+      try FileManager.default.copyItem(at: configURL, to: destination.configURL)
+      try FileManager.default.copyItem(at: nvramURL, to: destination.nvramURL)
+      try FileManager.default.copyItem(at: manifestURL, to: destination.manifestURL)
+
+      if copyWritableOverlay {
+        try FileManager.default.copyItem(at: overlayURL, to: destination.overlayURL)
+      }
+    }
+
+    if !copyWritableOverlay {
+      try destination.diskImageStack(contentStore: contentStore).createWritableOverlay()
+    }
+
+    if generateMAC {
+      try destination.regenerateMACAddress()
+    }
+  }
+
+  func cloneAsStackedBase(
+    to destination: VMDirectory,
+    generateMAC: Bool,
+    contentStore providedStore: ContentStore? = nil
+  ) throws {
+    let config = try VMConfig(fromURL: configURL)
+    let blockLayout = try DiskImageStack.baseBlockLayout(at: diskURL, expectedFormat: config.diskFormat)
+    let contentDigest = try Digest.hash(diskURL)
+    let contentStore = try providedStore ?? ContentStore()
+
+    var manifest = try OCIManifest(fromJSON: Data(contentsOf: manifestURL))
+    guard case .flat = try manifest.tartDiskRepresentation() else {
+      throw RuntimeError.VMConfigurationError("--stacked cannot use an image that already has a stacked disk")
+    }
+
+    guard let firstDiskIndex = manifest.layers.firstIndex(where: { $0.mediaType == diskV2MediaType }) else {
+      throw OCIManifestValidationError.invalidLayout("manifest must contain at least one disk chunk")
+    }
+
+    var baseAnnotations = manifest.layers[firstDiskIndex].annotations ?? [:]
+    baseAnnotations[diskFileContentDigestAnnotation] = contentDigest
+    manifest.layers[firstDiskIndex].annotations = baseAnnotations
+    let diskSize = blockLayout.blockSize.multipliedReportingOverflow(by: blockLayout.blockCount)
+    guard !diskSize.overflow else {
+      throw DiskImageStackError.invalidBlockLayout("stacked disk block layout overflows UInt64")
+    }
+    var annotations = manifest.annotations ?? [:]
+    annotations[diskBlockSizeAnnotation] = String(blockLayout.blockSize)
+    annotations[uncompressedDiskSizeAnnotation] = String(diskSize.partialValue)
+    manifest.annotations = annotations
+
+    try FileManager.default.copyItem(at: configURL, to: destination.configURL)
+    try FileManager.default.copyItem(at: nvramURL, to: destination.nvramURL)
+    try contentStore.withPruneLock {
+      try manifest.toJSON().write(to: destination.manifestURL)
+    }
+
+    // Publish the temporary VM's manifest before installing the shared base.
+    // Reference-aware pruning includes in-progress manifests, so the content
+    // cannot be collected in the window before this VM is moved into place.
+    if try contentStore.contentURLIfPresent(for: contentDigest) == nil {
+      let temporaryURL = try contentStore.temporaryContentURL(for: contentDigest)
+      do {
+        try FileManager.default.copyItem(at: diskURL, to: temporaryURL)
+        _ = try contentStore.install(temporaryURL, contentDigest: contentDigest)
+      } catch {
+        try? FileManager.default.removeItem(at: temporaryURL)
+        throw error
+      }
+    }
+
+    try destination.diskImageStack(contentStore: contentStore).createWritableOverlay()
+
+    if generateMAC {
+      try destination.regenerateMACAddress()
+    }
+  }
+
+  private func diskImageURL(for group: TartDiskFileGroup, contentStore: ContentStore) throws -> URL {
+    guard let contentDigest = group.contentDigest else {
+      throw OCIManifestValidationError.invalidDiskMetadata("stacked disk files need a whole-file content digest")
+    }
+    // Pull/install verifies immutable content before publishing it. Clone and
+    // run use the trusted content-addressed entry without rereading a possibly
+    // very large disk file, matching Tart's existing disk.img behavior.
+    guard let url = try contentStore.contentURLIfPresent(for: contentDigest) else {
+      throw RuntimeError.VMMissingFiles("VM is missing cached disk content \(contentDigest)")
+    }
+
+    return url
+  }
+}

Sources/tart/VMDirectory+OCI.swift

@@ -1,10 +1,11 @@
 import Compression
 import Foundation
-import Sentry
+import OpenTelemetryApi
+
+let legacyDiskV1MediaType = "application/vnd.cirruslabs.tart.disk.v1"
 
 enum OCIError: Error {
   case ShouldBeExactlyOneLayer
-  case ShouldBeAtLeastOneLayer
   case FailedToCreateVmFile
   case LayerIsMissingUncompressedSizeAnnotation
   case LayerIsMissingUncompressedDigestAnnotation
@@ -12,7 +13,7 @@ enum OCIError: Error {
 
 extension VMDirectory {
   func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt, localLayerCache: LocalLayerCache?, deduplicate: Bool) async throws {
-    // Pull VM's config file layer and re-serialize it into a config file
+    // Pull VM's config file layer and store it as the local config file.
     let configLayers = manifest.layers.filter {
       $0.mediaType == configMediaType
     }
@@ -28,22 +29,26 @@ extension VMDirectory {
     }
     try configFile.close()
 
-    // Pull VM's disk layers and decompress them into a disk file
-    let diskImplType: Disk.Type
-    let layers: [OCIManifestLayer]
-
-    if manifest.layers.contains(where: { $0.mediaType == diskV1MediaType }) {
-      diskImplType = DiskV1.self
-      layers = manifest.layers.filter { $0.mediaType == diskV1MediaType }
-    } else if manifest.layers.contains(where: { $0.mediaType == diskV2MediaType }) {
-      diskImplType = DiskV2.self
-      layers = manifest.layers.filter { $0.mediaType == diskV2MediaType }
-    } else {
-      throw OCIError.ShouldBeAtLeastOneLayer
+    // Pull VM's disk chunks and decompress them into complete disk files.
+    if manifest.layers.contains(where: { $0.mediaType == legacyDiskV1MediaType }) {
+      throw RuntimeError.Generic("Pulling OCI images with legacy disk media type \(legacyDiskV1MediaType) is no longer supported, please re-push the image using a current Tart version")
     }
 
-    let diskCompressedSize = layers.map { Int64($0.size) }.reduce(0, +)
-    SentrySDK.span?.setMeasurement(name: "compressed_disk_size", value: diskCompressedSize as NSNumber, unit: MeasurementUnitInformation.byte)
+    let diskRepresentation = try manifest.tartDiskRepresentation()
+    let diskChunks: [OCIManifestLayer]
+
+    switch diskRepresentation {
+    case .flat(let base):
+      diskChunks = base.chunks
+    case .stacked(let base, let overlays):
+      diskChunks = base.chunks + overlays.flatMap(\.chunks)
+    }
+
+    let diskCompressedSize = diskChunks.map { Int64($0.size) }.reduce(0, +)
+    OpenTelemetry.instance.contextProvider.activeSpan?.setAttribute(
+      key: "compressed_disk_size_bytes",
+      value: .int(Int(diskCompressedSize))
+    )
 
     let prettyDiskSize = String(format: "%.1f", Double(diskCompressedSize) / 1_000_000_000.0)
     defaultLogger.appendNewLine("pulling disk (\(prettyDiskSize) GB compressed)...")
@@ -52,19 +57,42 @@ extension VMDirectory {
     ProgressObserver(progress).log(defaultLogger)
 
     do {
-      try await diskImplType.pull(registry: registry, diskLayers: layers, diskURL: diskURL,
-                                  concurrency: concurrency, progress: progress,
-                                  localLayerCache: localLayerCache,
-                                  deduplicate: deduplicate)
+      switch diskRepresentation {
+      case .flat(let base):
+        try await DiskV2.pull(registry: registry, diskLayers: base.chunks, diskURL: diskURL,
+                              concurrency: concurrency, progress: progress,
+                              localLayerCache: localLayerCache,
+                              deduplicate: deduplicate)
+
+        if deduplicate, let llc = localLayerCache {
+          // set custom attribute to remember deduplicated bytes
+          diskURL.setDeduplicatedBytes(llc.deduplicatedBytes)
+        }
+      case .stacked(let base, let overlays):
+        // The deterministic resumable directory may contain a partial
+        // disk.img from an interrupted pull while this tag was standalone. A
+        // cached stacked image must not retain that file or it is mistaken for
+        // a standalone VM after the pull is moved into cache.
+        if FileManager.default.fileExists(atPath: diskURL.path) {
+          try FileManager.default.removeItem(at: diskURL)
+        }
+
+        let contentStore = try ContentStore()
+
+        for group in [base] + overlays {
+          _ = try await pullDiskFile(
+            registry: registry,
+            group: group,
+            contentStore: contentStore,
+            concurrency: concurrency,
+            progress: progress
+          )
+        }
+      }
     } catch let error where error is FilterError {
       throw RuntimeError.PullFailed("failed to decompress disk: \(error.localizedDescription)")
     }
 
-    if deduplicate, let llc = localLayerCache {
-      // set custom attribute to remember deduplicated bytes
-      diskURL.setDeduplicatedBytes(llc.deduplicatedBytes)
-    }
-
     // Pull VM's NVRAM file layer and store it in an NVRAM file
     defaultLogger.appendNewLine("pulling NVRAM...")
 
@@ -82,12 +110,50 @@ extension VMDirectory {
       try nvram.write(contentsOf: data)
     }
     try nvram.close()
-
-    // Serialize VM's manifest to enable better deduplication on subsequent "tart pull"'s
-    try manifest.toJSON().write(to: manifestURL)
   }
 
-  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int, diskFormat: String, concurrency: UInt, labels: [String: String] = [:]) async throws -> RemoteName {
+  /// Reconstructs one complete immutable base disk or published ASIF overlay
+  /// from its Tart disk chunks, unless the shared content store already has a
+  /// size-matching copy.
+  private func pullDiskFile(
+    registry: Registry,
+    group: TartDiskFileGroup,
+    contentStore: ContentStore,
+    concurrency: UInt,
+    progress: Progress
+  ) async throws -> URL {
+    guard let contentDigest = group.contentDigest else {
+      throw OCIManifestValidationError.invalidDiskMetadata("stacked disk files need a whole-file content digest")
+    }
+
+    // Pulls for the same semantic disk file share a stable resumable path so
+    // DiskV2 can resume after a transient failure. Serialize writers before
+    // rechecking the final entry to avoid racing on that shared path.
+    let lock = try FileLock(lockURL: contentStore.lockURL(for: contentDigest))
+    try lock.lock()
+    defer { try? lock.unlock() }
+
+    if let existingURL = try contentStore.contentURLIfPresent(for: contentDigest),
+       let actualSize = UInt64(exactly: try existingURL.sizeBytes()),
+       let expectedSize = group.uncompressedSize(),
+       actualSize == expectedSize {
+      progress.completedUnitCount += group.chunks.reduce(0) { $0 + Int64($1.size) }
+      return existingURL
+    }
+
+    let resumableURL = try contentStore.resumableContentURL(for: contentDigest)
+    try await DiskV2.pull(
+      registry: registry,
+      diskLayers: group.chunks,
+      diskURL: resumableURL,
+      concurrency: concurrency,
+      progress: progress
+    )
+
+    return try contentStore.install(resumableURL, contentDigest: contentDigest)
+  }
+
+  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int, concurrency: UInt, labels: [String: String] = [:]) async throws -> (name: RemoteName, manifest: OCIManifest) {
     var layers = Array<OCIManifestLayer>()
 
     // Read VM's config and push it as blob
@@ -101,21 +167,12 @@ extension VMDirectory {
     let configDigest = try await registry.pushBlob(fromData: configJSON, chunkSizeMb: chunkSizeMb)
     layers.append(OCIManifestLayer(mediaType: configMediaType, size: configJSON.count, digest: configDigest))
 
-    // Compress the disk file as multiple chunks and push them as disk layers
-    let diskSize = try FileManager.default.attributesOfItem(atPath: diskURL.path)[.size] as! Int64
-
-    defaultLogger.appendNewLine("pushing disk... this will take a while...")
-    let progress = Progress(totalUnitCount: diskSize)
-    ProgressObserver(progress).log(defaultLogger)
-
-    switch diskFormat {
-    case "v1":
-      layers.append(contentsOf: try await DiskV1.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, concurrency: concurrency, progress: progress))
-    case "v2":
-      layers.append(contentsOf: try await DiskV2.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, concurrency: concurrency, progress: progress))
-    default:
-      throw RuntimeError.OCIUnsupportedDiskFormat(diskFormat)
-    }
+    let (diskLayers, diskAnnotations) = try await pushDiskLayers(
+      registry: registry,
+      chunkSizeMb: chunkSizeMb,
+      concurrency: concurrency
+    )
+    layers.append(contentsOf: diskLayers)
 
     // Read VM's NVRAM and push it as blob
     defaultLogger.appendNewLine("pushing NVRAM...")
@@ -128,13 +185,13 @@ extension VMDirectory {
     let ociConfigContainer = OCIConfig.ConfigContainer(Labels: labels)
     let ociConfigJSON = try OCIConfig(architecture: config.arch, os: config.os, config: ociConfigContainer).toJSON()
     let ociConfigDigest = try await registry.pushBlob(fromData: ociConfigJSON, chunkSizeMb: chunkSizeMb)
-    let manifest = OCIManifest(
+    var manifest = OCIManifest(
       config: OCIManifestConfig(size: ociConfigJSON.count, digest: ociConfigDigest),
-      layers: layers,
-      uncompressedDiskSize: UInt64(diskSize),
-      uploadDate: Date()
+      layers: layers
     )
-
+    var annotations = diskAnnotations
+    annotations[uploadTimeAnnotation] = Date().toISO()
+    manifest.annotations = annotations
     // Manifest
     for reference in references {
       defaultLogger.appendNewLine("pushing manifest for \(reference)...")
@@ -143,7 +200,158 @@ extension VMDirectory {
     }
 
     let pushedReference = Reference(digest: try manifest.digest())
-    return RemoteName(host: registry.host!, namespace: registry.namespace, reference: pushedReference)
+    let name = RemoteName(host: registry.host!, namespace: registry.namespace, reference: pushedReference)
+    return (name, manifest)
+  }
+
+  /// Builds the disk portion of the manifest. Registry transport is shared
+  /// for standalone and stacked VMs; only their local disk representation
+  /// determines which descriptors need to be uploaded or reused.
+  private func pushDiskLayers(
+    registry: Registry,
+    chunkSizeMb: Int,
+    concurrency: UInt
+  ) async throws -> ([OCIManifestLayer], [String: String]) {
+    guard isStackedVM else {
+      let diskSize = try FileManager.default.attributesOfItem(atPath: diskURL.path)[.size] as! Int64
+      defaultLogger.appendNewLine("pushing disk... this will take a while...")
+      let progress = Progress(totalUnitCount: diskSize)
+      ProgressObserver(progress).log(defaultLogger)
+
+      let layers = try await DiskV2.push(
+        diskURL: diskURL,
+        mediaType: diskV2MediaType,
+        registry: registry,
+        chunkSizeMb: chunkSizeMb,
+        concurrency: concurrency,
+        progress: progress
+      )
+      return (layers, [uncompressedDiskSizeAnnotation: String(diskSize)])
+    }
+
+    let localManifest = try OCIManifest(fromJSON: Data(contentsOf: manifestURL))
+    // pushToRegistry() reads config.json before reaching this point. Closing
+    // that read descriptor can release the caller's fcntl PID lock, so take a
+    // fresh lock before hashing, uploading, and inspecting the writable overlay.
+    let stackedDiskLock = try lock()
+    guard try stackedDiskLock.trylock() else {
+      throw RuntimeError.VMIsRunning(name)
+    }
+    defer { try? stackedDiskLock.unlock() }
+
+    let inheritedGroups: [TartDiskFileGroup]
+    switch try localManifest.tartDiskRepresentation() {
+    case .flat(let base) where base.contentDigest != nil:
+      inheritedGroups = [base]
+    case .stacked(let base, let overlays):
+      inheritedGroups = [base] + overlays
+    default:
+      throw RuntimeError.VMConfigurationError("stacked VM is missing a pinned disk stack")
+    }
+
+    let contentStore = try ContentStore()
+    var layers: [OCIManifestLayer] = []
+    for group in inheritedGroups {
+      layers.append(contentsOf: try await descriptorsForCachedDiskFile(
+        group,
+        contentStore: contentStore,
+        registry: registry,
+        chunkSizeMb: chunkSizeMb,
+        concurrency: concurrency
+      ))
+    }
+
+    let overlaySize = try FileManager.default.attributesOfItem(atPath: overlayURL.path)[.size] as! Int64
+    defaultLogger.appendNewLine("pushing overlay...")
+    let progress = Progress(totalUnitCount: overlaySize)
+    ProgressObserver(progress).log(defaultLogger)
+    let contentDigest = try Digest.hash(overlayURL)
+    let chunks = try await DiskV2.push(
+      diskURL: overlayURL,
+      mediaType: asifOverlayMediaType,
+      registry: registry,
+      chunkSizeMb: chunkSizeMb,
+      concurrency: concurrency,
+      progress: progress
+    )
+    layers.append(contentsOf: annotatedChunks(chunks, kind: .asifOverlay, contentDigest: contentDigest))
+
+    let blockLayout = try DiskImageStack.diskImageBlockLayout(at: overlayURL)
+    let diskSize = blockLayout.blockSize.multipliedReportingOverflow(by: blockLayout.blockCount)
+    guard !diskSize.overflow else {
+      throw DiskImageStackError.invalidBlockLayout("stacked disk block layout overflows UInt64")
+    }
+
+    var annotations = localManifest.annotations ?? [:]
+    annotations[diskBlockSizeAnnotation] = String(blockLayout.blockSize)
+    annotations[uncompressedDiskSizeAnnotation] = String(diskSize.partialValue)
+
+    return (layers, annotations)
+  }
+
+  /// Returns transport descriptors for an immutable disk file. If the
+  /// target registry lacks the original blobs, recreate them from the local
+  /// content store.
+  private func descriptorsForCachedDiskFile(
+    _ group: TartDiskFileGroup,
+    contentStore: ContentStore,
+    registry: Registry,
+    chunkSizeMb: Int,
+    concurrency: UInt
+  ) async throws -> [OCIManifestLayer] {
+    guard let contentDigest = group.contentDigest else {
+      throw RuntimeError.VMConfigurationError("stacked VM is missing a pinned disk file digest")
+    }
+
+    var allChunksExist = true
+    for chunk in group.chunks {
+      if try await !registry.blobExists(chunk.digest) {
+        allChunksExist = false
+        break
+      }
+    }
+    if allChunksExist {
+      return group.chunks
+    }
+
+    // Rebuilding transport blobs republishes this file under the pinned
+    // whole-file digest, so validate the cached bytes at this boundary.
+    guard let contentURL = try contentStore.existingContentURL(for: contentDigest) else {
+      throw RuntimeError.VMMissingFiles("stacked VM is missing cached disk content \(contentDigest)")
+    }
+    let contentSize = try FileManager.default.attributesOfItem(atPath: contentURL.path)[.size] as! Int64
+    let progress = Progress(totalUnitCount: contentSize)
+    let mediaType = group.kind == .base ? diskV2MediaType : asifOverlayMediaType
+    let chunks = try await DiskV2.push(
+      diskURL: contentURL,
+      mediaType: mediaType,
+      registry: registry,
+      chunkSizeMb: chunkSizeMb,
+      concurrency: concurrency,
+      progress: progress
+    )
+
+    return annotatedChunks(chunks, kind: group.kind, contentDigest: contentDigest)
+  }
+
+  private func annotatedChunks(
+    _ chunks: [OCIManifestLayer],
+    kind: TartDiskFileGroup.Kind,
+    contentDigest: String
+  ) -> [OCIManifestLayer] {
+    guard !chunks.isEmpty else {
+      return chunks
+    }
+
+    var chunks = chunks
+    var annotations = chunks[0].annotations ?? [:]
+    annotations[diskFileContentDigestAnnotation] = contentDigest
+    if kind == .asifOverlay {
+      annotations[diskFileChunkCountAnnotation] = String(chunks.count)
+    }
+    chunks[0].annotations = annotations
+
+    return chunks
   }
 }
 

Sources/tart/VMDirectory.swift

@@ -2,25 +2,6 @@ import Foundation
 import Virtualization
 import CryptoKit
 
-// MARK: - Disk Image Info Structures
-struct DiskImageInfo: Codable {
-  let sizeInfo: SizeInfo?
-  let size: UInt64?
-
-  enum CodingKeys: String, CodingKey {
-    case sizeInfo = "Size Info"
-    case size = "Size"
-  }
-}
-
-struct SizeInfo: Codable {
-  let totalBytes: UInt64?
-
-  enum CodingKeys: String, CodingKey {
-    case totalBytes = "Total Bytes"
-  }
-}
-
 struct VMDirectory: Prunable {
   enum State: String {
     case Running = "running"
@@ -45,8 +26,11 @@ struct VMDirectory: Prunable {
   var manifestURL: URL {
     baseURL.appendingPathComponent("manifest.json")
   }
+  var overlayURL: URL {
+    baseURL.appendingPathComponent("overlay.asif")
+  }
   var controlSocketURL: URL {
-    baseURL.appendingPathComponent("control.sock")
+    URL(fileURLWithPath: "control.sock", relativeTo: baseURL)
   }
 
   var explicitlyPulledMark: URL {
@@ -106,10 +90,74 @@ struct VMDirectory: Prunable {
     return VMDirectory(baseURL: tmpDir)
   }
 
+  private var hasRequiredMetadata: Bool {
+    let fileManager = FileManager.default
+
+    return fileManager.fileExists(atPath: configURL.path) &&
+      fileManager.fileExists(atPath: nvramURL.path)
+  }
+
+  enum Layout: Equatable {
+    /// Existing Tart layout with one independently attachable `disk.img`.
+    /// A pulled standalone OCI record may also carry `manifest.json`.
+    case standalone
+
+    /// Runnable stacked VM with immutable disk files from `manifest.json` and
+    /// a private writable `overlay.asif`.
+    case stackedLocal
+
+    /// Pulled OCI record for a stacked image. It intentionally has no writable
+    /// overlay and becomes runnable only after `tart clone` creates one.
+    case stackedOCIRecord
+
+    var isRunnable: Bool {
+      self != .stackedOCIRecord
+    }
+  }
+
+  var layout: Layout? {
+    let fileManager = FileManager.default
+    let hasDisk = fileManager.fileExists(atPath: diskURL.path)
+    let hasManifest = fileManager.fileExists(atPath: manifestURL.path)
+    let hasOverlay = fileManager.fileExists(atPath: overlayURL.path)
+
+    guard hasRequiredMetadata else {
+      return nil
+    }
+
+    if hasDisk && !hasOverlay {
+      return .standalone
+    }
+    if !hasDisk && hasManifest && hasOverlay {
+      return .stackedLocal
+    }
+    if !hasDisk && hasManifest && !hasOverlay {
+      return .stackedOCIRecord
+    }
+
+    return nil
+  }
+
   var initialized: Bool {
-    FileManager.default.fileExists(atPath: configURL.path) &&
-      FileManager.default.fileExists(atPath: diskURL.path) &&
-      FileManager.default.fileExists(atPath: nvramURL.path)
+    layout?.isRunnable == true
+  }
+
+  var isStandalone: Bool {
+    layout == .standalone
+  }
+
+  var isStackedVM: Bool {
+    layout == .stackedLocal
+  }
+
+  var isStackedCachedImage: Bool {
+    layout == .stackedOCIRecord
+  }
+
+  /// Shapes that may live in the remote-image cache. A cached stacked image
+  /// has no writable overlay and is intentionally not runnable as a local VM.
+  var isCachedImage: Bool {
+    layout == .standalone || layout == .stackedOCIRecord
   }
 
   func initialize(overwrite: Bool = false) throws {
@@ -122,6 +170,9 @@ struct VMDirectory: Prunable {
     try? FileManager.default.removeItem(at: configURL)
     try? FileManager.default.removeItem(at: diskURL)
     try? FileManager.default.removeItem(at: nvramURL)
+    try? FileManager.default.removeItem(at: manifestURL)
+    try? FileManager.default.removeItem(at: overlayURL)
+    try? FileManager.default.removeItem(at: stateURL)
   }
 
   func validate(userFriendlyName: String) throws {
@@ -130,8 +181,26 @@ struct VMDirectory: Prunable {
     }
 
     if !initialized {
-      throw RuntimeError.VMMissingFiles("VM is missing some of its files (\(configURL.lastPathComponent),"
-        + " \(diskURL.lastPathComponent) or \(nvramURL.lastPathComponent))")
+      throw RuntimeError.VMMissingFiles(
+        "VM is missing files for a supported layout: "
+          + "standalone requires \(configURL.lastPathComponent), \(diskURL.lastPathComponent) and \(nvramURL.lastPathComponent); "
+          + "stacked requires \(configURL.lastPathComponent), \(manifestURL.lastPathComponent), "
+          + "\(overlayURL.lastPathComponent) and \(nvramURL.lastPathComponent)"
+      )
+    }
+  }
+
+  func validateCachedImage(userFriendlyName: String) throws {
+    if !FileManager.default.fileExists(atPath: baseURL.path) {
+      throw RuntimeError.VMDoesNotExist(name: userFriendlyName)
+    }
+
+    if !isCachedImage {
+      throw RuntimeError.VMMissingFiles(
+        "cached image is missing files for a supported layout: "
+          + "standalone requires \(configURL.lastPathComponent), \(diskURL.lastPathComponent) and \(nvramURL.lastPathComponent); "
+          + "stacked requires \(configURL.lastPathComponent), \(manifestURL.lastPathComponent) and \(nvramURL.lastPathComponent)"
+      )
     }
   }
 
@@ -161,7 +230,38 @@ struct VMDirectory: Prunable {
     try vmConfig.save(toURL: configURL)
   }
 
-  func resizeDisk(_ sizeGB: UInt16, format: DiskImageFormat = .raw) throws {
+  func resizeDisk(
+    _ sizeGB: UInt16,
+    format: DiskImageFormat = .raw,
+    contentStore: ContentStore? = nil
+  ) throws {
+    if isStackedVM {
+      // Resolve the stack before taking the config.json PID lock. Reading
+      // config.json after acquiring an fcntl lock would release that lock
+      // when the read file descriptor is closed.
+      let stack = try diskImageStack(contentStore: contentStore)
+      let lock = try lock()
+      guard try lock.trylock() else {
+        throw RuntimeError.VMConfigurationError("VM \"\(name)\" must be stopped before resizing its disk")
+      }
+      defer { try? lock.unlock() }
+
+      // Holding the PID lock proves that the VM is not running. A saved state
+      // file is the remaining suspended state that must also reject resize.
+      guard !FileManager.default.fileExists(atPath: stateURL.path) else {
+        throw RuntimeError.VMConfigurationError("VM \"\(name)\" must be stopped before resizing its disk")
+      }
+
+      let desiredSizeBytes = UInt64(sizeGB) * 1000 * 1000 * 1000
+      guard desiredSizeBytes.isMultiple(of: stack.blockSize) else {
+        throw RuntimeError.InvalidDiskSize("new disk size must align to the stacked disk block size")
+      }
+
+      let desiredBlockCount = desiredSizeBytes / stack.blockSize
+      try stack.growWritableOverlay(toBlockCount: desiredBlockCount)
+      return
+    }
+
     let diskExists = FileManager.default.fileExists(atPath: diskURL.path)
 
     if diskExists {
@@ -201,69 +301,28 @@ struct VMDirectory: Prunable {
   }
 
   private func resizeASIFDisk(_ sizeGB: UInt16) throws {
-    guard let diskutilURL = resolveBinaryPath("diskutil") else {
-      throw RuntimeError.FailedToResizeDisk("diskutil not found in PATH")
-    }
-
-    // First, get current disk image info to check current size
-    let infoProcess = Process()
-    infoProcess.executableURL = diskutilURL
-    infoProcess.arguments = ["image", "info", "--plist", diskURL.path]
-
-    let infoPipe = Pipe()
-    infoProcess.standardOutput = infoPipe
-    infoProcess.standardError = infoPipe
-
     do {
-      try infoProcess.run()
-      infoProcess.waitUntilExit()
+      let diskImageInfo = try Diskutil.imageInfo(diskURL)
 
-      let infoData = infoPipe.fileHandleForReading.readDataToEndOfFile()
+      let currentSizeBytes = try diskImageInfo.totalBytes()
+      let desiredSizeBytes = UInt64(sizeGB) * 1000 * 1000 * 1000
 
-      if infoProcess.terminationStatus != 0 {
-        let output = String(data: infoData, encoding: .utf8) ?? "Unknown error"
-        throw RuntimeError.FailedToResizeDisk("Failed to get ASIF disk info: \(output)")
-      }
+      if desiredSizeBytes < currentSizeBytes {
+        let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentSizeBytes))
+        let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredSizeBytes))
 
-      // Parse the plist using PropertyListDecoder
-      do {
-        let diskImageInfo = try PropertyListDecoder().decode(DiskImageInfo.self, from: infoData)
-
-        // Extract current size from the decoded structure
-        var currentSizeBytes: UInt64?
-
-        // Try to get size from Size Info -> Total Bytes first
-        if let totalBytes = diskImageInfo.sizeInfo?.totalBytes {
-          currentSizeBytes = totalBytes
-        } else if let size = diskImageInfo.size {
-          // Fallback to top-level Size field
-          currentSizeBytes = size
-        }
-
-        guard let currentSizeBytes = currentSizeBytes else {
-          throw RuntimeError.FailedToResizeDisk("Could not find size information in disk image info")
-        }
-
-        let desiredSizeBytes = UInt64(sizeGB) * 1000 * 1000 * 1000
-
-        if desiredSizeBytes < currentSizeBytes {
-          let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentSizeBytes))
-          let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredSizeBytes))
-          throw RuntimeError.InvalidDiskSize("new disk size of \(desiredLengthHuman) should be larger " +
-            "than the current disk size of \(currentLengthHuman)")
-        } else if desiredSizeBytes > currentSizeBytes {
-          // Resize the ASIF disk image using diskutil
-          try performASIFResize(sizeGB)
-        }
+        throw RuntimeError.InvalidDiskSize("New disk size of \(desiredLengthHuman) should be larger " +
+          "than the current disk size of \(currentLengthHuman)")
+      } else if desiredSizeBytes > currentSizeBytes {
+        // Resize the ASIF disk image using diskutil
+        try performASIFResize(sizeGB)
+      } else {
         // If sizes are equal, no action needed
-      } catch let error as RuntimeError {
-        throw error
-      } catch {
-        let outputString = String(data: infoData, encoding: .utf8) ?? "Unable to decode output"
-        throw RuntimeError.FailedToResizeDisk("Failed to parse disk image info: \(error). Output: \(outputString)")
       }
+    } catch let error as RuntimeError {
+      throw error
     } catch {
-      throw RuntimeError.FailedToResizeDisk("Failed to get disk image info: \(error)")
+      throw RuntimeError.FailedToResizeDisk("\(error)")
     }
   }
 
@@ -304,7 +363,7 @@ struct VMDirectory: Prunable {
     case .raw:
       try createRawDisk(sizeGB: sizeGB)
     case .asif:
-      try createASIFDisk(sizeGB: sizeGB)
+      try Diskutil.imageCreate(diskURL: diskURL, sizeGB: sizeGB)
     }
   }
 
@@ -318,38 +377,6 @@ struct VMDirectory: Prunable {
     try diskFileHandle.close()
   }
 
-  private func createASIFDisk(sizeGB: UInt16) throws {
-    guard let diskutilURL = resolveBinaryPath("diskutil") else {
-      throw RuntimeError.FailedToCreateDisk("diskutil not found in PATH")
-    }
-
-    let process = Process()
-    process.executableURL = diskutilURL
-    process.arguments = [
-      "image", "create", "blank",
-      "--format", "ASIF",
-      "--size", "\(sizeGB)G",
-      "--volumeName", "Tart",
-      diskURL.path
-    ]
-
-    let pipe = Pipe()
-    process.standardOutput = pipe
-    process.standardError = pipe
-
-    do {
-      try process.run()
-      process.waitUntilExit()
-
-      if process.terminationStatus != 0 {
-        let data = pipe.fileHandleForReading.readDataToEndOfFile()
-        let output = String(data: data, encoding: .utf8) ?? "Unknown error"
-        throw RuntimeError.FailedToCreateDisk("Failed to create ASIF disk image: \(output)")
-      }
-    } catch {
-      throw RuntimeError.FailedToCreateDisk("Failed to execute diskutil: \(error)")
-    }
-  }
 
   func delete() throws {
     let lock = try lock()
@@ -358,17 +385,33 @@ struct VMDirectory: Prunable {
       throw RuntimeError.VMIsRunning(name)
     }
 
-    try FileManager.default.removeItem(at: baseURL)
+    // Standalone local VMs do not reference the shared content store. Delete
+    // them directly so a full disk can still be recovered before the content
+    // store has ever been initialized.
+    if isStandalone {
+      try FileManager.default.removeItem(at: baseURL)
+    } else {
+      try removeFromDisk()
+    }
 
     try lock.unlock()
   }
 
+  /// Removes a VM directory while preserving the content-store reference
+  /// protocol for any complete or partially published manifest it contains.
+  func removeFromDisk() throws {
+    let contentStore = try ContentStore()
+    try contentStore.withPruneLock {
+      try FileManager.default.removeItem(at: baseURL)
+    }
+  }
+
   func accessDate() throws -> Date {
     try baseURL.accessDate()
   }
 
   func allocatedSizeBytes() throws -> Int {
-    try configURL.allocatedSizeBytes() + diskURL.allocatedSizeBytes() + nvramURL.allocatedSizeBytes()
+    try configURL.allocatedSizeBytes() + localDiskStorageAllocatedSizeBytes() + nvramURL.allocatedSizeBytes()
   }
 
   func allocatedSizeGB() throws -> Int {
@@ -376,7 +419,7 @@ struct VMDirectory: Prunable {
   }
 
   func deduplicatedSizeBytes() throws -> Int {
-    try configURL.deduplicatedSizeBytes() + diskURL.deduplicatedSizeBytes() + nvramURL.deduplicatedSizeBytes()
+    try configURL.deduplicatedSizeBytes() + localDiskStorageDeduplicatedSizeBytes() + nvramURL.deduplicatedSizeBytes()
   }
 
   func deduplicatedSizeGB() throws -> Int {
@@ -384,13 +427,52 @@ struct VMDirectory: Prunable {
   }
 
   func sizeBytes() throws -> Int {
-    try configURL.sizeBytes() + diskURL.sizeBytes() + nvramURL.sizeBytes()
+    try configURL.sizeBytes() + localDiskStorageSizeBytes() + nvramURL.sizeBytes()
   }
 
   func sizeGB() throws -> Int {
     try sizeBytes() / 1000 / 1000 / 1000
   }
 
+  func diskSizeBytes() throws -> Int {
+    if isStackedVM {
+      let blockLayout = try DiskImageStack.diskImageBlockLayout(at: overlayURL)
+      let product = blockLayout.blockSize.multipliedReportingOverflow(by: blockLayout.blockCount)
+      guard !product.overflow, let diskSizeBytes = Int(exactly: product.partialValue) else {
+        throw RuntimeError.VMConfigurationError("VM has invalid stacked disk block layout")
+      }
+
+      return diskSizeBytes
+    }
+
+    if isStackedCachedImage {
+      let manifest = try OCIManifest(fromJSON: Data(contentsOf: manifestURL))
+      guard let blockSize = manifest.diskBlockSize(),
+            let blockCount = manifest.diskBlockCount() else {
+        throw RuntimeError.VMConfigurationError("VM has invalid stacked disk block layout")
+      }
+      let product = blockSize.multipliedReportingOverflow(by: blockCount)
+      guard !product.overflow, let diskSizeBytes = Int(exactly: product.partialValue) else {
+        throw RuntimeError.VMConfigurationError("VM has invalid stacked disk block layout")
+      }
+
+      return diskSizeBytes
+    }
+
+    let vmConfig = try VMConfig(fromURL: configURL)
+
+    return switch vmConfig.diskFormat {
+    case .raw:
+      try sizeBytes()
+    case .asif:
+      try Diskutil.imageInfo(diskURL).totalBytes()
+    }
+  }
+
+  func diskSizeGB() throws -> Int {
+    try diskSizeBytes() / 1000 / 1000 / 1000
+  }
+
   func markExplicitlyPulled() {
     FileManager.default.createFile(atPath: explicitlyPulledMark.path, contents: nil)
   }
@@ -398,4 +480,23 @@ struct VMDirectory: Prunable {
   func isExplicitlyPulled() -> Bool {
     FileManager.default.fileExists(atPath: explicitlyPulledMark.path)
   }
+
+  private var localDiskStorageURL: URL {
+    isStackedVM ? overlayURL : diskURL
+  }
+
+  // Cached stacked images own no disk file in their VM directory. Their
+  // immutable disk content lives in the shared content store and must not be
+  // charged to every cached image that references it.
+  private func localDiskStorageAllocatedSizeBytes() throws -> Int {
+    isStackedCachedImage ? 0 : try localDiskStorageURL.allocatedSizeBytes()
+  }
+
+  private func localDiskStorageDeduplicatedSizeBytes() throws -> Int {
+    isStackedCachedImage ? 0 : try localDiskStorageURL.deduplicatedSizeBytes()
+  }
+
+  private func localDiskStorageSizeBytes() throws -> Int {
+    isStackedCachedImage ? 0 : try localDiskStorageURL.sizeBytes()
+  }
 }

Sources/tart/VMStorageHelper.swift

@@ -74,7 +74,6 @@ enum RuntimeError : Error {
   case ImportFailed(_ message: String)
   case SoftnetFailed(_ message: String)
   case OCIStorageError(_ message: String)
-  case OCIUnsupportedDiskFormat(_ format: String)
   case SuspendFailed(_ message: String)
   case PullFailed(_ message: String)
   case VirtualMachineLimitExceeded(_ hint: String)
@@ -139,8 +138,6 @@ extension RuntimeError : CustomStringConvertible {
       return "Softnet failed: \(message)"
     case .OCIStorageError(let message):
       return "OCI storage error: \(message)"
-    case .OCIUnsupportedDiskFormat(let format):
-      return "OCI disk format \(format) is not supported by this version of Tart"
     case .SuspendFailed(let message):
       return "Failed to suspend the VM: \(message)"
     case .PullFailed(let message):
@@ -169,14 +166,3 @@ extension RuntimeError : HasExitCode {
     }
   }
 }
-
-// Customize error description for Sentry[1]
-//
-// [1]: https://docs.sentry.io/platforms/apple/guides/ios/usage/#customizing-error-descriptions
-extension RuntimeError : CustomNSError {
-  var errorUserInfo: [String : Any] {
-    [
-      NSDebugDescriptionErrorKey: description,
-    ]
-  }
-}

Sources/tart/VMStorageLocal.swift

@@ -1,7 +1,11 @@
 import Foundation
 
 class VMStorageLocal: PrunableStorage {
-  let baseURL: URL = try! Config().tartHomeDir.appendingPathComponent("vms", isDirectory: true)
+  let baseURL: URL
+
+  init() throws {
+    baseURL = try Config().tartHomeDir.appendingPathComponent("vms", isDirectory: true)
+  }
 
   private func vmURL(_ name: String) -> URL {
     baseURL.appendingPathComponent(name, isDirectory: true)
@@ -31,11 +35,27 @@ class VMStorageLocal: PrunableStorage {
 
   func move(_ name: String, from: VMDirectory) throws {
     _ = try FileManager.default.createDirectory(at: baseURL, withIntermediateDirectories: true)
-    _ = try FileManager.default.replaceItemAt(vmURL(name), withItemAt: from.baseURL)
+    try replace(VMDirectory(baseURL: vmURL(name)), with: from)
   }
 
   func rename(_ name: String, _ newName: String) throws {
-    _ = try FileManager.default.replaceItemAt(vmURL(newName), withItemAt: vmURL(name))
+    let source = VMDirectory(baseURL: vmURL(name))
+    let destination = VMDirectory(baseURL: vmURL(newName))
+    try replace(destination, with: source)
+  }
+
+  /// References in a manifest must not disappear while content GC is deciding
+  /// whether their immutable disk files are still in use.
+  private func replace(_ destination: VMDirectory, with source: VMDirectory) throws {
+    if FileManager.default.fileExists(atPath: source.manifestURL.path) ||
+      FileManager.default.fileExists(atPath: destination.manifestURL.path) {
+      let contentStore = try ContentStore()
+      try contentStore.withPruneLock {
+        _ = try FileManager.default.replaceItemAt(destination.baseURL, withItemAt: source.baseURL)
+      }
+    } else {
+      _ = try FileManager.default.replaceItemAt(destination.baseURL, withItemAt: source.baseURL)
+    }
   }
 
   func delete(_ name: String) throws {

Sources/tart/VMStorageOCI.swift

@@ -1,9 +1,13 @@
 import Foundation
-import Sentry
+import OpenTelemetryApi
 import Retry
 
 class VMStorageOCI: PrunableStorage {
-  let baseURL = try! Config().tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
+  let baseURL: URL
+
+  init() throws {
+    baseURL = try Config().tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
+  }
 
   private func vmURL(_ name: RemoteName) -> URL {
     baseURL.appendingRemoteName(name)
@@ -14,7 +18,104 @@ class VMStorageOCI: PrunableStorage {
   }
 
   func exists(_ name: RemoteName) -> Bool {
-    VMDirectory(baseURL: vmURL(name)).initialized
+    VMDirectory(baseURL: vmURL(name)).isCachedImage
+  }
+
+  /// Whether clone can use a cached image without pulling. Standalone images keep
+  /// Tart's existing structural check. Stacked cached images require every
+  /// immutable file with its expected length.
+  func hasUsableCachedImageForClone(_ name: RemoteName, requireManifest: Bool = false) throws -> Bool {
+    guard exists(name) else {
+      return false
+    }
+
+    let vmDir = VMDirectory(baseURL: vmURL(name))
+    if requireManifest && !FileManager.default.fileExists(atPath: vmDir.manifestURL.path) {
+      return false
+    }
+    guard vmDir.isStackedCachedImage else {
+      return true
+    }
+
+    let manifest = try OCIManifest(fromJSON: Data(contentsOf: vmDir.manifestURL))
+    guard case .stacked(let base, let overlays) = try manifest.tartDiskRepresentation() else {
+      return true
+    }
+
+    let contentStore = try ContentStore()
+    for group in [base] + overlays {
+      guard try hasUsableCachedDiskFile(group, contentStore: contentStore) else {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /// Whether a cached image is complete enough for `pull` to return without
+  /// repairing it. Standalone images keep Tart's existing structural cache-hit
+  /// behavior; stacked cached images additionally need every immutable disk file in
+  /// the shared content store.
+  func hasCompleteCachedImage(
+    _ name: RemoteName,
+    manifest: OCIManifest,
+    requireManifest: Bool = false
+  ) throws -> Bool {
+    guard exists(name) else {
+      return false
+    }
+
+    let vmDir = VMDirectory(baseURL: vmURL(name))
+    if requireManifest && !FileManager.default.fileExists(atPath: vmDir.manifestURL.path) {
+      return false
+    }
+
+    guard let missingGroups = try missingStackedDiskFileGroups(for: manifest) else {
+      return true
+    }
+
+    return missingGroups.isEmpty
+  }
+
+  /// The lock-free pull fast path is only useful for a tag that already
+  /// points at this digest. New or retargeted tags validate once after taking
+  /// the host lock instead of hashing a large stack twice.
+  func hasCompleteLinkedImage(
+    _ name: RemoteName,
+    digestName: RemoteName,
+    manifest: OCIManifest,
+    requireManifest: Bool = false
+  ) throws -> Bool {
+    guard exists(name), linked(from: name, to: digestName) else {
+      return false
+    }
+
+    return try hasCompleteCachedImage(digestName, manifest: manifest, requireManifest: requireManifest)
+  }
+
+  /// Bytes that this pull may need to materialize locally. For stacked images
+  /// this is the sum of only the missing complete disk files, not the final
+  /// guest-visible disk block layout.
+  func requiredDiskStorageBytes(for manifest: OCIManifest) throws -> UInt64? {
+    guard let missingGroups = try missingStackedDiskFileGroups(for: manifest) else {
+      return manifest.uncompressedDiskSize()
+    }
+
+    var total: UInt64 = 0
+    for group in missingGroups {
+      for chunk in group.chunks {
+        guard let uncompressedSize = chunk.uncompressedSize() else {
+          throw OCIManifestValidationError.invalidDiskMetadata("disk chunks need uncompressed size and content digest")
+        }
+        let addition = total.addingReportingOverflow(uncompressedSize)
+        guard !addition.overflow else {
+          throw RuntimeError.PullFailed("stacked disk storage size overflows UInt64")
+        }
+        total = addition.partialValue
+      }
+    }
+
+    return total
   }
 
   func digest(_ name: RemoteName) throws -> String {
@@ -30,7 +131,7 @@ class VMStorageOCI: PrunableStorage {
   func open(_ name: RemoteName, _ accessDate: Date = Date()) throws -> VMDirectory {
     let vmDir = VMDirectory(baseURL: vmURL(name))
 
-    try vmDir.validate(userFriendlyName: name.description)
+    try vmDir.validateCachedImage(userFriendlyName: name.description)
 
     try vmDir.baseURL.updateAccessDate(accessDate)
 
@@ -40,11 +141,64 @@ class VMStorageOCI: PrunableStorage {
   func create(_ name: RemoteName, overwrite: Bool = false) throws -> VMDirectory {
     let vmDir = VMDirectory(baseURL: vmURL(name))
 
+    if !overwrite && vmDir.isCachedImage {
+      throw RuntimeError.VMDirectoryAlreadyInitialized("VM directory is already initialized, preventing overwrite")
+    }
+
     try vmDir.initialize(overwrite: overwrite)
 
     return vmDir
   }
 
+  /// Materialize the digest-addressed cached image for an image Tart just
+  /// pushed, without routing its own local data back through the registry.
+  func populate(_ name: RemoteName, from source: VMDirectory, manifest: OCIManifest) throws {
+    if try hasCompleteCachedImage(name, manifest: manifest) {
+      return
+    }
+
+    let vmDir = try create(name, overwrite: exists(name))
+
+    do {
+      if source.isStackedVM {
+        guard case .stacked(_, let overlays) = try manifest.tartDiskRepresentation(),
+              let contentDigest = overlays.last?.contentDigest else {
+          throw RuntimeError.VMConfigurationError("pushed image is missing its writable ASIF overlay")
+        }
+
+        // The pushed top overlay becomes immutable in the cached image. Keep a
+        // semantic copy so later clones do not need to fetch it back.
+        let contentStore = try ContentStore()
+        try contentStore.withPruneLock {
+          try FileManager.default.copyItem(at: source.configURL, to: vmDir.configURL)
+          try FileManager.default.copyItem(at: source.nvramURL, to: vmDir.nvramURL)
+          // Publish the reference before installing the immutable top overlay,
+          // so reference-aware pruning cannot collect it in between.
+          try manifest.toJSON().write(to: vmDir.manifestURL)
+        }
+
+        if try contentStore.contentURLIfPresent(for: contentDigest) == nil {
+          let temporaryURL = try contentStore.temporaryContentURL(for: contentDigest)
+          do {
+            try FileManager.default.copyItem(at: source.overlayURL, to: temporaryURL)
+            _ = try contentStore.install(temporaryURL, contentDigest: contentDigest)
+          } catch {
+            try? FileManager.default.removeItem(at: temporaryURL)
+            throw error
+          }
+        }
+      } else {
+        try source.clone(to: vmDir, generateMAC: false)
+        // Keep the exact manifest Tart submitted so tag links and later pushes
+        // refer to the same digest-addressed cached image.
+        try manifest.toJSON().write(to: vmDir.manifestURL)
+      }
+    } catch {
+      try? vmDir.removeFromDisk()
+      throw error
+    }
+  }
+
   func move(_ name: RemoteName, from: VMDirectory) throws{
     let targetURL = vmURL(name)
 
@@ -53,11 +207,20 @@ class VMStorageOCI: PrunableStorage {
     try FileManager.default.createDirectory(at: targetURL.deletingLastPathComponent(),
                                             withIntermediateDirectories: true)
 
-    _ = try FileManager.default.replaceItemAt(targetURL, withItemAt: from.baseURL)
+    let target = VMDirectory(baseURL: targetURL)
+    if FileManager.default.fileExists(atPath: from.manifestURL.path) ||
+      FileManager.default.fileExists(atPath: target.manifestURL.path) {
+      let contentStore = try ContentStore()
+      try contentStore.withPruneLock {
+        _ = try FileManager.default.replaceItemAt(targetURL, withItemAt: from.baseURL)
+      }
+    } else {
+      _ = try FileManager.default.replaceItemAt(targetURL, withItemAt: from.baseURL)
+    }
   }
 
   func delete(_ name: RemoteName) throws {
-    try FileManager.default.removeItem(at: vmURL(name))
+    try removeRecord(at: vmURL(name))
     try gc()
   }
 
@@ -66,6 +229,7 @@ class VMStorageOCI: PrunableStorage {
 
     guard let enumerator = FileManager.default.enumerator(at: baseURL,
                                                           includingPropertiesForKeys: [.isSymbolicLinkKey]) else {
+      try gcContent()
       return
     }
 
@@ -80,7 +244,7 @@ class VMStorageOCI: PrunableStorage {
       }
 
       let vmDir = VMDirectory(baseURL: foundURL.resolvingSymlinksInPath())
-      if !vmDir.initialized {
+      if !vmDir.isCachedImage {
         continue
       }
 
@@ -93,7 +257,28 @@ class VMStorageOCI: PrunableStorage {
       let vmDir = VMDirectory(baseURL: baseURL)
 
       if !vmDir.isExplicitlyPulled() && incRefCount == 0 {
-        try FileManager.default.removeItem(at: baseURL)
+        try removeRecord(at: baseURL)
+      }
+    }
+
+    try gcContent()
+  }
+
+  /// Cached images with a manifest publish references into the shared content
+  /// store. Remove them through VMDirectory so reference removal is serialized
+  /// with clone, export, pull, and content GC, even if a record is incomplete.
+  private func removeRecord(at url: URL) throws {
+    try VMDirectory(baseURL: url).removeFromDisk()
+  }
+
+  /// Remove immutable files whose final published or in-progress reference
+  /// has disappeared, without collecting unrelated cached images.
+  fileprivate func gcContent() throws {
+    let contentStore = try ContentStore()
+    try contentStore.withPruneLock {
+      let referencedContentDigests = try referencedContentDigests(includeCachedImages: true)
+      for contentURL in try contentStore.prunables(excluding: referencedContentDigests) {
+        try FileManager.default.removeItem(at: contentURL)
       }
     }
   }
@@ -109,7 +294,7 @@ class VMStorageOCI: PrunableStorage {
     for case let foundURL as URL in enumerator {
       let vmDir = VMDirectory(baseURL: foundURL)
 
-      if !vmDir.initialized {
+      if !vmDir.isCachedImage {
         continue
       }
 
@@ -137,22 +322,91 @@ class VMStorageOCI: PrunableStorage {
   }
 
   func prunables() throws -> [Prunable] {
-    try list().filter { (_, _, isSymlink) in !isSymlink }.map { (_, vmDir, _) in vmDir }
+    let records = try list().filter { (_, _, isSymlink) in
+      !isSymlink
+    }.map { (_, vmDir, _) in vmDir }
+
+    // Attribute shared content to the newest cached image that references it.
+    // This counts each file once while charging it to the last record that
+    // normally needs to be removed before the file becomes reclaimable.
+    let nonCacheContentDigests = try referencedContentDigests(includeCachedImages: false)
+    var contentOwners = [String: VMDirectory]()
+    for record in records where record.isStackedCachedImage {
+      // Interrupted cache population can leave a truncated manifest in an
+      // otherwise recognizable cached record. It has no reliable content
+      // references, but it must not prevent pruning other cache entries.
+      for contentDigest in (try? record.diskContentDigests()) ?? []
+        where !nonCacheContentDigests.contains(contentDigest) {
+        guard let currentOwner = contentOwners[contentDigest] else {
+          contentOwners[contentDigest] = record
+          continue
+        }
+
+        let recordAccessDate = try record.accessDate()
+        let currentAccessDate = try currentOwner.accessDate()
+        if recordAccessDate > currentAccessDate ||
+          (recordAccessDate == currentAccessDate && record.url.path > currentOwner.url.path) {
+          contentOwners[contentDigest] = record
+        }
+      }
+    }
+
+    let contentStore = try ContentStore()
+    var ownedContentURLs = [URL: [URL]]()
+    for (contentDigest, owner) in contentOwners {
+      let contentURL = try contentStore.contentURL(for: contentDigest)
+      guard FileManager.default.fileExists(atPath: contentURL.path) else {
+        continue
+      }
+
+      ownedContentURLs[owner.url, default: []].append(contentURL)
+    }
+
+    var result: [Prunable] = records.map { record in
+      CachedImagePrunable(
+        vmDir: record,
+        ownedContentURLs: ownedContentURLs[record.url] ?? []
+      )
+    }
+
+    result += try contentStore.prunables(excluding: referencedContentDigests(includeCachedImages: true))
+      .map(ContentPrunable.init)
+
+    return result
   }
 
-  func pull(_ name: RemoteName, registry: Registry, concurrency: UInt, deduplicate: Bool) async throws {
-    SentrySDK.configureScope { scope in
-      scope.setContext(value: ["imageName": name.description], key: "OCI")
-    }
+  func pull(
+    _ name: RemoteName,
+    registry: Registry,
+    concurrency: UInt,
+    deduplicate: Bool,
+    requireManifest: Bool = false,
+    resolvedManifest: (manifest: OCIManifest, data: Data)? = nil
+  ) async throws {
+    OpenTelemetry.instance.contextProvider.activeSpan?.setAttribute(
+      key: "oci.image-name",
+      value: .string(name.description)
+    )
 
     defaultLogger.appendNewLine("pulling manifest...")
 
-    let (manifest, manifestData) = try await registry.pullManifest(reference: name.reference.value)
+    let (manifest, manifestData): (OCIManifest, Data)
+    if let resolvedManifest {
+      manifest = resolvedManifest.manifest
+      manifestData = resolvedManifest.data
+    } else {
+      (manifest, manifestData) = try await registry.pullManifest(reference: name.reference.value)
+    }
 
     let digestName = RemoteName(host: name.host, namespace: name.namespace,
                                 reference: Reference(digest: Digest.hash(manifestData)))
 
-    if exists(name) && exists(digestName) && linked(from: name, to: digestName) {
+    if try hasCompleteLinkedImage(
+      name,
+      digestName: digestName,
+      manifest: manifest,
+      requireManifest: requireManifest
+    ) {
       // optimistically check if we need to do anything at all before locking
       defaultLogger.appendNewLine("\(digestName) image is already cached and linked!")
       return
@@ -176,9 +430,22 @@ class VMStorageOCI: PrunableStorage {
       throw CancellationError()
     }
 
-    if !exists(digestName) {
-      let transaction = SentrySDK.startTransaction(name: name.description, operation: "pull", bindToScope: true)
+    let digestVMDir = VMDirectory(baseURL: vmURL(digestName))
+    if requireManifest,
+       !FileManager.default.fileExists(atPath: digestVMDir.manifestURL.path),
+       try hasCompleteCachedImage(digestName, manifest: manifest) {
+      // Old Tart versions cached standalone OCI images without manifest.json.
+      // A stacked clone needs the manifest to describe its immutable base, but
+      // the existing disk remains usable and must not be downloaded again.
+      try manifestData.write(to: digestVMDir.manifestURL, options: .atomic)
+    }
+
+    if try !hasCompleteCachedImage(digestName, manifest: manifest, requireManifest: requireManifest) {
+      let span = OTel.shared.tracer.spanBuilder(spanName: "pull").setActive(true).startSpan()
+      defer { span.end() }
+
       let tmpVMDir = try VMDirectory.temporaryDeterministic(key: name.description)
+      let preserveExplicitlyPulledMark = digestVMDir.isExplicitlyPulled()
 
       // Open an existing VM directory corresponding to this name, if any,
       // marking it as outdated to speed up the garbage collection process
@@ -188,21 +455,47 @@ class VMStorageOCI: PrunableStorage {
       let tmpVMDirLock = try FileLock(lockURL: tmpVMDir.baseURL)
       try tmpVMDirLock.lock()
 
+      // Make in-progress stacked content references visible before reclaiming
+      // space or reconstructing immutable files.
+      try ContentStore().withPruneLock {
+        try manifestData.write(to: tmpVMDir.manifestURL)
+      }
+
+      // A previously pulled standalone image already has the complete base
+      // disk locally as disk.img. Promote that file into the content store
+      // before sizing or pulling so a stacked child only fetches overlays.
+      try reuseStandaloneDiskForStackedBaseIfPossible(manifest)
+
       // Try to reclaim some cache space if we know the VM size in advance
-      if let uncompressedDiskSize = manifest.uncompressedDiskSize() {
-        SentrySDK.configureScope { scope in
-          scope.setContext(value: ["imageUncompressedDiskSize": uncompressedDiskSize], key: "OCI")
+      if let requiredDiskStorageBytes = try requiredDiskStorageBytes(for: manifest) {
+        if let telemetryValue = Int(exactly: requiredDiskStorageBytes) {
+          OpenTelemetry.instance.contextProvider.activeSpan?.setAttribute(
+            key: "oci.image-required-disk-storage-bytes",
+            value: .int(telemetryValue)
+          )
         }
 
         let otherVMFilesSize: UInt64 = 128 * 1024 * 1024
+        let requiredStorage = requiredDiskStorageBytes.addingReportingOverflow(otherVMFilesSize)
+        guard !requiredStorage.overflow else {
+          throw RuntimeError.PullFailed("required pull storage size overflows UInt64")
+        }
 
-        try Prune.reclaimIfNeeded(uncompressedDiskSize + otherVMFilesSize)
+        try Prune.reclaimIfNeeded(requiredStorage.partialValue)
       }
 
       try await withTaskCancellationHandler(operation: {
         try await retry(maxAttempts: 5) {
-          // Choose the best base image which has the most deduplication ratio
-          let localLayerCache = try await chooseLocalLayerCache(name, manifest, registry)
+          // Existing standalone images can still reuse another complete local disk.
+          // Stacked images reconstruct their immutable files through the
+          // shared content store instead of materializing disk.img.
+          let localLayerCache: LocalLayerCache?
+          switch try manifest.tartDiskRepresentation() {
+          case .flat:
+            localLayerCache = try await chooseLocalLayerCache(name, manifest, registry)
+          case .stacked:
+            localLayerCache = nil
+          }
 
           if let llc = localLayerCache {
             let deduplicatedHuman = ByteCountFormatter.string(fromByteCount: Int64(llc.deduplicatedBytes), countStyle: .file)
@@ -224,11 +517,14 @@ class VMStorageOCI: PrunableStorage {
 
           return .throw
         }
+
+        if preserveExplicitlyPulledMark {
+          tmpVMDir.markExplicitlyPulled()
+        }
+
         try move(digestName, from: tmpVMDir)
-        transaction.finish()
       }, onCancel: {
-        transaction.finish(status: SentrySpanStatus.cancelled)
-        try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+        try? tmpVMDir.removeFromDisk()
       })
     } else {
       defaultLogger.appendNewLine("\(digestName) image is already cached! creating a symlink...")
@@ -247,6 +543,115 @@ class VMStorageOCI: PrunableStorage {
     _ = try VMStorageOCI().open(name)
   }
 
+  /// Returns nil for standalone images and the missing immutable disk-file
+  /// groups for stacked images. Like existing standalone cached images, cache hits trust
+  /// already-installed files; checking size still repairs truncated entries
+  /// without hashing a large prewarmed base on every pull.
+  private func missingStackedDiskFileGroups(for manifest: OCIManifest) throws -> [TartDiskFileGroup]? {
+    guard case .stacked(let base, let overlays) = try manifest.tartDiskRepresentation() else {
+      return nil
+    }
+
+    let contentStore = try ContentStore()
+    var missingGroups: [TartDiskFileGroup] = []
+    for group in [base] + overlays {
+      if try !hasUsableCachedDiskFile(group, contentStore: contentStore) {
+        missingGroups.append(group)
+      }
+    }
+
+    return missingGroups
+  }
+
+  /// Seed a stacked image's immutable base from an already pulled standalone
+  /// OCI record when both manifests describe the same transport chunks. The
+  /// content store still verifies the whole-file digest before publishing it.
+  func reuseStandaloneDiskForStackedBaseIfPossible(_ manifest: OCIManifest) throws {
+    guard case .stacked(let base, _) = try manifest.tartDiskRepresentation(),
+          let contentDigest = base.contentDigest else {
+      return
+    }
+
+    let contentStore = try ContentStore()
+    var attemptedCandidates = Swift.Set<String>()
+    while true {
+      // Keep the source record alive only while cloning its disk. The pull's
+      // in-progress manifest already protects the destination content digest,
+      // so hashing and installing the staged clone need not hold the global
+      // prune lock.
+      let temporaryURL = try contentStore.withPruneLock { () -> URL? in
+        // Content-store entries are verified when installed. Avoid hashing a
+        // potentially large prewarmed base again on every stacked pull.
+        guard try contentStore.contentURLIfPresent(for: contentDigest) == nil else {
+          return nil
+        }
+
+        for (_, vmDir, isSymlink) in try list() where !isSymlink && vmDir.isStandalone {
+          guard !attemptedCandidates.contains(vmDir.baseURL.path),
+                let manifestData = try? Data(contentsOf: vmDir.manifestURL),
+                let candidateManifest = try? OCIManifest(fromJSON: manifestData),
+                case .flat(let candidateBase) = try? candidateManifest.tartDiskRepresentation(),
+                diskChunksMatch(candidateBase.chunks, base.chunks) else {
+            continue
+          }
+
+          attemptedCandidates.insert(vmDir.baseURL.path)
+          let temporaryURL = try contentStore.temporaryContentURL(for: contentDigest)
+          do {
+            try FileManager.default.copyItem(at: vmDir.diskURL, to: temporaryURL)
+            return temporaryURL
+          } catch {
+            try? FileManager.default.removeItem(at: temporaryURL)
+            throw error
+          }
+        }
+
+        return nil
+      }
+
+      guard let temporaryURL else {
+        return
+      }
+
+      do {
+        _ = try contentStore.install(temporaryURL, contentDigest: contentDigest)
+        return
+      } catch ContentStoreError.contentDigestMismatch {
+        try? FileManager.default.removeItem(at: temporaryURL)
+      } catch {
+        try? FileManager.default.removeItem(at: temporaryURL)
+        throw error
+      }
+    }
+  }
+
+  /// Compare the OCI transport identity while ignoring stacked-only
+  /// whole-file annotations added to the first base chunk.
+  private func diskChunksMatch(_ left: [OCIManifestLayer], _ right: [OCIManifestLayer]) -> Bool {
+    guard left.count == right.count else {
+      return false
+    }
+
+    return zip(left, right).allSatisfy { left, right in
+      left.mediaType == right.mediaType &&
+        left.size == right.size &&
+        left.digest == right.digest &&
+        left.uncompressedSize() == right.uncompressedSize() &&
+        left.uncompressedContentDigest() == right.uncompressedContentDigest()
+    }
+  }
+
+  private func hasUsableCachedDiskFile(_ group: TartDiskFileGroup, contentStore: ContentStore) throws -> Bool {
+    guard let contentDigest = group.contentDigest,
+          let contentURL = try contentStore.contentURLIfPresent(for: contentDigest),
+          let actualSize = UInt64(exactly: try contentURL.sizeBytes()),
+          let expectedSize = group.uncompressedSize() else {
+      return false
+    }
+
+    return actualSize == expectedSize
+  }
+
   func linked(from: RemoteName, to: RemoteName) -> Bool {
     do {
       let resolvedFrom = try FileManager.default.destinationOfSymbolicLink(atPath: vmURL(from).path)
@@ -257,9 +662,13 @@ class VMStorageOCI: PrunableStorage {
   }
 
   func link(from: RemoteName, to: RemoteName) throws {
-    try? FileManager.default.removeItem(at: vmURL(from))
-
-    try FileManager.default.createSymbolicLink(at: vmURL(from), withDestinationURL: vmURL(to))
+    // Export resolves mutable tags while holding this same lock, so replace
+    // the symlink atomically with respect to stacked archive staging.
+    let contentStore = try ContentStore()
+    try contentStore.withPruneLock {
+      try? FileManager.default.removeItem(at: vmURL(from))
+      try FileManager.default.createSymbolicLink(at: vmURL(from), withDestinationURL: vmURL(to))
+    }
 
     try gc()
   }
@@ -274,10 +683,16 @@ class VMStorageOCI: PrunableStorage {
     }
 
     // Load OCI VM images and their manifests (if present)
-    var candidates: [(name: String, vmDir: VMDirectory, manifest: OCIManifest, deduplicatedBytes: UInt64)] = []
+    var candidates: [(
+      name: String,
+      vmDir: VMDirectory,
+      manifest: OCIManifest,
+      manifestDigest: String,
+      deduplicatedBytes: UInt64
+    )] = []
 
     for (name, vmDir, isSymlink) in try list() {
-      if isSymlink {
+      if isSymlink || !vmDir.isStandalone {
         continue
       }
 
@@ -289,7 +704,13 @@ class VMStorageOCI: PrunableStorage {
         continue
       }
 
-      candidates.append((name, vmDir, manifest, calculateDeduplicatedBytes(manifest)))
+      candidates.append((
+        name,
+        vmDir,
+        manifest,
+        Digest.hash(manifestJSON),
+        calculateDeduplicatedBytes(manifest)
+      ))
     }
 
     // Previously we haven't stored the OCI VM image manifests, but still fetched the VM image manifest if
@@ -299,10 +720,17 @@ class VMStorageOCI: PrunableStorage {
     // with the registry if we haven't already retrieved the manifest for that OCI VM image.
     if name.reference.type == .Tag,
        let vmDir = try? open(name),
+       vmDir.isStandalone,
        let digest = try? digest(name),
-       try !candidates.contains(where: {try $0.manifest.digest() == digest}),
-       let (manifest, _) = try? await registry.pullManifest(reference: digest) {
-      candidates.append((name.description, vmDir, manifest, calculateDeduplicatedBytes(manifest)))
+       !candidates.contains(where: { $0.manifestDigest == digest }),
+       let (manifest, manifestData) = try? await registry.pullManifest(reference: digest) {
+      candidates.append((
+        name.description,
+        vmDir,
+        manifest,
+        Digest.hash(manifestData),
+        calculateDeduplicatedBytes(manifest)
+      ))
     }
 
     // Now, find the best match based on how many bytes we'll deduplicate
@@ -316,6 +744,108 @@ class VMStorageOCI: PrunableStorage {
       try LocalLayerCache(choosen.name, choosen.deduplicatedBytes, choosen.vmDir.diskURL, choosen.manifest)
     })
   }
+
+  /// Returns content referenced outside the OCI cache, optionally including
+  /// references published by retained cached images.
+  private func referencedContentDigests(includeCachedImages: Bool) throws -> Swift.Set<String> {
+    var result = Swift.Set<String>()
+
+    for (_, vmDir) in try VMStorageLocal().list() where vmDir.isStackedVM {
+      result.formUnion(try vmDir.diskContentDigests())
+    }
+
+    // Clone, pull, and import publish their manifest before installing
+    // immutable content. Include partially populated temporary directories so
+    // pruning cannot race those operations.
+    for url in try FileManager.default.contentsOfDirectory(
+      at: Config().tartTmpDir,
+      includingPropertiesForKeys: [],
+      options: .skipsHiddenFiles
+    ) {
+      let vmDir = VMDirectory(baseURL: url)
+      guard FileManager.default.fileExists(atPath: vmDir.manifestURL.path),
+            let contentDigests = try? vmDir.diskContentDigests() else {
+        continue
+      }
+
+      result.formUnion(contentDigests)
+    }
+
+    if includeCachedImages {
+      for (_, vmDir, isSymlink) in try list() where !isSymlink && vmDir.isStackedCachedImage {
+        // Malformed cached records are invalid references. Keep scanning so
+        // one interrupted population does not disable content GC globally.
+        if let contentDigests = try? vmDir.diskContentDigests() {
+          result.formUnion(contentDigests)
+        }
+      }
+    }
+
+    return result
+  }
+
+  fileprivate func deleteContentIfUnused(_ url: URL) throws {
+    let contentStore = try ContentStore()
+    try contentStore.withPruneLock {
+      let referencedContentDigests = try referencedContentDigests(includeCachedImages: true)
+      let stillPrunable = try contentStore.prunables(excluding: referencedContentDigests).contains {
+        $0.resolvingSymlinksInPath() == url.resolvingSymlinksInPath()
+      }
+      if stillPrunable {
+        try FileManager.default.removeItem(at: url)
+      }
+    }
+  }
+}
+
+private struct ContentPrunable: Prunable {
+  let url: URL
+
+  func delete() throws {
+    try VMStorageOCI().deleteContentIfUnused(url)
+  }
+
+  func accessDate() throws -> Date {
+    try url.accessDate()
+  }
+
+  func sizeBytes() throws -> Int {
+    try url.sizeBytes()
+  }
+
+  func allocatedSizeBytes() throws -> Int {
+    try url.allocatedSizeBytes()
+  }
+}
+
+/// A digest-addressed cached image plus immutable content attributed to the
+/// final remote reference that can release it.
+private struct CachedImagePrunable: Prunable {
+  let vmDir: VMDirectory
+  let ownedContentURLs: [URL]
+
+  var url: URL {
+    vmDir.url
+  }
+
+  func delete() throws {
+    try vmDir.delete()
+    // Deleting a record can make attributed content unreferenced. Run GC now
+    // so one prune invocation reclaims those bytes.
+    try VMStorageOCI().gcContent()
+  }
+
+  func accessDate() throws -> Date {
+    try vmDir.accessDate()
+  }
+
+  func sizeBytes() throws -> Int {
+    try vmDir.sizeBytes() + ownedContentURLs.map { try $0.sizeBytes() }.reduce(0, +)
+  }
+
+  func allocatedSizeBytes() throws -> Int {
+    try vmDir.allocatedSizeBytes() + ownedContentURLs.map { try $0.allocatedSizeBytes() }.reduce(0, +)
+  }
 }
 
 extension URL {

Tests/TartTests/CommandBehaviorTests.swift

@@ -0,0 +1,152 @@
+import Foundation
+import ArgumentParser
+import XCTest
+@testable import tart
+
+final class CommandBehaviorTests: XCTestCase {
+  func testStandaloneDeleteDoesNotInitializeContentStore() throws {
+    try withTemporaryTartHome {
+      let vmDir = try VMStorageLocal().create("standalone")
+      try config().save(toURL: vmDir.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.nvramURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.diskURL.path, contents: Data()))
+
+      let contentStoreURL = try Config().tartCacheDir.appendingPathComponent("content", isDirectory: true)
+      XCTAssertFalse(FileManager.default.fileExists(atPath: contentStoreURL.path))
+
+      try vmDir.delete()
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: vmDir.baseURL.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: contentStoreURL.path))
+    }
+  }
+
+  func testSetDiskRejectsStackedVMBeforeSavingConfig() async throws {
+    try await withTemporaryTartHome {
+      let vmDir = try VMStorageLocal().create("stacked")
+      let originalConfig = config()
+      try originalConfig.save(toURL: vmDir.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.nvramURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.manifestURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.overlayURL.path, contents: Data()))
+
+      let replacementURL = try temporaryDirectory().appendingPathComponent("replacement.img")
+      XCTAssertTrue(FileManager.default.createFile(atPath: replacementURL.path, contents: Data("replacement".utf8)))
+
+      let command = try Set.parseAsRoot([
+        "stacked",
+        "--cpu", "4",
+        "--disk", replacementURL.path,
+      ]) as! Set
+
+      do {
+        try await command.run()
+        XCTFail("expected stacked disk replacement to be rejected")
+      } catch let error as ValidationError {
+        XCTAssertEqual(error.message, "--disk is not supported for VMs with a stacked disk")
+      }
+
+      XCTAssertEqual(try VMConfig(fromURL: vmDir.configURL).cpuCount, originalConfig.cpuCount)
+      XCTAssertFalse(FileManager.default.fileExists(atPath: vmDir.diskURL.path))
+    }
+  }
+
+  func testRemoteAdditionalDiskRetainsTemporaryBackingFileLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let name = try RemoteName("example.com/org/image:latest")
+      let cachedImage = try storage.create(name)
+      try config().save(toURL: cachedImage.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: cachedImage.nvramURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(
+        atPath: cachedImage.diskURL.path,
+        contents: Data(repeating: 0, count: 4096)
+      ))
+
+      do {
+        let additionalDisk = try AdditionalDisk(parseFrom: name.description)
+        let entriesBeforeGC = try temporaryEntries()
+        XCTAssertEqual(entriesBeforeGC.count, 1)
+
+        try Config().gc()
+        XCTAssertEqual(try temporaryEntries(), entriesBeforeGC)
+
+        withExtendedLifetime(additionalDisk) {}
+      }
+
+      try Config().gc()
+      XCTAssertTrue(try temporaryEntries().isEmpty)
+    }
+  }
+
+  func testGarbageCollectionPreservesLockedTemporaryDirectory() throws {
+    try withTemporaryTartHome {
+      let temporaryVMDir = try VMDirectory.temporary()
+      let lock = try FileLock(lockURL: temporaryVMDir.baseURL)
+      try lock.lock()
+      XCTAssertTrue(FileManager.default.createFile(
+        atPath: temporaryVMDir.overlayURL.path,
+        contents: Data("overlay".utf8)
+      ))
+
+      try Config().gc()
+      XCTAssertTrue(FileManager.default.fileExists(atPath: temporaryVMDir.overlayURL.path))
+
+      try lock.unlock()
+      try Config().gc()
+      XCTAssertFalse(FileManager.default.fileExists(atPath: temporaryVMDir.baseURL.path))
+    }
+  }
+
+  private func config() -> VMConfig {
+    VMConfig(
+      platform: Linux(),
+      cpuCountMin: 2,
+      memorySizeMin: 512 * 1024 * 1024,
+      diskFormat: .raw
+    )
+  }
+
+  private func temporaryEntries() throws -> [URL] {
+    try FileManager.default.contentsOfDirectory(
+      at: Config().tartTmpDir,
+      includingPropertiesForKeys: nil
+    )
+  }
+
+  private func withTemporaryTartHome(_ body: () throws -> Void) throws {
+    let home = try temporaryDirectory()
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", home.path, 1)
+    defer { restoreEnvironment("TART_HOME", to: previousHome) }
+
+    try body()
+  }
+
+  private func withTemporaryTartHome(_ body: () async throws -> Void) async throws {
+    let home = try temporaryDirectory()
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", home.path, 1)
+    defer { restoreEnvironment("TART_HOME", to: previousHome) }
+
+    try await body()
+  }
+
+  private func temporaryDirectory() throws -> URL {
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: url)
+    }
+
+    return url
+  }
+
+  private func restoreEnvironment(_ name: String, to value: String?) {
+    if let value {
+      setenv(name, value, 1)
+    } else {
+      unsetenv(name)
+    }
+  }
+}

Tests/TartTests/ContentStoreTests.swift

@@ -0,0 +1,190 @@
+import Foundation
+import XCTest
+@testable import tart
+
+final class ContentStoreTests: XCTestCase {
+  func testCreatesDigestDirectoryDuringInitialization() throws {
+    let store = try temporaryStore()
+    let contentURL = try store.contentURL(for: Digest.hash(Data()))
+
+    XCTAssertTrue(FileManager.default.fileExists(atPath: contentURL.deletingLastPathComponent().path))
+  }
+
+  func testInstallAndValidatedLookup() throws {
+    let store = try temporaryStore()
+    let data = Data("base disk".utf8)
+    let digest = Digest.hash(data)
+    let temporaryURL = try store.temporaryContentURL(for: digest)
+    try data.write(to: temporaryURL)
+
+    let installedURL = try store.install(temporaryURL, contentDigest: digest)
+
+    XCTAssertEqual(installedURL, try store.contentURL(for: digest))
+    XCTAssertEqual(try store.existingContentURL(for: digest), installedURL)
+  }
+
+  func testCorruptCacheEntryIsMiss() throws {
+    let store = try temporaryStore()
+    let expectedDigest = Digest.hash(Data("expected".utf8))
+    let contentURL = try store.contentURL(for: expectedDigest)
+    try FileManager.default.createDirectory(at: contentURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    try Data("corrupt".utf8).write(to: contentURL)
+
+    XCTAssertNil(try store.existingContentURL(for: expectedDigest))
+    XCTAssertEqual(try store.contentURLIfPresent(for: expectedDigest), contentURL)
+  }
+
+  func testResumableAndLockURLsAreStablePerDigest() throws {
+    let store = try temporaryStore()
+    let firstDigest = Digest.hash(Data("first".utf8))
+    let secondDigest = Digest.hash(Data("second".utf8))
+
+    XCTAssertEqual(
+      try store.resumableContentURL(for: firstDigest),
+      try store.resumableContentURL(for: firstDigest)
+    )
+    XCTAssertNotEqual(
+      try store.resumableContentURL(for: firstDigest),
+      try store.resumableContentURL(for: secondDigest)
+    )
+    XCTAssertEqual(
+      try store.lockURL(for: firstDigest),
+      try store.lockURL(for: firstDigest)
+    )
+    XCTAssertTrue(FileManager.default.fileExists(atPath: try store.lockURL(for: firstDigest).path))
+  }
+
+  func testInstallReplacesCorruptEntry() throws {
+    let store = try temporaryStore()
+    let data = Data("expected".utf8)
+    let digest = Digest.hash(data)
+    let contentURL = try store.contentURL(for: digest)
+    try FileManager.default.createDirectory(at: contentURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    try Data("corrupt".utf8).write(to: contentURL)
+    let temporaryURL = try store.temporaryContentURL(for: digest)
+    try data.write(to: temporaryURL)
+
+    XCTAssertEqual(try store.install(temporaryURL, contentDigest: digest), contentURL)
+    XCTAssertEqual(try Digest.hash(contentURL), digest)
+  }
+
+  func testInstallPreservesExistingValidEntry() throws {
+    let store = try temporaryStore()
+    let data = Data("expected".utf8)
+    let digest = Digest.hash(data)
+    let firstTemporaryURL = try store.temporaryContentURL(for: digest)
+    try data.write(to: firstTemporaryURL)
+    let installedURL = try store.install(firstTemporaryURL, contentDigest: digest)
+    let secondTemporaryURL = try store.temporaryContentURL(for: digest)
+    try data.write(to: secondTemporaryURL)
+
+    XCTAssertEqual(try store.install(secondTemporaryURL, contentDigest: digest), installedURL)
+    XCTAssertFalse(FileManager.default.fileExists(atPath: secondTemporaryURL.path))
+    XCTAssertEqual(try Digest.hash(installedURL), digest)
+  }
+
+  func testConcurrentInstallsAcceptDigestValidWinner() throws {
+    try assertConcurrentInstalls(seedCorruptEntry: false)
+  }
+
+  func testConcurrentInstallsRepairCorruptEntry() throws {
+    try assertConcurrentInstalls(seedCorruptEntry: true)
+  }
+
+  func testInstallRejectsWrongContentDigest() throws {
+    let store = try temporaryStore()
+    let expectedDigest = Digest.hash(Data("expected".utf8))
+    let temporaryURL = try store.temporaryContentURL(for: expectedDigest)
+    try Data("actual".utf8).write(to: temporaryURL)
+
+    XCTAssertThrowsError(try store.install(temporaryURL, contentDigest: expectedDigest)) { error in
+      guard case ContentStoreError.contentDigestMismatch(let expected, _) = error else {
+        return XCTFail("unexpected error: \(error)")
+      }
+
+      XCTAssertEqual(expected, expectedDigest)
+    }
+  }
+
+  func testRejectsNonCanonicalDigest() throws {
+    let store = try temporaryStore()
+
+    XCTAssertThrowsError(try store.contentURL(for: "sha256:ABC")) { error in
+      XCTAssertEqual(error as? ContentStoreError, .invalidContentDigest("sha256:ABC"))
+    }
+  }
+
+  func testContentURLUnderArbitraryRootHasNoSideEffects() throws {
+    let rootURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: rootURL)
+    }
+    let digest = Digest.hash(Data("content".utf8))
+
+    let contentStore = try temporaryStore()
+    let contentURL = try contentStore.contentURL(for: digest, under: rootURL)
+
+    XCTAssertEqual(
+      contentURL,
+      rootURL.appendingPathComponent("sha256", isDirectory: true)
+        .appendingPathComponent(String(digest.dropFirst("sha256:".count)))
+    )
+    XCTAssertFalse(FileManager.default.fileExists(atPath: rootURL.path))
+  }
+
+  private func temporaryStore() throws -> ContentStore {
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: url)
+    }
+
+    return try ContentStore(baseURL: url)
+  }
+
+  private func assertConcurrentInstalls(seedCorruptEntry: Bool) throws {
+    let store = try temporaryStore()
+    let data = Data("expected".utf8)
+    let digest = Digest.hash(data)
+    let contentURL = try store.contentURL(for: digest)
+    try FileManager.default.createDirectory(at: contentURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    if seedCorruptEntry {
+      try Data("corrupt".utf8).write(to: contentURL)
+    }
+
+    let temporaryURLs = try (0..<16).map { _ in
+      let url = try store.temporaryContentURL(for: digest)
+      try data.write(to: url)
+      return url
+    }
+    let errors = ErrorCollector()
+
+    DispatchQueue.concurrentPerform(iterations: temporaryURLs.count) { index in
+      do {
+        _ = try store.install(temporaryURLs[index], contentDigest: digest)
+      } catch {
+        errors.append(error)
+      }
+    }
+
+    XCTAssertTrue(errors.values.isEmpty, "unexpected install errors: \(errors.values)")
+    XCTAssertEqual(try Digest.hash(contentURL), digest)
+    XCTAssertTrue(temporaryURLs.allSatisfy { !FileManager.default.fileExists(atPath: $0.path) })
+  }
+
+  private final class ErrorCollector: @unchecked Sendable {
+    private let lock = NSLock()
+    private var errors: [Error] = []
+
+    var values: [Error] {
+      lock.lock()
+      defer { lock.unlock() }
+      return errors
+    }
+
+    func append(_ error: Error) {
+      lock.lock()
+      defer { lock.unlock() }
+      errors.append(error)
+    }
+  }
+}

Tests/TartTests/ControlSocketTests.swift

@@ -0,0 +1,55 @@
+import XCTest
+@testable import tart
+
+@available(macOS 14, *)
+final class ControlSocketTests: XCTestCase {
+  func testInitializerCreatesControlSocketBeforeReturning() async throws {
+    let temporaryDirectory = try makeTemporaryDirectory()
+    let originalDirectory = FileManager.default.currentDirectoryPath
+    defer {
+      FileManager.default.changeCurrentDirectoryPath(originalDirectory)
+      try? FileManager.default.removeItem(at: temporaryDirectory)
+    }
+
+    let socketURL = URL(fileURLWithPath: "control.sock", relativeTo: temporaryDirectory)
+    var controlSocket: ControlSocket? = try await ControlSocket(socketURL)
+    let eventLoopGroup = try XCTUnwrap(controlSocket?.eventLoopGroup)
+
+    do {
+      let serverChannel = try XCTUnwrap(controlSocket?.serverChannel)
+      XCTAssertTrue(FileManager.default.fileExists(atPath: socketURL.path))
+
+      try await serverChannel.executeThenClose { _ in }
+    }
+
+    controlSocket = nil
+    try await eventLoopGroup.shutdownGracefully()
+  }
+
+  func testInitializerPropagatesControlSocketCreationFailure() async throws {
+    let temporaryDirectory = try makeTemporaryDirectory()
+    let originalDirectory = FileManager.default.currentDirectoryPath
+    defer {
+      FileManager.default.changeCurrentDirectoryPath(originalDirectory)
+      try? FileManager.default.removeItem(at: temporaryDirectory)
+    }
+
+    let socketURL = URL(fileURLWithPath: "missing/control.sock", relativeTo: temporaryDirectory)
+
+    do {
+      _ = try await ControlSocket(socketURL)
+      XCTFail("Binding should fail when the socket's parent directory does not exist")
+    } catch {
+      XCTAssertFalse(FileManager.default.fileExists(atPath: socketURL.path))
+    }
+  }
+
+  private func makeTemporaryDirectory() throws -> URL {
+    let directory = FileManager.default.temporaryDirectory.appendingPathComponent(
+      UUID().uuidString,
+      isDirectory: true
+    )
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: false)
+    return directory
+  }
+}

Tests/TartTests/DigestTests.swift

@@ -1,3 +1,4 @@
+import Foundation
 import XCTest
 @testable import tart
 
@@ -21,4 +22,34 @@ final class DigestTests: XCTestCase {
 
     XCTAssertEqual(Digest.hash(data), "sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592")
   }
+
+  func testFileAndRangeHashingMatchDataHashing() throws {
+    let prefix = Data(repeating: 0x61, count: 4 * 1024 * 1024 + 17)
+    let range = Data("range".utf8)
+    let suffix = Data(repeating: 0x62, count: 23)
+    let data = prefix + range + suffix
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    try data.write(to: url)
+    defer { try? FileManager.default.removeItem(at: url) }
+
+    XCTAssertEqual(try Digest.hash(url), Digest.hash(data))
+    XCTAssertEqual(try Digest.hash(url, offset: UInt64(prefix.count), size: UInt64(range.count)), Digest.hash(range))
+  }
+
+  func testRangeHashingRejectsOutOfBoundsRanges() throws {
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    try Data("range".utf8).write(to: url)
+    defer { try? FileManager.default.removeItem(at: url) }
+
+    XCTAssertThrowsError(try Digest.hash(url, offset: 6, size: 0)) { error in
+      guard case DigestError.InvalidOffset = error else {
+        return XCTFail("unexpected error: \(error)")
+      }
+    }
+    XCTAssertThrowsError(try Digest.hash(url, offset: 1, size: UInt64.max)) { error in
+      guard case DigestError.InvalidSize = error else {
+        return XCTFail("unexpected error: \(error)")
+      }
+    }
+  }
 }

Tests/TartTests/DiskImageFormatTests.swift

@@ -2,13 +2,9 @@ import XCTest
 @testable import tart
 
 final class DiskImageFormatTests: XCTestCase {
-  func testRawFormatIsAlwaysSupported() throws {
-    XCTAssertTrue(DiskImageFormat.raw.isSupported)
-  }
-
   func testASIFFormatSupport() throws {
-    // ASIF should be supported on macOS 15+
-    if #available(macOS 15, *) {
+    // ASIF should be supported on macOS 26+
+    if #available(macOS 26, *) {
       XCTAssertTrue(DiskImageFormat.asif.isSupported)
     } else {
       XCTAssertFalse(DiskImageFormat.asif.isSupported)

Tests/TartTests/DiskImageStackTests.swift

@@ -0,0 +1,263 @@
+import Foundation
+import XCTest
+@testable import tart
+
+#if canImport(DiskImageKit)
+  import DiskImageKit
+
+  @available(macOS 27.0, *)
+  final class DiskImageStackTests: XCTestCase {
+    override func setUpWithError() throws {
+      try super.setUpWithError()
+
+      if #unavailable(macOS 27.0) {
+        throw XCTSkip("DiskImageKit tests require macOS 27 or newer")
+      }
+    }
+
+    func testCreatesAndAttachesRawBaseWithWritableOverlay() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+
+      try fixture.disk.createWritableOverlay()
+      XCTAssertTrue(FileManager.default.fileExists(atPath: fixture.disk.writableOverlayURL.path))
+
+      _ = try fixture.disk.makeAttachment()
+    }
+
+    func testCreatesAndAttachesASIFBaseWithPublishedOverlay() throws {
+      let fixture = try Fixture(baseFormat: .asif, publishedOverlayCount: 1)
+
+      try fixture.disk.createWritableOverlay()
+      _ = try fixture.disk.makeAttachment()
+    }
+
+    func testCreatesAndAttachesMultiplePublishedOverlays() throws {
+      let fixture = try Fixture(baseFormat: .asif, publishedOverlayCount: 2)
+
+      try fixture.disk.createWritableOverlay()
+      _ = try fixture.disk.makeAttachment()
+    }
+
+    func testCreatesAndAttachesLongPublishedOverlayChain() throws {
+      let fixture = try Fixture(baseFormat: .asif, publishedOverlayCount: 8)
+
+      try fixture.disk.createWritableOverlay()
+      _ = try fixture.disk.makeAttachment()
+    }
+
+    func testAttachesStackReadOnly() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      try fixture.disk.createWritableOverlay()
+
+      _ = try fixture.disk.makeAttachment(readOnly: true)
+    }
+
+    func testRejectsMissingWritableOverlayWhenAttaching() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+
+      assertThrows(.writableOverlayMissing(fixture.disk.writableOverlayURL)) {
+        try fixture.disk.makeAttachment()
+      }
+    }
+
+    func testRejectsExistingWritableOverlayWhenCreating() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      XCTAssertTrue(FileManager.default.createFile(atPath: fixture.disk.writableOverlayURL.path, contents: nil))
+
+      assertThrows(.writableOverlayAlreadyExists(fixture.disk.writableOverlayURL)) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsExistingCopyDestination() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      try fixture.disk.createWritableOverlay()
+
+      let destinationURL = fixture.directory.appendingPathComponent("existing-overlay.asif")
+      XCTAssertTrue(FileManager.default.createFile(atPath: destinationURL.path, contents: nil))
+
+      assertThrows(.writableOverlayAlreadyExists(destinationURL)) {
+        try fixture.disk.copyWritableOverlay(to: destinationURL)
+      }
+    }
+
+    func testRejectsNonASIFPublishedOverlay() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      let overlayURL = fixture.directory.appendingPathComponent("published-raw.img")
+      _ = try DiskImage(creating: .raw(url: overlayURL, blockCount: 8))
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: [
+          overlayURL,
+        ],
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: fixture.disk.blockSize,
+        blockCount: fixture.disk.blockCount
+      )
+
+      assertThrows(.invalidDiskImage(overlayURL, "overlay must use ASIF format")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsWrongBaseFormat() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: .asif,
+        immutableOverlayURLs: fixture.disk.immutableOverlayURLs,
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: fixture.disk.blockSize,
+        blockCount: fixture.disk.blockCount
+      )
+
+      assertThrows(.invalidDiskImage(fixture.disk.baseURL, "base disk format does not match")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsBlockSizeMismatch() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: fixture.disk.immutableOverlayURLs,
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: 4096,
+        blockCount: fixture.disk.blockCount
+      )
+
+      assertThrows(.invalidBlockLayout("immutable disk stack does not match manifest block size")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsUnsupportedBlockSize() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: fixture.disk.immutableOverlayURLs,
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: 123,
+        blockCount: fixture.disk.blockCount
+      )
+
+      assertThrows(.invalidBlockLayout("unsupported stacked disk block size 123")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsManifestBlockCountMismatch() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: fixture.disk.immutableOverlayURLs,
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: fixture.disk.blockSize,
+        blockCount: fixture.disk.blockCount + 1
+      )
+
+      assertThrows(.invalidBlockLayout("immutable disk stack does not match manifest block count")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testCopiesAndGrowsWritableOverlay() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      try fixture.disk.createWritableOverlay()
+
+      let copiedURL = fixture.directory.appendingPathComponent("copied-overlay.asif")
+      try fixture.disk.copyWritableOverlay(to: copiedURL)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: fixture.disk.immutableOverlayURLs,
+        writableOverlayURL: copiedURL,
+        blockSize: fixture.disk.blockSize,
+        blockCount: fixture.disk.blockCount
+      )
+      try fixture.disk.growWritableOverlay(toBlockCount: 16)
+
+      let copied = try DiskImage(opening: .open(url: copiedURL, mode: .readOnly))
+      XCTAssertEqual(copied.blockCount, 16)
+    }
+
+    func testRejectsOverlayFromDifferentASIFParent() throws {
+      let fixture = try Fixture(baseFormat: .asif)
+      let other = try Fixture(baseFormat: .asif, publishedOverlayCount: 1)
+      fixture.disk = DiskImageStack(
+        baseURL: fixture.disk.baseURL,
+        baseFormat: fixture.disk.baseFormat,
+        immutableOverlayURLs: other.disk.immutableOverlayURLs,
+        writableOverlayURL: fixture.disk.writableOverlayURL,
+        blockSize: fixture.disk.blockSize,
+        blockCount: fixture.disk.blockCount
+      )
+
+      assertThrows(.invalidDiskImage(other.disk.immutableOverlayURLs[0], "ASIF overlay is incompatible with its parent")) {
+        try fixture.disk.createWritableOverlay()
+      }
+    }
+
+    func testRejectsWritableOverlayShrink() throws {
+      let fixture = try Fixture(baseFormat: .raw)
+      try fixture.disk.createWritableOverlay()
+
+      assertThrows(.invalidDiskImage(fixture.disk.writableOverlayURL, "ASIF overlay block count shrinks the stacked disk")) {
+        try fixture.disk.growWritableOverlay(toBlockCount: 4)
+      }
+    }
+
+    private func assertThrows<T>(
+      _ expected: DiskImageStackError,
+      operation: () throws -> T
+    ) {
+      XCTAssertThrowsError(try operation()) { error in
+        XCTAssertEqual(error as? DiskImageStackError, expected)
+      }
+    }
+
+    private final class Fixture {
+      let directory: URL
+      var disk: DiskImageStack
+
+      init(baseFormat: DiskImageFormat, publishedOverlayCount: Int = 0) throws {
+        directory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: false)
+
+        let baseURL = directory.appendingPathComponent("base.img")
+        switch baseFormat {
+        case .raw:
+          _ = try DiskImage(creating: .raw(url: baseURL, blockCount: 8))
+        case .asif:
+          _ = try DiskImage(creating: .asif(url: baseURL, blockCount: 8, blockSize: .bytes512))
+        }
+
+        var immutableOverlayURLs: [URL] = []
+        var image = try DiskImage(opening: .open(url: baseURL, mode: .readOnly))
+        for index in 0..<publishedOverlayCount {
+          let overlayURL = directory.appendingPathComponent("published-\(index).asif")
+          let stack = try image.appending(.asifLayer(url: overlayURL, type: .overlay))
+          immutableOverlayURLs.append(overlayURL)
+          image = stack
+        }
+
+        disk = DiskImageStack(
+          baseURL: baseURL,
+          baseFormat: baseFormat,
+          immutableOverlayURLs: immutableOverlayURLs,
+          writableOverlayURL: directory.appendingPathComponent("overlay.asif"),
+          blockSize: 512,
+          blockCount: 8
+        )
+      }
+
+      deinit {
+        try? FileManager.default.removeItem(at: directory)
+      }
+    }
+  }
+#endif

Tests/TartTests/DiskutilTests.swift

@@ -0,0 +1,21 @@
+import XCTest
+@testable import tart
+
+final class DiskutilTests: XCTestCase {
+  func testDiskutilInfo() throws {
+    // Create a temporary directory
+    let tempDirURL = FileManager.default.temporaryDirectory.appendingPathComponent("tart-diskutil-tests-\(UUID().uuidString)")
+    try? FileManager.default.createDirectory(at: tempDirURL, withIntermediateDirectories: true)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: tempDirURL)
+    }
+
+    // Create a 123 GB ASIF disk
+    let diskURL = tempDirURL.appendingPathComponent("disk.asif")
+    try Diskutil.imageCreate(diskURL: diskURL, sizeGB: 123)
+
+    // Retrieve its information and ensure that it does indeed take 123 GB
+    let info = try Diskutil.imageInfo(diskURL)
+    XCTAssertEqual(123 * 1000 * 1000 * 1000, try info.totalBytes())
+  }
+}

Tests/TartTests/HumanReadableByteCountTests.swift

@@ -0,0 +1,15 @@
+import Foundation
+import XCTest
+@testable import tart
+
+final class HumanReadableByteCountTests: XCTestCase {
+  func testTextAndJSONRepresentations() throws {
+    let integer = HumanReadableByteCount(51_400_000_000) { _ in 51 }
+    let string = HumanReadableByteCount(17_234_000_000) { _ in "17.234" }
+    let encoder = JSONEncoder()
+
+    XCTAssertEqual(string.description.compactMap(\.wholeNumberValue), [1, 7])
+    XCTAssertEqual(try JSONDecoder().decode(Int.self, from: encoder.encode(integer)), 51)
+    XCTAssertEqual(try JSONDecoder().decode(String.self, from: encoder.encode(string)), "17.234")
+  }
+}

Tests/TartTests/LayerizerTests.swift

@@ -14,7 +14,7 @@ final class LayerizerTests: XCTestCase {
     do {
       registryRunner = try await RegistryRunner()
     } catch {
-      try XCTSkipIf(ProcessInfo.processInfo.environment["CI"] == nil)
+      throw XCTSkip("Registry is unavailable: \(error)")
     }
   }
 
@@ -24,30 +24,9 @@ final class LayerizerTests: XCTestCase {
     registryRunner = nil
   }
 
-  func testDiskV1() async throws {
-    // Original disk file to be pushed to the registry
-    let originalDiskFileURL = try fileWithRandomData(sizeBytes: 5 * 1024 * 1024 * 1024)
-    addTeardownBlock {
-      try FileManager.default.removeItem(at: originalDiskFileURL)
-    }
-
-    // Disk file to be pulled from the registry
-    // and compared against the original disk file
-    let pulledDiskFileURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
-
-    print("pushing disk...")
-    let diskLayers = try await DiskV1.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, concurrency: 4, progress: Progress())
-
-    print("pulling disk...")
-    try await DiskV1.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())
-
-    print("comparing disks...")
-    try XCTAssertEqual(Digest.hash(originalDiskFileURL), Digest.hash(pulledDiskFileURL))
-  }
-
   func testDiskV2() async throws {
     // Original disk file to be pushed to the registry
-    let originalDiskFileURL = try fileWithRandomData(sizeBytes: 5 * 1024 * 1024 * 1024)
+    let originalDiskFileURL = try fileWithRandomData(sizeBytes: 1 * 1024 * 1024 * 1024)
     addTeardownBlock {
       try FileManager.default.removeItem(at: originalDiskFileURL)
     }
@@ -57,7 +36,14 @@ final class LayerizerTests: XCTestCase {
     let pulledDiskFileURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
 
     print("pushing disk...")
-    let diskLayers = try await DiskV2.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, concurrency: 4, progress: Progress())
+    let diskLayers = try await DiskV2.push(
+      diskURL: originalDiskFileURL,
+      mediaType: diskV2MediaType,
+      registry: registry,
+      chunkSizeMb: 0,
+      concurrency: 4,
+      progress: Progress()
+    )
 
     print("pulling disk...")
     try await DiskV2.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())

Tests/TartTests/OCIManifestTests.swift

@@ -0,0 +1,196 @@
+import XCTest
+@testable import tart
+
+final class OCIManifestTests: XCTestCase {
+  func testFlatDiskRepresentation() throws {
+    let chunks = [chunk(mediaType: diskV2MediaType, suffix: "base-0")]
+    let representation = try manifest(diskDescriptors: chunks).tartDiskRepresentation()
+
+    XCTAssertEqual(representation, .flat(base: TartDiskFileGroup(kind: .base, chunks: chunks, contentDigest: nil)))
+  }
+
+  func testStackedDiskRepresentation() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base")
+    let overlay0 = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-0", diskFileDigest: "sha256:overlay", chunkCount: 2)
+    let overlay1 = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-1")
+    let representation = try manifest(diskDescriptors: [base, overlay0, overlay1]).tartDiskRepresentation()
+
+    XCTAssertEqual(representation, .stacked(
+      base: TartDiskFileGroup(kind: .base, chunks: [base], contentDigest: "sha256:base"),
+      overlays: [TartDiskFileGroup(kind: .asifOverlay, chunks: [overlay0, overlay1], contentDigest: "sha256:overlay")]
+    ))
+  }
+
+  func testDiskFileGroupUncompressedSize() {
+    let first = chunk(mediaType: diskV2MediaType, suffix: "base-0")
+    let second = chunk(mediaType: diskV2MediaType, suffix: "base-1")
+    XCTAssertEqual(TartDiskFileGroup(kind: .base, chunks: [first, second], contentDigest: nil).uncompressedSize(), 2)
+
+    var overflowing = first
+    overflowing.annotations?[uncompressedSizeAnnotation] = String(UInt64.max)
+    XCTAssertNil(TartDiskFileGroup(kind: .base, chunks: [overflowing, second], contentDigest: nil).uncompressedSize())
+  }
+
+  func testDiskContentDigests() throws {
+    let flatBase = chunk(mediaType: diskV2MediaType, suffix: "flat", diskFileDigest: "sha256:flat")
+    XCTAssertEqual(try manifest(diskDescriptors: [flatBase]).diskContentDigests(), ["sha256:flat"])
+
+    let stackedBase = chunk(mediaType: diskV2MediaType, suffix: "base", diskFileDigest: "sha256:base")
+    let overlay = chunk(
+      mediaType: asifOverlayMediaType,
+      suffix: "overlay",
+      diskFileDigest: "sha256:overlay",
+      chunkCount: 1
+    )
+    XCTAssertEqual(
+      try manifest(diskDescriptors: [stackedBase, overlay]).diskContentDigests(),
+      ["sha256:base", "sha256:overlay"]
+    )
+  }
+
+  func testStackedRepresentationRequiresBaseDigest() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0")
+    let overlay = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-0", diskFileDigest: "sha256:overlay", chunkCount: 1)
+
+    assertManifestError(
+      .invalidDiskMetadata("a stacked base disk needs a whole-file content digest"),
+      diskDescriptors: [base, overlay]
+    )
+  }
+
+  func testBaseGroupRejectsMetadataAfterFirstChunk() throws {
+    let base0 = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base")
+    let base1 = chunk(mediaType: diskV2MediaType, suffix: "base-1", diskFileDigest: "sha256:other-base")
+
+    assertManifestError(
+      .invalidDiskMetadata("base disk metadata must appear only on its first chunk"),
+      diskDescriptors: [base0, base1]
+    )
+  }
+
+  func testBaseGroupRejectsOverlayChunkCount() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base", chunkCount: 1)
+
+    assertManifestError(
+      .invalidDiskMetadata("base disk metadata must appear only on its first chunk"),
+      diskDescriptors: [base]
+    )
+  }
+
+  func testOverlayGroupRequiresDigestAndChunkCount() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base")
+    let overlay = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-0")
+
+    assertManifestError(
+      .invalidDiskMetadata("an ASIF overlay needs a content digest and chunk count"),
+      diskDescriptors: [base, overlay]
+    )
+  }
+
+  func testOverlayGroupRejectsInconsistentChunkCount() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base")
+    let overlay = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-0", diskFileDigest: "sha256:overlay", chunkCount: 2)
+
+    assertManifestError(
+      .invalidDiskMetadata("ASIF overlay chunk count is invalid"),
+      diskDescriptors: [base, overlay]
+    )
+  }
+
+  func testDiskV2AfterOverlayIsRejected() throws {
+    let base = chunk(mediaType: diskV2MediaType, suffix: "base-0", diskFileDigest: "sha256:base")
+    let overlay = chunk(mediaType: asifOverlayMediaType, suffix: "overlay-0", diskFileDigest: "sha256:overlay", chunkCount: 2)
+    let lateBase = chunk(mediaType: diskV2MediaType, suffix: "base-1")
+
+    assertManifestError(
+      .invalidLayout("ASIF overlay chunks must be contiguous"),
+      diskDescriptors: [base, overlay, lateBase]
+    )
+  }
+
+  func testChunkMetadataIsRequired() throws {
+    var base = chunk(mediaType: diskV2MediaType, suffix: "base-0")
+    base.annotations = nil
+
+    assertManifestError(
+      .invalidDiskMetadata("disk chunks need uncompressed size and content digest"),
+      diskDescriptors: [base]
+    )
+  }
+
+  func testCanonicalConfigAndNVRAMOrderIsRequired() throws {
+    let disk = chunk(mediaType: diskV2MediaType, suffix: "base-0")
+    let manifest = OCIManifest(
+      config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+      layers: [disk, configLayer(), nvramLayer()]
+    )
+
+    XCTAssertThrowsError(try manifest.tartDiskRepresentation()) { error in
+      XCTAssertEqual(
+        error as? OCIManifestValidationError,
+        .invalidLayout("descriptors must be ordered as config, disk chunks, then NVRAM")
+      )
+    }
+  }
+
+  func testManifestBlockLayout() throws {
+    var manifest = manifest(diskDescriptors: [chunk(mediaType: diskV2MediaType, suffix: "base-0")])
+    manifest.annotations = [
+      uncompressedDiskSizeAnnotation: "100000000000",
+      diskBlockSizeAnnotation: "512",
+    ]
+
+    XCTAssertEqual(manifest.diskBlockSize(), 512)
+    XCTAssertEqual(manifest.diskBlockCount(), 195312500)
+  }
+
+  func testManifestRejectsInexactDerivedBlockCount() throws {
+    var manifest = manifest(diskDescriptors: [chunk(mediaType: diskV2MediaType, suffix: "base-0")])
+    manifest.annotations = [
+      uncompressedDiskSizeAnnotation: "513",
+      diskBlockSizeAnnotation: "512",
+    ]
+
+    XCTAssertNil(manifest.diskBlockCount())
+  }
+
+  private func assertManifestError(_ expected: OCIManifestValidationError, diskDescriptors: [OCIManifestLayer]) {
+    XCTAssertThrowsError(try manifest(diskDescriptors: diskDescriptors).tartDiskRepresentation()) { error in
+      XCTAssertEqual(error as? OCIManifestValidationError, expected)
+    }
+  }
+
+  private func manifest(diskDescriptors: [OCIManifestLayer]) -> OCIManifest {
+    OCIManifest(
+      config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+      layers: [configLayer()] + diskDescriptors + [nvramLayer()]
+    )
+  }
+
+  private func configLayer() -> OCIManifestLayer {
+    OCIManifestLayer(mediaType: configMediaType, size: 1, digest: "sha256:tart-config")
+  }
+
+  private func nvramLayer() -> OCIManifestLayer {
+    OCIManifestLayer(mediaType: nvramMediaType, size: 1, digest: "sha256:nvram")
+  }
+
+  private func chunk(mediaType: String, suffix: String, diskFileDigest: String? = nil, chunkCount: Int? = nil) -> OCIManifestLayer {
+    var descriptor = OCIManifestLayer(
+      mediaType: mediaType,
+      size: 1,
+      digest: "sha256:\(suffix)",
+      uncompressedSize: 1,
+      uncompressedContentDigest: "sha256:uncompressed-\(suffix)"
+    )
+
+    if let diskFileDigest {
+      descriptor.annotations?[diskFileContentDigestAnnotation] = diskFileDigest
+    }
+    if let chunkCount {
+      descriptor.annotations?[diskFileChunkCountAnnotation] = String(chunkCount)
+    }
+
+    return descriptor
+  }
+}

Tests/TartTests/RegistryTests.swift

@@ -10,7 +10,7 @@ final class RegistryTests: XCTestCase {
     do {
       registryRunner = try await RegistryRunner()
     } catch {
-      try XCTSkipIf(ProcessInfo.processInfo.environment["CI"] == nil)
+      throw XCTSkip("Registry is unavailable: \(error)")
     }
   }
 

Tests/TartTests/SoftnetControlFDTests.swift

@@ -0,0 +1,183 @@
+import XCTest
+@testable import tart
+
+import Semaphore
+
+final class SoftnetControlFDTests: XCTestCase {
+  func testConnectedUnixStreamSocketIsAccepted() throws {
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(socketpair(AF_UNIX, SOCK_STREAM, 0, &fds), 0)
+    defer {
+      close(fds[0])
+      close(fds[1])
+    }
+
+    XCTAssertNoThrow(try Softnet.validateControlFD(fds[0]))
+  }
+
+  func testUnixDatagramSocketIsRejected() throws {
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(socketpair(AF_UNIX, SOCK_DGRAM, 0, &fds), 0)
+    defer {
+      close(fds[0])
+      close(fds[1])
+    }
+
+    XCTAssertThrowsError(try Softnet.validateControlFD(fds[0]))
+  }
+
+  func testUnconnectedUnixStreamSocketIsRejected() throws {
+    let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+    XCTAssertGreaterThan(fd, STDERR_FILENO)
+    defer { close(fd) }
+
+    XCTAssertThrowsError(try Softnet.validateControlFD(fd))
+  }
+
+  func testPipeIsRejected() throws {
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(pipe(&fds), 0)
+    defer {
+      close(fds[0])
+      close(fds[1])
+    }
+
+    XCTAssertThrowsError(try Softnet.validateControlFD(fds[0]))
+  }
+
+  func testStandardDescriptorsAreRejected() throws {
+    XCTAssertThrowsError(try Softnet.validateControlFD(STDIN_FILENO))
+    XCTAssertThrowsError(try Softnet.validateControlFD(STDOUT_FILENO))
+    XCTAssertThrowsError(try Softnet.validateControlFD(STDERR_FILENO))
+  }
+
+  func testStandardDescriptorsRemainOpenWhenInitializationFails() throws {
+    for fd in [STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO] {
+      let flags = fcntl(fd, F_GETFD)
+      XCTAssertNotEqual(flags, -1)
+
+      XCTAssertThrowsError(try Softnet(vmMACAddress: "02:00:00:00:00:01", controlFD: fd))
+      XCTAssertEqual(fcntl(fd, F_GETFD), flags)
+    }
+  }
+
+  func testControlChannelIsPassedToSoftnetAndVMFDRemainsDatagram() async throws {
+    let temporaryDirectory = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString)
+    try FileManager.default.createDirectory(at: temporaryDirectory, withIntermediateDirectories: false)
+    defer { try? FileManager.default.removeItem(at: temporaryDirectory) }
+
+    let executable = temporaryDirectory.appendingPathComponent("softnet")
+    let script = """
+    #!/usr/bin/env python3
+    import socket
+    import sys
+
+    assert sys.argv[1:] == ["--vm-fd", "0", "--vm-mac-address", "02:00:00:00:00:01", "--control-fd", "1"]
+    vm = socket.socket(fileno=0)
+    control = socket.socket(fileno=1)
+    assert vm.family == socket.AF_UNIX and vm.type == socket.SOCK_DGRAM
+    assert control.family == socket.AF_UNIX and control.type == socket.SOCK_STREAM
+    assert control.recv(4096) == b"softnet.policy.set\\n"
+    control.sendall(b"ok\\n")
+    """
+    try script.write(to: executable, atomically: true, encoding: .utf8)
+    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: executable.path)
+
+    let previousPath = ProcessInfo.processInfo.environment["PATH"] ?? ""
+    setenv("PATH", "\(temporaryDirectory.path):\(previousPath)", 1)
+    defer { setenv("PATH", previousPath, 1) }
+
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(socketpair(AF_UNIX, SOCK_STREAM, 0, &fds), 0)
+    defer { close(fds[1]) }
+
+    var timeout = timeval(tv_sec: 5, tv_usec: 0)
+    XCTAssertEqual(setsockopt(fds[1], SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size)), 0)
+
+    let semaphore = AsyncSemaphore(value: 0)
+    let softnet = try Softnet(vmMACAddress: "02:00:00:00:00:01", controlFD: fds[0])
+    try softnet.run(semaphore)
+
+    XCTAssertEqual(fcntl(fds[0], F_GETFD), -1)
+    XCTAssertEqual(errno, EBADF)
+
+    let request = Array("softnet.policy.set\n".utf8)
+    XCTAssertEqual(request.withUnsafeBytes { send(fds[1], $0.baseAddress, $0.count, 0) }, request.count)
+
+    var response = [UInt8](repeating: 0, count: 128)
+    let received = recv(fds[1], &response, response.count, 0)
+    XCTAssertGreaterThan(received, 0)
+    XCTAssertEqual(String(decoding: response.prefix(Int(max(received, 0))), as: UTF8.self), "ok\n")
+
+    await semaphore.wait()
+  }
+
+  func testControlFDIsClosedWhenSoftnetInitializationFails() throws {
+    let previousPath = ProcessInfo.processInfo.environment["PATH"] ?? ""
+    setenv("PATH", "/this/path/does/not/exist", 1)
+    defer { setenv("PATH", previousPath, 1) }
+
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(socketpair(AF_UNIX, SOCK_STREAM, 0, &fds), 0)
+    defer { close(fds[1]) }
+
+    XCTAssertThrowsError(try Softnet(vmMACAddress: "02:00:00:00:00:01", controlFD: fds[0]))
+    XCTAssertEqual(fcntl(fds[0], F_GETFD), -1)
+    XCTAssertEqual(errno, EBADF)
+  }
+
+  func testControlFDIsClosedWhenSoftnetValidationFails() throws {
+    var fds: [Int32] = [-1, -1]
+    XCTAssertEqual(socketpair(AF_UNIX, SOCK_DGRAM, 0, &fds), 0)
+    defer { close(fds[1]) }
+
+    XCTAssertThrowsError(try Softnet(vmMACAddress: "02:00:00:00:00:01", controlFD: fds[0]))
+    XCTAssertEqual(fcntl(fds[0], F_GETFD), -1)
+    XCTAssertEqual(errno, EBADF)
+  }
+
+  func testControlFDImpliesSoftnet() throws {
+    let temporaryHome = try createTemporaryTartHome()
+    defer { try? FileManager.default.removeItem(at: temporaryHome) }
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", temporaryHome.path, 1)
+    defer { restoreEnvironment("TART_HOME", value: previousHome) }
+
+    let command = try Run.parse(["vm", "--net-softnet-control-fd", "3"])
+
+    XCTAssertTrue(command.netSoftnet)
+    XCTAssertEqual(command.netSoftnetControlFd, 3)
+  }
+
+  func testControlFDIsRejectedWithHostNetworking() throws {
+    let temporaryHome = try createTemporaryTartHome()
+    defer { try? FileManager.default.removeItem(at: temporaryHome) }
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", temporaryHome.path, 1)
+    defer { restoreEnvironment("TART_HOME", value: previousHome) }
+
+    XCTAssertThrowsError(
+      try Run.parse(["vm", "--net-host", "--net-softnet-control-fd", "3"])
+    )
+  }
+
+  private func createTemporaryTartHome() throws -> URL {
+    let temporaryHome = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString)
+    let vm = temporaryHome.appendingPathComponent("vms/vm")
+    try FileManager.default.createDirectory(at: vm, withIntermediateDirectories: true)
+
+    for name in ["config.json", "disk.img", "nvram.bin"] {
+      XCTAssertTrue(FileManager.default.createFile(atPath: vm.appendingPathComponent(name).path, contents: nil))
+    }
+
+    return temporaryHome
+  }
+
+  private func restoreEnvironment(_ name: String, value: String?) {
+    if let value = value {
+      setenv(name, value, 1)
+    } else {
+      unsetenv(name)
+    }
+  }
+}

Tests/TartTests/Util/RegistryRunner.swift

@@ -13,7 +13,7 @@ class RegistryRunner {
     let stdoutPipe = Pipe()
 
     let proc = Process()
-    proc.executableURL = URL(fileURLWithPath: "/usr/local/bin/docker")
+    proc.executableURL = URL(fileURLWithPath: "/opt/homebrew/bin/docker")
     proc.arguments = arguments
     proc.standardOutput = stdoutPipe
     try proc.run()
@@ -31,7 +31,7 @@ class RegistryRunner {
 
   init() async throws {
     // Start container
-    let container = try Self.dockerCmd("run", "-d", "--rm", "-p", "127.0.0.1:0:5000", "registry:2")
+    let container = try Self.dockerCmd("run", "-d", "--rm", "-p", "127.0.0.1::5000", "registry:2")
       .trimmingCharacters(in: CharacterSet.newlines)
     containerID = container
 

Tests/TartTests/VMConfigTests.swift

@@ -0,0 +1,18 @@
+import XCTest
+@testable import tart
+
+final class VMConfigTests: XCTestCase {
+  func testVMDisplayConfig() throws {
+    // Defaults units (points)
+    var vmDisplayConfig = VMDisplayConfig.init(argument: "1234x5678")
+    XCTAssertEqual(VMDisplayConfig(width: 1234, height: 5678, unit: nil), vmDisplayConfig)
+
+    // Explicit units (points)
+    vmDisplayConfig = VMDisplayConfig.init(argument: "1234x5678pt")
+    XCTAssertEqual(VMDisplayConfig(width: 1234, height: 5678, unit: .point), vmDisplayConfig)
+
+    // Explicit units (pixels)
+    vmDisplayConfig = VMDisplayConfig.init(argument: "1234x5678px")
+    XCTAssertEqual(VMDisplayConfig(width: 1234, height: 5678, unit: .pixel), vmDisplayConfig)
+  }
+}

Tests/TartTests/VMDirectoryDiskImageStackTests.swift

@@ -0,0 +1,359 @@
+import Foundation
+import XCTest
+@testable import tart
+
+#if canImport(DiskImageKit)
+  import DiskImageKit
+
+  @available(macOS 27.0, *)
+  final class VMDirectoryDiskImageStackTests: XCTestCase {
+    override func setUpWithError() throws {
+      try super.setUpWithError()
+
+      if #unavailable(macOS 27.0) {
+        throw XCTSkip("DiskImageKit tests require macOS 27 or newer")
+      }
+    }
+
+    func testBaseBlockLayoutReadsRawAndASIFImages() throws {
+      let directory = try temporaryDirectory()
+      let rawURL = directory.appendingPathComponent("base.raw")
+      let asifURL = directory.appendingPathComponent("base.asif")
+      _ = try DiskImage(creating: .raw(url: rawURL, blockCount: 8))
+      _ = try DiskImage(creating: .asif(url: asifURL, blockCount: 16, blockSize: .bytes512))
+
+      XCTAssertEqual(try DiskImageStack.baseBlockLayout(at: rawURL, expectedFormat: .raw).blockCount, 8)
+      XCTAssertEqual(try DiskImageStack.baseBlockLayout(at: asifURL, expectedFormat: .asif).blockCount, 16)
+    }
+
+    func testCloneAsStackedBasePinsFlatManifestAndCreatesOverlay() throws {
+      let contentStore = try temporaryContentStore()
+      let source = try flatSource()
+      let destination = try temporaryVMDirectory()
+
+      try source.cloneAsStackedBase(to: destination, generateMAC: false, contentStore: contentStore)
+
+      XCTAssertTrue(destination.isStackedVM)
+      XCTAssertFalse(FileManager.default.fileExists(atPath: destination.diskURL.path))
+
+      let contentDigest = try Digest.hash(source.diskURL)
+      let manifest = try OCIManifest(fromJSON: Data(contentsOf: destination.manifestURL))
+      guard case .flat(let base) = try manifest.tartDiskRepresentation() else {
+        return XCTFail("expected a pinned base-only manifest")
+      }
+      XCTAssertEqual(base.contentDigest, contentDigest)
+      XCTAssertEqual(manifest.diskBlockSize(), 512)
+      XCTAssertEqual(manifest.diskBlockCount(), 8)
+
+      let stack = try destination.diskImageStack(contentStore: contentStore)
+      XCTAssertEqual(stack.baseURL, try contentStore.contentURL(for: contentDigest))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: destination.overlayURL.path))
+    }
+
+    func testCloneAsStackedBaseSupportsASIFDisk() throws {
+      let contentStore = try temporaryContentStore()
+      let source = try flatSource(diskFormat: .asif)
+      let destination = try temporaryVMDirectory()
+
+      try source.cloneAsStackedBase(to: destination, generateMAC: false, contentStore: contentStore)
+
+      let stack = try destination.diskImageStack(contentStore: contentStore)
+      XCTAssertEqual(stack.baseFormat, .asif)
+      XCTAssertTrue(destination.isStackedVM)
+      _ = try stack.makeAttachment()
+    }
+
+    func testStackedCloneCanCopyOrCreateWritableOverlay() throws {
+      let contentStore = try temporaryContentStore()
+      let source = try flatSource()
+      let stacked = try temporaryVMDirectory()
+      try source.cloneAsStackedBase(to: stacked, generateMAC: false, contentStore: contentStore)
+
+      let copied = try temporaryVMDirectory()
+      try stacked.cloneStacked(to: copied, copyWritableOverlay: true, generateMAC: false, contentStore: contentStore)
+      XCTAssertEqual(try Digest.hash(copied.overlayURL), try Digest.hash(stacked.overlayURL))
+
+      let fresh = try temporaryVMDirectory()
+      try stacked.cloneStacked(to: fresh, copyWritableOverlay: false, generateMAC: false, contentStore: contentStore)
+      XCTAssertTrue(fresh.isStackedVM)
+      XCTAssertTrue(FileManager.default.fileExists(atPath: fresh.overlayURL.path))
+    }
+
+    func testStackedRemoteAdditionalDiskRetainsTemporaryVM() throws {
+      try withTemporaryTartHome {
+        let source = try flatSource()
+        let stacked = try temporaryVMDirectory()
+        try source.cloneAsStackedBase(to: stacked, generateMAC: false)
+
+        let storage = try VMStorageOCI()
+        let name = try RemoteName("example.com/org/image:latest")
+        let cachedImage = try storage.create(name)
+        try FileManager.default.copyItem(at: stacked.configURL, to: cachedImage.configURL)
+        try FileManager.default.copyItem(at: stacked.nvramURL, to: cachedImage.nvramURL)
+        try FileManager.default.copyItem(at: stacked.manifestURL, to: cachedImage.manifestURL)
+
+        do {
+          let additionalDisk = try AdditionalDisk(parseFrom: name.description)
+          let entries = try temporaryEntries()
+          XCTAssertEqual(entries.count, 1)
+          XCTAssertTrue(VMDirectory(baseURL: entries[0]).isStackedVM)
+
+          try Config().gc()
+          XCTAssertEqual(try temporaryEntries(), entries)
+
+          withExtendedLifetime(additionalDisk) {}
+        }
+
+        try Config().gc()
+        XCTAssertTrue(try temporaryEntries().isEmpty)
+      }
+    }
+
+    func testResizeDiskGrowsWritableOverlayAndPreservesParentGeometry() throws {
+      let contentStore = try temporaryContentStore()
+      let source = try flatSource()
+      let stacked = try temporaryVMDirectory()
+      try source.cloneAsStackedBase(to: stacked, generateMAC: false, contentStore: contentStore)
+
+      try stacked.resizeDisk(1, contentStore: contentStore)
+
+      let image = try DiskImage(opening: .open(url: stacked.overlayURL, mode: .readOnly))
+      XCTAssertEqual(image.blockCount, 1_000_000_000 / 512)
+      XCTAssertEqual(try stacked.diskSizeBytes(), 1_000_000_000)
+
+      let manifest = try OCIManifest(fromJSON: Data(contentsOf: stacked.manifestURL))
+      XCTAssertEqual(manifest.diskBlockSize(), 512)
+      XCTAssertEqual(manifest.diskBlockCount(), 8)
+
+      _ = try stacked.diskImageStack(contentStore: contentStore).makeAttachment()
+    }
+
+    func testStackedArchiveRoundTripsImmutableContentAndOverlay() throws {
+      try withTemporaryTartHome {
+        let source = try flatSource()
+        let stacked = try temporaryVMDirectory()
+        try source.cloneAsStackedBase(to: stacked, generateMAC: false)
+
+        let contentDigest = try Digest.hash(source.diskURL)
+        let contentStore = try ContentStore()
+        let archivedOverlayDigest = try Digest.hash(stacked.overlayURL)
+        let archiveURL = try temporaryDirectory().appendingPathComponent("stacked.tvm")
+        try stacked.exportToArchive(path: archiveURL.path)
+
+        let cachedBaseURL = try XCTUnwrap(try contentStore.existingContentURL(for: contentDigest))
+        // Import must repair a corrupt cache entry from the valid archive
+        // instead of discarding the archive copy as an apparent cache hit.
+        try Data("corrupt".utf8).write(to: cachedBaseURL)
+        XCTAssertNil(try contentStore.existingContentURL(for: contentDigest))
+
+        let imported = try temporaryVMDirectory()
+        try imported.importFromArchive(path: archiveURL.path)
+
+        XCTAssertTrue(imported.isStackedVM)
+        XCTAssertEqual(try Digest.hash(imported.overlayURL), archivedOverlayDigest)
+        XCTAssertNotNil(try contentStore.existingContentURL(for: contentDigest))
+        _ = try imported.diskImageStack().makeAttachment()
+      }
+    }
+
+    func testStackedArchiveRejectsCorruptImmutableContent() throws {
+      try withTemporaryTartHome {
+        let source = try flatSource()
+        let stacked = try temporaryVMDirectory()
+        try source.cloneAsStackedBase(to: stacked, generateMAC: false)
+
+        let contentDigest = try Digest.hash(source.diskURL)
+        let contentStore = try ContentStore()
+        let cachedBaseURL = try XCTUnwrap(try contentStore.contentURLIfPresent(for: contentDigest))
+        try Data("corrupt".utf8).write(to: cachedBaseURL)
+
+        let archiveURL = try temporaryDirectory().appendingPathComponent("stacked.tvm")
+        XCTAssertThrowsError(try stacked.exportToArchive(path: archiveURL.path)) { error in
+          guard case RuntimeError.ExportFailed(let message) = error else {
+            return XCTFail("unexpected error: \(error)")
+          }
+          XCTAssertEqual(message, "VM is missing cached disk content \(contentDigest)")
+        }
+      }
+    }
+
+    func testStackedOCIArchiveSurvivesConcurrentRecordDeletion() throws {
+      try withTemporaryTartHome {
+        let source = try flatSource()
+        let stacked = try temporaryVMDirectory()
+        try source.cloneAsStackedBase(to: stacked, generateMAC: false)
+
+        let manifest = try OCIManifest(fromJSON: Data(contentsOf: stacked.manifestURL))
+        let storage = try VMStorageOCI()
+        let record = try storage.create(RemoteName(
+          host: "example.com",
+          namespace: "org/image",
+          reference: Reference(digest: try manifest.digest())
+        ))
+        try FileManager.default.copyItem(at: stacked.configURL, to: record.configURL)
+        try FileManager.default.copyItem(at: stacked.nvramURL, to: record.nvramURL)
+        try FileManager.default.copyItem(at: stacked.manifestURL, to: record.manifestURL)
+        XCTAssertTrue(record.isStackedCachedImage)
+
+        let archiveURL = try temporaryDirectory().appendingPathComponent("stacked-race.tvm")
+        let contentStore = try ContentStore()
+        let lockHeld = DispatchSemaphore(value: 0)
+        let releaseLock = DispatchSemaphore(value: 0)
+        let exportStarted = DispatchSemaphore(value: 0)
+        let exportFinished = DispatchSemaphore(value: 0)
+        let deletionStarted = DispatchSemaphore(value: 0)
+        let deletionFinished = DispatchSemaphore(value: 0)
+
+        DispatchQueue.global().async {
+          try? contentStore.withPruneLock {
+            lockHeld.signal()
+            releaseLock.wait()
+          }
+        }
+        XCTAssertEqual(lockHeld.wait(timeout: .now() + 1), .success)
+
+        // Queue export first so it is the next prune-lock waiter, then queue
+        // deletion behind it. Export must finish staging everything it needs
+        // before deletion can remove the source cached image.
+        DispatchQueue.global().async {
+          exportStarted.signal()
+          try? record.exportToArchive(path: archiveURL.path)
+          exportFinished.signal()
+        }
+        XCTAssertEqual(exportStarted.wait(timeout: .now() + 1), .success)
+        Thread.sleep(forTimeInterval: 0.1)
+
+        DispatchQueue.global().async {
+          deletionStarted.signal()
+          try? record.delete()
+          deletionFinished.signal()
+        }
+        XCTAssertEqual(deletionStarted.wait(timeout: .now() + 1), .success)
+        XCTAssertEqual(exportFinished.wait(timeout: .now() + 0.1), .timedOut)
+        XCTAssertEqual(deletionFinished.wait(timeout: .now() + 0.1), .timedOut)
+
+        releaseLock.signal()
+        XCTAssertEqual(exportFinished.wait(timeout: .now() + 5), .success)
+        XCTAssertEqual(deletionFinished.wait(timeout: .now() + 5), .success)
+        XCTAssertFalse(FileManager.default.fileExists(atPath: record.baseURL.path))
+
+        let imported = try temporaryVMDirectory()
+        try imported.importFromArchive(path: archiveURL.path)
+        XCTAssertTrue(imported.isStackedVM)
+        _ = try imported.diskImageStack().makeAttachment()
+      }
+    }
+
+    func testResolvesPublishedOverlayFromManifestAndCache() throws {
+      let contentStore = try temporaryContentStore()
+      let source = try flatSource()
+      let baseOnly = try temporaryVMDirectory()
+      try source.cloneAsStackedBase(to: baseOnly, generateMAC: false, contentStore: contentStore)
+
+      let contentDigest = try Digest.hash(baseOnly.overlayURL)
+      let temporaryContentURL = try contentStore.temporaryContentURL(for: contentDigest)
+      try FileManager.default.copyItem(at: baseOnly.overlayURL, to: temporaryContentURL)
+      _ = try contentStore.install(temporaryContentURL, contentDigest: contentDigest)
+
+      var manifest = try OCIManifest(fromJSON: Data(contentsOf: baseOnly.manifestURL))
+      var overlay = OCIManifestLayer(
+        mediaType: asifOverlayMediaType,
+        size: 1,
+        digest: "sha256:overlay-transport",
+        uncompressedSize: 1,
+        uncompressedContentDigest: "sha256:overlay-chunk"
+      )
+      overlay.annotations?[diskFileContentDigestAnnotation] = contentDigest
+      overlay.annotations?[diskFileChunkCountAnnotation] = "1"
+      manifest.layers.insert(overlay, at: manifest.layers.count - 1)
+
+      let destination = try temporaryVMDirectory()
+      try FileManager.default.copyItem(at: baseOnly.configURL, to: destination.configURL)
+      try FileManager.default.copyItem(at: baseOnly.nvramURL, to: destination.nvramURL)
+      try manifest.toJSON().write(to: destination.manifestURL)
+
+      let stack = try destination.diskImageStack(contentStore: contentStore)
+      XCTAssertEqual(stack.immutableOverlayURLs, [try contentStore.contentURL(for: contentDigest)])
+      try stack.createWritableOverlay()
+      _ = try stack.makeAttachment()
+    }
+
+    private func flatSource(diskFormat: DiskImageFormat = .raw) throws -> VMDirectory {
+      let vmDir = try temporaryVMDirectory()
+      let config = VMConfig(
+        platform: Linux(),
+        cpuCountMin: 2,
+        memorySizeMin: 512 * 1024 * 1024,
+        diskFormat: diskFormat
+      )
+      try config.save(toURL: vmDir.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.nvramURL.path, contents: Data()))
+      switch diskFormat {
+      case .raw:
+        _ = try DiskImage(creating: .raw(url: vmDir.diskURL, blockCount: 8))
+      case .asif:
+        _ = try DiskImage(creating: .asif(url: vmDir.diskURL, blockCount: 8, blockSize: .bytes512))
+      }
+
+      let diskChunk = OCIManifestLayer(
+        mediaType: diskV2MediaType,
+        size: 1,
+        digest: "sha256:transport",
+        uncompressedSize: 4096,
+        uncompressedContentDigest: "sha256:chunk"
+      )
+      let manifest = OCIManifest(
+        config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+        layers: [
+          OCIManifestLayer(mediaType: configMediaType, size: 1, digest: "sha256:config"),
+          diskChunk,
+          OCIManifestLayer(mediaType: nvramMediaType, size: 1, digest: "sha256:nvram"),
+        ]
+      )
+      try manifest.toJSON().write(to: vmDir.manifestURL)
+
+      return vmDir
+    }
+
+    private func temporaryContentStore() throws -> ContentStore {
+      let url = try temporaryDirectory()
+      return try ContentStore(baseURL: url)
+    }
+
+    private func temporaryEntries() throws -> [URL] {
+      try FileManager.default.contentsOfDirectory(
+        at: Config().tartTmpDir,
+        includingPropertiesForKeys: nil
+      )
+    }
+
+    private func withTemporaryTartHome(_ body: () throws -> Void) throws {
+      let home = try temporaryDirectory()
+      let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+      setenv("TART_HOME", home.path, 1)
+      defer {
+        if let previousHome {
+          setenv("TART_HOME", previousHome, 1)
+        } else {
+          unsetenv("TART_HOME")
+        }
+      }
+
+      try body()
+    }
+
+    private func temporaryVMDirectory() throws -> VMDirectory {
+      VMDirectory(baseURL: try temporaryDirectory())
+    }
+
+    private func temporaryDirectory() throws -> URL {
+      let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+      try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false)
+      addTeardownBlock {
+        try? FileManager.default.removeItem(at: url)
+      }
+
+      return url
+    }
+  }
+#endif

Tests/TartTests/VMDirectoryLayoutTests.swift

@@ -0,0 +1,154 @@
+import Foundation
+import XCTest
+@testable import tart
+
+final class VMDirectoryLayoutTests: XCTestCase {
+  func testStandaloneLayoutWithPinnedManifest() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try touch(vmDir.configURL)
+    try touch(vmDir.nvramURL)
+    try touch(vmDir.diskURL)
+    try touch(vmDir.manifestURL)
+
+    XCTAssertEqual(vmDir.layout, .standalone)
+    XCTAssertTrue(vmDir.initialized)
+    XCTAssertTrue(vmDir.isCachedImage)
+    XCTAssertNoThrow(try vmDir.validateCachedImage(userFriendlyName: "standalone"))
+  }
+
+  func testStackedVMLayout() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try touch(vmDir.configURL)
+    try touch(vmDir.nvramURL)
+    try touch(vmDir.manifestURL)
+    try touch(vmDir.overlayURL)
+
+    XCTAssertEqual(vmDir.layout, .stackedLocal)
+    XCTAssertTrue(vmDir.initialized)
+    XCTAssertFalse(vmDir.isCachedImage)
+  }
+
+  func testStackedCachedImageLayout() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try touch(vmDir.configURL)
+    try touch(vmDir.nvramURL)
+    try touch(vmDir.manifestURL)
+
+    XCTAssertEqual(vmDir.layout, .stackedOCIRecord)
+    XCTAssertFalse(vmDir.initialized)
+    XCTAssertTrue(vmDir.isCachedImage)
+    XCTAssertNoThrow(try vmDir.validateCachedImage(userFriendlyName: "stacked"))
+  }
+
+  func testAmbiguousDiskAndOverlayIsNotInitialized() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try touch(vmDir.configURL)
+    try touch(vmDir.nvramURL)
+    try touch(vmDir.diskURL)
+    try touch(vmDir.manifestURL)
+    try touch(vmDir.overlayURL)
+
+    XCTAssertNil(vmDir.layout)
+    XCTAssertFalse(vmDir.initialized)
+    XCTAssertFalse(vmDir.isCachedImage)
+  }
+
+  func testStackedVMAccountingUsesOverlay() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try Data("config".utf8).write(to: vmDir.configURL)
+    try Data("nvram".utf8).write(to: vmDir.nvramURL)
+    try Data("overlay".utf8).write(to: vmDir.overlayURL)
+    try stackedManifest(blockSize: 512, blockCount: 8).toJSON().write(to: vmDir.manifestURL)
+
+    XCTAssertEqual(
+      try vmDir.sizeBytes(),
+      try vmDir.configURL.sizeBytes() + vmDir.overlayURL.sizeBytes() + vmDir.nvramURL.sizeBytes()
+    )
+    XCTAssertEqual(
+      try vmDir.allocatedSizeBytes(),
+      try vmDir.configURL.allocatedSizeBytes() + vmDir.overlayURL.allocatedSizeBytes() + vmDir.nvramURL.allocatedSizeBytes()
+    )
+  }
+
+  func testStackedCachedImageAccountingUsesManifestBlockLayout() throws {
+    let vmDir = try temporaryVMDirectory()
+
+    try Data("config".utf8).write(to: vmDir.configURL)
+    try Data("nvram".utf8).write(to: vmDir.nvramURL)
+    try stackedManifest(blockSize: 512, blockCount: 8).toJSON().write(to: vmDir.manifestURL)
+
+    XCTAssertEqual(
+      try vmDir.sizeBytes(),
+      try vmDir.configURL.sizeBytes() + vmDir.nvramURL.sizeBytes()
+    )
+    XCTAssertEqual(
+      try vmDir.allocatedSizeBytes(),
+      try vmDir.configURL.allocatedSizeBytes() + vmDir.nvramURL.allocatedSizeBytes()
+    )
+    XCTAssertEqual(try vmDir.diskSizeBytes(), 4096)
+  }
+
+  func testStackedArchiveRequiresMacOS27() throws {
+    if #available(macOS 27.0, *) {
+      throw XCTSkip("macOS 26 compatibility test")
+    }
+
+    let vmDir = try temporaryVMDirectory()
+    try Data("config".utf8).write(to: vmDir.configURL)
+    try Data("nvram".utf8).write(to: vmDir.nvramURL)
+    try Data("overlay".utf8).write(to: vmDir.overlayURL)
+    try stackedManifest(blockSize: 512, blockCount: 8).toJSON().write(to: vmDir.manifestURL)
+    let archiveURL = try temporaryVMDirectory().baseURL.appendingPathComponent("stacked.tvm")
+    XCTAssertThrowsError(try vmDir.exportToArchive(path: archiveURL.path)) { error in
+      guard case DiskImageStackError.unavailable = error else {
+        return XCTFail("unexpected error: \(error)")
+      }
+    }
+    XCTAssertFalse(FileManager.default.fileExists(atPath: archiveURL.path))
+  }
+
+  private func temporaryVMDirectory() throws -> VMDirectory {
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: url)
+    }
+
+    return VMDirectory(baseURL: url)
+  }
+
+  private func touch(_ url: URL) throws {
+    XCTAssertTrue(FileManager.default.createFile(atPath: url.path, contents: Data()))
+  }
+
+  private func stackedManifest(blockSize: UInt64, blockCount: UInt64) -> OCIManifest {
+    var disk = OCIManifestLayer(
+      mediaType: diskV2MediaType,
+      size: 1,
+      digest: "sha256:transport",
+      uncompressedSize: blockSize * blockCount,
+      uncompressedContentDigest: "sha256:chunk"
+    )
+    disk.annotations?[diskFileContentDigestAnnotation] = "sha256:base"
+
+    var manifest = OCIManifest(
+      config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+      layers: [
+        OCIManifestLayer(mediaType: configMediaType, size: 1, digest: "sha256:config"),
+        disk,
+        OCIManifestLayer(mediaType: nvramMediaType, size: 1, digest: "sha256:nvram"),
+      ]
+    )
+    manifest.annotations = [
+      uncompressedDiskSizeAnnotation: String(blockSize * blockCount),
+      diskBlockSizeAnnotation: String(blockSize),
+    ]
+
+    return manifest
+  }
+}

Tests/TartTests/VMStorageOCITests.swift

@@ -0,0 +1,974 @@
+import Foundation
+import XCTest
+@testable import tart
+
+#if canImport(DiskImageKit)
+  import DiskImageKit
+#endif
+
+final class VMStorageOCITests: XCTestCase {
+  func testPopulateStandalonePushedImageCachesDiskAndManifest() throws {
+    try withTemporaryTartHome {
+      let source = try standaloneSource(diskData: Data("disk".utf8))
+      let manifest = try flatManifest()
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+
+      try storage.populate(name, from: source, manifest: manifest)
+
+      let cached = try storage.open(name)
+      XCTAssertTrue(cached.isStandalone)
+      XCTAssertEqual(try Data(contentsOf: cached.diskURL), Data("disk".utf8))
+      XCTAssertEqual(try OCIManifest(fromJSON: Data(contentsOf: cached.manifestURL)), manifest)
+    }
+  }
+
+  func testStackedCloneRequiresManifestForLegacyStandaloneCachedImage() throws {
+    try withTemporaryTartHome {
+      let manifest = try flatManifest()
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+      let record = try storage.create(name)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.diskURL.path, contents: Data()))
+
+      XCTAssertTrue(try storage.hasUsableCachedImageForClone(name))
+      XCTAssertFalse(try storage.hasUsableCachedImageForClone(name, requireManifest: true))
+      XCTAssertTrue(try storage.hasCompleteCachedImage(name, manifest: manifest))
+      XCTAssertFalse(try storage.hasCompleteCachedImage(name, manifest: manifest, requireManifest: true))
+    }
+  }
+
+  func testCloneCacheCheckRejectsMissingOrWrongSizedStackedContent() throws {
+    try withTemporaryTartHome {
+      let baseData = Data("base".utf8)
+      let overlayData = Data("overlay".utf8)
+      let baseDigest = Digest.hash(baseData)
+      let overlayDigest = Digest.hash(overlayData)
+      let manifest = try stackedManifest(
+        baseContentDigest: baseDigest,
+        overlayContentDigest: overlayDigest,
+        baseUncompressedSize: UInt64(baseData.count),
+        overlayUncompressedSize: UInt64(overlayData.count)
+      )
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+      let record = try storage.create(name)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: record.manifestURL)
+
+      XCTAssertFalse(try storage.hasUsableCachedImageForClone(name))
+
+      let contentStore = try ContentStore()
+      try installContent(baseData, contentDigest: baseDigest, into: contentStore)
+      try installContent(overlayData, contentDigest: overlayDigest, into: contentStore)
+      XCTAssertTrue(try storage.hasUsableCachedImageForClone(name))
+
+      try Data("bad".utf8).write(to: try contentStore.contentURL(for: overlayDigest))
+      XCTAssertFalse(try storage.hasUsableCachedImageForClone(name))
+    }
+  }
+
+  func testListIncludesStackedCachedImage() throws {
+    try withTemporaryTartHome {
+      let manifest = try stackedManifest()
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+      let record = try storage.create(name)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: record.manifestURL)
+
+      XCTAssertTrue(try storage.list().contains { $0.0 == name.description })
+      XCTAssertEqual(try record.diskSizeBytes(), 4096)
+      XCTAssertNoThrow(try record.allocatedSizeBytes())
+    }
+  }
+
+  func testStackedCacheHitRequiresExpectedContentSizes() throws {
+    try withTemporaryTartHome {
+      let baseData = Data(repeating: 0x41, count: 10)
+      let overlayData = Data(repeating: 0x42, count: 20)
+      let baseDigest = Digest.hash(baseData)
+      let overlayDigest = Digest.hash(overlayData)
+      let manifest = try stackedManifest(
+        baseContentDigest: baseDigest,
+        overlayContentDigest: overlayDigest,
+        baseUncompressedSize: 10,
+        overlayUncompressedSize: 20
+      )
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+      let record = try storage.create(name)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: record.manifestURL)
+
+      XCTAssertFalse(try storage.hasCompleteCachedImage(name, manifest: manifest))
+      XCTAssertEqual(try storage.requiredDiskStorageBytes(for: manifest), 30)
+
+      let contentStore = try ContentStore()
+      try installContent(baseData, contentDigest: baseDigest, into: contentStore)
+      XCTAssertFalse(try storage.hasCompleteCachedImage(name, manifest: manifest))
+      XCTAssertEqual(try storage.requiredDiskStorageBytes(for: manifest), 20)
+
+      try installContent(overlayData, contentDigest: overlayDigest, into: contentStore)
+      XCTAssertTrue(try storage.hasCompleteCachedImage(name, manifest: manifest))
+      XCTAssertEqual(try storage.requiredDiskStorageBytes(for: manifest), 0)
+
+      let overlayURL = try contentStore.contentURL(for: overlayDigest)
+      try Data("corrupt".utf8).write(to: overlayURL)
+      XCTAssertFalse(try storage.hasCompleteCachedImage(name, manifest: manifest))
+      XCTAssertEqual(try storage.requiredDiskStorageBytes(for: manifest), 20)
+    }
+  }
+
+  func testStackedPullReusesPreviouslyPulledStandaloneDisk() throws {
+    try withTemporaryTartHome {
+      let diskData = Data([0])
+      let contentDigest = Digest.hash(diskData)
+      let flatManifest = try flatManifest()
+      let flatName = try digestName(for: flatManifest)
+      let storage = try VMStorageOCI()
+      let flatRecord = try storage.create(flatName)
+      try config().save(toURL: flatRecord.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: flatRecord.nvramURL.path, contents: Data()))
+      try diskData.write(to: flatRecord.diskURL)
+      try flatManifest.toJSON().write(to: flatRecord.manifestURL)
+
+      let stackedManifest = try stackedManifest(baseContentDigest: contentDigest)
+      XCTAssertNil(try ContentStore().existingContentURL(for: contentDigest))
+
+      try storage.reuseStandaloneDiskForStackedBaseIfPossible(stackedManifest)
+
+      let reusedURL = try XCTUnwrap(try ContentStore().existingContentURL(for: contentDigest))
+      XCTAssertEqual(try Data(contentsOf: reusedURL), diskData)
+    }
+  }
+
+  func testStackedPullDoesNotRehashInstalledBaseBeforeReuse() throws {
+    try withTemporaryTartHome {
+      let contentDigest = Digest.hash(Data("base".utf8))
+      let manifest = try stackedManifest(baseContentDigest: contentDigest)
+      let contentURL = try ContentStore().contentURL(for: contentDigest)
+
+      // Hashing this path would throw. Once an entry is published, this
+      // fast path must trust its presence and let normal pull validation
+      // repair unusable content later.
+      try FileManager.default.createDirectory(at: contentURL, withIntermediateDirectories: false)
+
+      XCTAssertNoThrow(try VMStorageOCI().reuseStandaloneDiskForStackedBaseIfPossible(manifest))
+    }
+  }
+
+  func testNewTagDoesNotValidateCachedStackBeforeLock() throws {
+    try withTemporaryTartHome {
+      let baseDigest = Digest.hash(Data("base".utf8))
+      let overlayDigest = Digest.hash(Data("overlay".utf8))
+      let manifest = try stackedManifest(
+        baseContentDigest: baseDigest,
+        overlayContentDigest: overlayDigest
+      )
+      let digestName = try digestName(for: manifest)
+      let tagName = RemoteName(
+        host: digestName.host,
+        namespace: digestName.namespace,
+        reference: Reference(tag: "latest")
+      )
+      let storage = try VMStorageOCI()
+      let record = try storage.create(digestName)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: record.manifestURL)
+
+      // Hashing this directory as a disk file throws. A new tag must skip
+      // validation until after it has taken the host lock.
+      let contentURL = try ContentStore().contentURL(for: baseDigest)
+      try FileManager.default.createDirectory(at: contentURL, withIntermediateDirectories: false)
+      XCTAssertFalse(try storage.hasCompleteLinkedImage(tagName, digestName: digestName, manifest: manifest))
+    }
+  }
+
+  func testStandaloneLayerCacheIgnoresStackedCachedImages() async throws {
+    try await withTemporaryTartHome {
+      var targetManifest = try flatManifest()
+      var stackedCandidateManifest = try stackedManifest()
+      let sharedDiskSize = 2 * 1024 * 1024 * 1024
+      targetManifest.layers[1].size = sharedDiskSize
+      stackedCandidateManifest.layers[1] = targetManifest.layers[1]
+
+      let candidateName = try digestName(for: stackedCandidateManifest)
+      let storage = try VMStorageOCI()
+      let candidate = try storage.create(candidateName)
+      try config().save(toURL: candidate.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: candidate.nvramURL.path, contents: Data()))
+      try stackedCandidateManifest.toJSON().write(to: candidate.manifestURL)
+
+      let targetName = RemoteName(
+        host: "example.com",
+        namespace: "org/target",
+        reference: Reference(digest: try targetManifest.digest())
+      )
+      let registry = try Registry(host: targetName.host, namespace: targetName.namespace)
+
+      let layerCache = try await storage.chooseLocalLayerCache(targetName, targetManifest, registry)
+      XCTAssertNil(layerCache)
+    }
+  }
+
+  func testGCPrunesOnlyUnreferencedContent() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let referenced = try installContent(Data("referenced".utf8), into: contentStore)
+      let unreferenced = try installContent(Data("unreferenced".utf8), into: contentStore)
+
+      let stacked = try VMStorageLocal().create("stacked")
+      try config().save(toURL: stacked.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: stacked.nvramURL.path, contents: Data()))
+      XCTAssertTrue(FileManager.default.createFile(atPath: stacked.overlayURL.path, contents: Data()))
+      try pinnedBaseManifest(contentDigest: referenced.digest).toJSON().write(to: stacked.manifestURL)
+
+      try VMStorageOCI().gc()
+
+      XCTAssertTrue(FileManager.default.fileExists(atPath: referenced.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: unreferenced.url.path))
+    }
+  }
+
+  func testGCPrunesContentWithoutOCIStorageDirectory() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let unreferenced = try installContent(Data("unreferenced".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: storage.baseURL.path))
+
+      try storage.gc()
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: unreferenced.url.path))
+    }
+  }
+
+  func testGCDoesNotPruneContentReferencedByInProgressManifest() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let referenced = try installContent(Data("in-progress".utf8), into: contentStore)
+      let temporaryVMDir = try VMDirectory.temporary()
+
+      // Pull and clone publish the manifest before config, NVRAM, or a
+      // writable overlay necessarily exist.
+      try pinnedBaseManifest(contentDigest: referenced.digest).toJSON().write(to: temporaryVMDir.manifestURL)
+
+      try VMStorageOCI().gc()
+
+      XCTAssertTrue(FileManager.default.fileExists(atPath: referenced.url.path))
+    }
+  }
+
+  func testStalePrunableDoesNotDeleteNewlyReferencedContent() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let content = try installContent(Data("new-reference".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+      let candidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.resolvingSymlinksInPath() == content.url.resolvingSymlinksInPath()
+      })
+
+      // Simulate a clone or pull publishing its manifest after prune built
+      // the candidate list but before deletion starts.
+      let temporaryVMDir = try VMDirectory.temporary()
+      try contentStore.withPruneLock {
+        try pinnedBaseManifest(contentDigest: content.digest).toJSON().write(to: temporaryVMDir.manifestURL)
+      }
+
+      try candidate.delete()
+
+      XCTAssertTrue(FileManager.default.fileExists(atPath: content.url.path))
+    }
+  }
+
+  func testVMDirectoryDeletionOfStackedOCIRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let record = try createRecord(for: stackedManifest(), in: storage)
+
+      try assertDeletionWaitsForPruneLock(record: record) {
+        try record.delete()
+      }
+    }
+  }
+
+  func testStorageDeletionOfStackedOCIRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let manifest = try stackedManifest()
+      let name = try digestName(for: manifest)
+      let record = try createRecord(for: manifest, in: storage)
+
+      try assertDeletionWaitsForPruneLock(record: record) {
+        try storage.delete(name)
+      }
+    }
+  }
+
+  func testStorageDeletionOfIncompleteManifestRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let name = RemoteName(
+        host: "example.com",
+        namespace: "org/image",
+        reference: Reference(digest: "sha256:incomplete")
+      )
+      let record = try storage.create(name)
+      try Data("{}".utf8).write(to: record.manifestURL)
+
+      try assertDeletionWaitsForPruneLock(record: record) {
+        try storage.delete(name)
+      }
+    }
+  }
+
+  func testVMDirectoryDeletionOfUnpublishedRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let record = try storage.create(RemoteName(
+        host: "example.com",
+        namespace: "org/image",
+        reference: Reference(digest: "sha256:unpublished")
+      ))
+
+      try assertDeletionWaitsForPruneLock(record: record) {
+        try record.removeFromDisk()
+      }
+    }
+  }
+
+  func testTagReplacementWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let firstManifest = try stackedManifest(baseContentDigest: "sha256:first")
+      let secondManifest = try stackedManifest(baseContentDigest: "sha256:second")
+      let firstName = try digestName(for: firstManifest)
+      let secondName = try digestName(for: secondManifest)
+      _ = try createRecord(for: firstManifest, in: storage)
+      _ = try createRecord(for: secondManifest, in: storage)
+      let tagName = RemoteName(
+        host: secondName.host,
+        namespace: secondName.namespace,
+        reference: Reference(tag: "latest")
+      )
+
+      let contentStore = try ContentStore()
+      let lockHeld = DispatchSemaphore(value: 0)
+      let releaseLock = DispatchSemaphore(value: 0)
+      let replacementStarted = DispatchSemaphore(value: 0)
+      let replacementFinished = DispatchSemaphore(value: 0)
+
+      DispatchQueue.global().async {
+        try? contentStore.withPruneLock {
+          lockHeld.signal()
+          releaseLock.wait()
+        }
+      }
+      XCTAssertEqual(lockHeld.wait(timeout: .now() + 1), .success)
+
+      DispatchQueue.global().async {
+        replacementStarted.signal()
+        try? storage.link(from: tagName, to: secondName)
+        replacementFinished.signal()
+      }
+      XCTAssertEqual(replacementStarted.wait(timeout: .now() + 1), .success)
+      XCTAssertEqual(replacementFinished.wait(timeout: .now() + 0.1), .timedOut)
+
+      releaseLock.signal()
+      XCTAssertEqual(replacementFinished.wait(timeout: .now() + 1), .success)
+      XCTAssertTrue(storage.linked(from: tagName, to: secondName))
+      XCTAssertFalse(storage.linked(from: tagName, to: firstName))
+    }
+  }
+
+  func testGCDeletionOfStackedOCIRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let record = try createRecord(for: stackedManifest(), in: storage)
+
+      try assertDeletionWaitsForPruneLock(record: record) {
+        try storage.gc()
+      }
+    }
+  }
+
+  func testTemporaryManifestGCWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let temporaryVMDir = try VMDirectory.temporary()
+      try stackedManifest().toJSON().write(to: temporaryVMDir.manifestURL)
+
+      try assertDeletionWaitsForPruneLock(record: temporaryVMDir) {
+        try Config().gc()
+      }
+    }
+  }
+
+  func testLockedTemporaryDirectorySurvivesGarbageCollection() throws {
+    try withTemporaryTartHome {
+      let temporaryVMDir = try VMDirectory.temporary()
+      let lock = try FileLock(lockURL: temporaryVMDir.baseURL)
+      try lock.lock()
+
+      try Config().gc()
+      XCTAssertTrue(FileManager.default.fileExists(atPath: temporaryVMDir.baseURL.path))
+
+      try lock.unlock()
+      try Config().gc()
+      XCTAssertFalse(FileManager.default.fileExists(atPath: temporaryVMDir.baseURL.path))
+    }
+  }
+
+  func testMovingStackedOCIRecordWaitsForPruneLock() throws {
+    try withTemporaryTartHome {
+      let storage = try VMStorageOCI()
+      let source = try temporaryVMDirectory()
+      let manifest = try stackedManifest()
+      let name = try digestName(for: manifest)
+      try config().save(toURL: source.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: source.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: source.manifestURL)
+
+      let contentStore = try ContentStore()
+      let lockHeld = DispatchSemaphore(value: 0)
+      let releaseLock = DispatchSemaphore(value: 0)
+      let moveStarted = DispatchSemaphore(value: 0)
+      let moveFinished = DispatchSemaphore(value: 0)
+
+      DispatchQueue.global().async {
+        try? contentStore.withPruneLock {
+          lockHeld.signal()
+          releaseLock.wait()
+        }
+      }
+      XCTAssertEqual(lockHeld.wait(timeout: .now() + 1), .success)
+
+      DispatchQueue.global().async {
+        moveStarted.signal()
+        try? storage.move(name, from: source)
+        moveFinished.signal()
+      }
+      XCTAssertEqual(moveStarted.wait(timeout: .now() + 1), .success)
+      XCTAssertEqual(moveFinished.wait(timeout: .now() + 0.1), .timedOut)
+      XCTAssertTrue(FileManager.default.fileExists(atPath: source.baseURL.path))
+
+      releaseLock.signal()
+      XCTAssertEqual(moveFinished.wait(timeout: .now() + 1), .success)
+      XCTAssertFalse(FileManager.default.fileExists(atPath: source.baseURL.path))
+      XCTAssertTrue(try storage.open(name).isStackedCachedImage)
+    }
+  }
+
+  func testPruningLastStackedOCIRecordReclaimsItsContent() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let baseContent = try installContent(Data("record-only-base".utf8), into: contentStore)
+      let overlayContent = try installContent(Data("record-only-overlay".utf8), into: contentStore)
+      let manifest = try stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: overlayContent.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try overlayContent.url.sizeBytes())
+      )
+      let name = try digestName(for: manifest)
+      let storage = try VMStorageOCI()
+      let record = try storage.create(name)
+      try config().save(toURL: record.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+      try manifest.toJSON().write(to: record.manifestURL)
+
+      let candidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.lastPathComponent == record.url.lastPathComponent
+      })
+      XCTAssertGreaterThanOrEqual(
+        try candidate.allocatedSizeBytes(),
+        try baseContent.url.allocatedSizeBytes() + overlayContent.url.allocatedSizeBytes()
+      )
+
+      // The record itself fits in this budget, so pruning only succeeds if it
+      // accounts for the immutable content released with the final reference.
+      try Prune.pruneSpaceBudget(
+        prunableStorages: [storage],
+        spaceBudgetBytes: UInt64(try record.allocatedSizeBytes())
+      )
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: record.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: baseContent.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: overlayContent.url.path))
+    }
+  }
+
+  func testMalformedStackedOCIRecordDoesNotBlockPruning() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let baseContent = try installContent(Data("valid-base".utf8), into: contentStore)
+      let overlayContent = try installContent(Data("valid-overlay".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+      let validRecord = try createRecord(for: stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: overlayContent.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try overlayContent.url.sizeBytes())
+      ), in: storage)
+
+      let malformedRecord = try storage.create(RemoteName(
+        host: "example.com",
+        namespace: "org/image",
+        reference: Reference(digest: "sha256:malformed")
+      ))
+      try config().save(toURL: malformedRecord.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: malformedRecord.nvramURL.path, contents: Data()))
+      try Data("{".utf8).write(to: malformedRecord.manifestURL)
+
+      XCTAssertNoThrow(try storage.prunables())
+      try Prune.pruneSpaceBudget(prunableStorages: [storage], spaceBudgetBytes: 0)
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: validRecord.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: malformedRecord.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: baseContent.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: overlayContent.url.path))
+    }
+  }
+
+  func testPruningOneStackedOCIRecordPreservesSharedContent() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let baseContent = try installContent(Data("shared-base".utf8), into: contentStore)
+      let firstOverlay = try installContent(Data("first-overlay".utf8), into: contentStore)
+      let secondOverlay = try installContent(Data("second-overlay".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+
+      let firstManifest = try stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: firstOverlay.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try firstOverlay.url.sizeBytes())
+      )
+      let secondManifest = try stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: secondOverlay.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try secondOverlay.url.sizeBytes())
+      )
+      let firstRecord = try createRecord(for: firstManifest, in: storage)
+      let secondRecord = try createRecord(for: secondManifest, in: storage)
+
+      let firstCandidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.lastPathComponent == firstRecord.url.lastPathComponent
+      })
+      try firstCandidate.delete()
+
+      XCTAssertTrue(FileManager.default.fileExists(atPath: baseContent.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: firstOverlay.url.path))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: secondOverlay.url.path))
+
+      let secondCandidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.lastPathComponent == secondRecord.url.lastPathComponent
+      })
+      try secondCandidate.delete()
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: baseContent.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: secondOverlay.url.path))
+    }
+  }
+
+  func testSpaceBudgetRecomputesSharedContentAfterOwnerDeletion() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let baseContent = try installContent(Data("shared-base".utf8), into: contentStore)
+      let firstOverlay = try installContent(Data("first-overlay".utf8), into: contentStore)
+      let secondOverlay = try installContent(Data("second-overlay".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+
+      let firstManifest = try stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: firstOverlay.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try firstOverlay.url.sizeBytes())
+      )
+      let secondManifest = try stackedManifest(
+        baseContentDigest: baseContent.digest,
+        overlayContentDigest: secondOverlay.digest,
+        baseUncompressedSize: UInt64(try baseContent.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try secondOverlay.url.sizeBytes())
+      )
+      let olderRecord = try createRecord(for: firstManifest, in: storage)
+      let newerRecord = try createRecord(for: secondManifest, in: storage)
+      try olderRecord.url.updateAccessDate(Date(timeIntervalSince1970: 1))
+      try newerRecord.url.updateAccessDate(Date(timeIntervalSince1970: 2))
+
+      let olderCandidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.lastPathComponent == olderRecord.url.lastPathComponent
+      })
+      let budget = UInt64(try olderCandidate.allocatedSizeBytes())
+
+      // On the first pass the newer record owns the shared base and is
+      // selected for deletion, while the older record fits this budget.
+      // Recomputing must then charge the surviving record for the base and
+      // prune it too.
+      try Prune.pruneSpaceBudget(
+        prunableStorages: [storage],
+        spaceBudgetBytes: budget
+      )
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: olderRecord.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: newerRecord.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: baseContent.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: firstOverlay.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: secondOverlay.url.path))
+    }
+  }
+
+  func testSpaceBudgetRecomputesBeforeDeletingAnotherCandidate() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let sharedBase = try installContent(Data(repeating: 0x41, count: 128 * 1024), into: contentStore)
+      let newestOverlay = try installContent(Data("newest-overlay".utf8), into: contentStore)
+      let middleOverlay = try installContent(Data("middle-overlay".utf8), into: contentStore)
+      let retainedBase = try installContent(Data(repeating: 0x42, count: 32 * 1024), into: contentStore)
+      let retainedOverlay = try installContent(Data("retained-overlay".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+
+      let newest = try createRecord(for: stackedManifest(
+        baseContentDigest: sharedBase.digest,
+        overlayContentDigest: newestOverlay.digest,
+        baseUncompressedSize: UInt64(try sharedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try newestOverlay.url.sizeBytes())
+      ), in: storage)
+      let middle = try createRecord(for: stackedManifest(
+        baseContentDigest: sharedBase.digest,
+        overlayContentDigest: middleOverlay.digest,
+        baseUncompressedSize: UInt64(try sharedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try middleOverlay.url.sizeBytes())
+      ), in: storage)
+      let retained = try createRecord(for: stackedManifest(
+        baseContentDigest: retainedBase.digest,
+        overlayContentDigest: retainedOverlay.digest,
+        baseUncompressedSize: UInt64(try retainedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try retainedOverlay.url.sizeBytes())
+      ), in: storage)
+      try newest.url.updateAccessDate(Date(timeIntervalSince1970: 3))
+      try middle.url.updateAccessDate(Date(timeIntervalSince1970: 2))
+      try retained.url.updateAccessDate(Date(timeIntervalSince1970: 1))
+
+      let retainedCandidate = try XCTUnwrap(storage.prunables().first {
+        $0.url.lastPathComponent == retained.url.lastPathComponent
+      })
+
+      // Initially the newest record owns the shared base and is too large.
+      // The middle record appears small enough to retain, making the oldest
+      // unrelated record look like a second deletion candidate. After the
+      // first deletion, ownership moves to the middle record; recomputing
+      // before selecting again must delete it and preserve the unrelated one.
+      try Prune.pruneSpaceBudget(
+        prunableStorages: [storage],
+        spaceBudgetBytes: UInt64(try retainedCandidate.allocatedSizeBytes())
+      )
+
+      XCTAssertFalse(FileManager.default.fileExists(atPath: newest.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: middle.url.path))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: retained.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: sharedBase.url.path))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: retainedBase.url.path))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: retainedOverlay.url.path))
+    }
+  }
+
+  func testAutomaticReclaimRecomputesSharedContentAfterOwnerDeletion() throws {
+    try withTemporaryTartHome {
+      let contentStore = try ContentStore()
+      let sharedBase = try installContent(Data(repeating: 0x41, count: 128 * 1024), into: contentStore)
+      let initiatorOverlay = try installContent(Data("initiator-overlay".utf8), into: contentStore)
+      let ownerOverlay = try installContent(Data("owner-overlay".utf8), into: contentStore)
+      let unrelatedBase = try installContent(Data("unrelated-base".utf8), into: contentStore)
+      let unrelatedOverlay = try installContent(Data("unrelated-overlay".utf8), into: contentStore)
+      let storage = try VMStorageOCI()
+
+      let initiatorManifest = try stackedManifest(
+        baseContentDigest: sharedBase.digest,
+        overlayContentDigest: initiatorOverlay.digest,
+        baseUncompressedSize: UInt64(try sharedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try initiatorOverlay.url.sizeBytes())
+      )
+      let ownerManifest = try stackedManifest(
+        baseContentDigest: sharedBase.digest,
+        overlayContentDigest: ownerOverlay.digest,
+        baseUncompressedSize: UInt64(try sharedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try ownerOverlay.url.sizeBytes())
+      )
+      let unrelatedManifest = try stackedManifest(
+        baseContentDigest: unrelatedBase.digest,
+        overlayContentDigest: unrelatedOverlay.digest,
+        baseUncompressedSize: UInt64(try unrelatedBase.url.sizeBytes()),
+        overlayUncompressedSize: UInt64(try unrelatedOverlay.url.sizeBytes())
+      )
+      let initiator = try createRecord(for: initiatorManifest, in: storage)
+      let owner = try createRecord(for: ownerManifest, in: storage)
+      let unrelated = try createRecord(for: unrelatedManifest, in: storage)
+      try initiator.url.updateAccessDate(Date(timeIntervalSince1970: 1))
+      try owner.url.updateAccessDate(Date(timeIntervalSince1970: 2))
+      try unrelated.url.updateAccessDate(Date(timeIntervalSince1970: 3))
+
+      let sharedBaseSize = UInt64(try sharedBase.url.allocatedSizeBytes())
+
+      // The owner is the first deletable record and is initially charged for
+      // the shared base. Deleting it cannot reclaim that base because the
+      // protected initiator still references it, so reclaim must continue.
+      try Prune.reclaimIfPossible(sharedBaseSize, initiator)
+
+      XCTAssertTrue(FileManager.default.fileExists(atPath: initiator.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: owner.url.path))
+      XCTAssertFalse(FileManager.default.fileExists(atPath: unrelated.url.path))
+      XCTAssertTrue(FileManager.default.fileExists(atPath: sharedBase.url.path))
+    }
+  }
+
+  #if canImport(DiskImageKit)
+    @available(macOS 27.0, *)
+    func testPopulateStackedPushedImageCachesImmutableTopOverlay() throws {
+      if #unavailable(macOS 27.0) {
+        throw XCTSkip("DiskImageKit tests require macOS 27 or newer")
+      }
+
+      try withTemporaryTartHome {
+        let source = try diskImageSource()
+        let stacked = try temporaryVMDirectory()
+        try source.cloneAsStackedBase(to: stacked, generateMAC: false)
+
+        var manifest = try OCIManifest(fromJSON: Data(contentsOf: stacked.manifestURL))
+        let contentDigest = try Digest.hash(stacked.overlayURL)
+        var overlay = OCIManifestLayer(
+          mediaType: asifOverlayMediaType,
+          size: 1,
+          digest: "sha256:overlay-transport",
+          uncompressedSize: 1,
+          uncompressedContentDigest: "sha256:overlay-chunk"
+        )
+        overlay.annotations?[diskFileContentDigestAnnotation] = contentDigest
+        overlay.annotations?[diskFileChunkCountAnnotation] = "1"
+        manifest.layers.insert(overlay, at: manifest.layers.count - 1)
+
+        let name = try digestName(for: manifest)
+        let storage = try VMStorageOCI()
+        try storage.populate(name, from: stacked, manifest: manifest)
+
+        let cached = try storage.open(name)
+        XCTAssertTrue(cached.isStackedCachedImage)
+        XCTAssertFalse(FileManager.default.fileExists(atPath: cached.overlayURL.path))
+        XCTAssertEqual(try OCIManifest(fromJSON: Data(contentsOf: cached.manifestURL)), manifest)
+
+        let cachedContent = try XCTUnwrap(try ContentStore().existingContentURL(for: contentDigest))
+        XCTAssertEqual(try Digest.hash(cachedContent), contentDigest)
+      }
+    }
+  #endif
+
+  private func standaloneSource(diskData: Data) throws -> VMDirectory {
+    let vmDir = try temporaryVMDirectory()
+    try config().save(toURL: vmDir.configURL)
+    XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.nvramURL.path, contents: Data()))
+    try diskData.write(to: vmDir.diskURL)
+
+    return vmDir
+  }
+
+  private func createRecord(for manifest: OCIManifest, in storage: VMStorageOCI) throws -> VMDirectory {
+    let record = try storage.create(try digestName(for: manifest))
+    try config().save(toURL: record.configURL)
+    XCTAssertTrue(FileManager.default.createFile(atPath: record.nvramURL.path, contents: Data()))
+    try manifest.toJSON().write(to: record.manifestURL)
+
+    return record
+  }
+
+  private func assertDeletionWaitsForPruneLock(
+    record: VMDirectory,
+    deletion: @escaping () throws -> Void
+  ) throws {
+    let contentStore = try ContentStore()
+    let lockHeld = DispatchSemaphore(value: 0)
+    let releaseLock = DispatchSemaphore(value: 0)
+    let deletionStarted = DispatchSemaphore(value: 0)
+    let deletionFinished = DispatchSemaphore(value: 0)
+
+    DispatchQueue.global().async {
+      try? contentStore.withPruneLock {
+        lockHeld.signal()
+        releaseLock.wait()
+      }
+    }
+    XCTAssertEqual(lockHeld.wait(timeout: .now() + 1), .success)
+
+    DispatchQueue.global().async {
+      deletionStarted.signal()
+      try? deletion()
+      deletionFinished.signal()
+    }
+    XCTAssertEqual(deletionStarted.wait(timeout: .now() + 1), .success)
+    XCTAssertEqual(deletionFinished.wait(timeout: .now() + 0.1), .timedOut)
+    XCTAssertTrue(FileManager.default.fileExists(atPath: record.baseURL.path))
+
+    releaseLock.signal()
+    XCTAssertEqual(deletionFinished.wait(timeout: .now() + 1), .success)
+    XCTAssertFalse(FileManager.default.fileExists(atPath: record.baseURL.path))
+  }
+
+  #if canImport(DiskImageKit)
+    @available(macOS 27.0, *)
+    private func diskImageSource() throws -> VMDirectory {
+      let vmDir = try temporaryVMDirectory()
+      try config().save(toURL: vmDir.configURL)
+      XCTAssertTrue(FileManager.default.createFile(atPath: vmDir.nvramURL.path, contents: Data()))
+      _ = try DiskImage(creating: .raw(url: vmDir.diskURL, blockCount: 8))
+      try flatManifest().toJSON().write(to: vmDir.manifestURL)
+
+      return vmDir
+    }
+  #endif
+
+  private func config() -> VMConfig {
+    VMConfig(
+      platform: Linux(),
+      cpuCountMin: 2,
+      memorySizeMin: 512 * 1024 * 1024,
+      diskFormat: .raw
+    )
+  }
+
+  private func flatManifest() throws -> OCIManifest {
+    let disk = OCIManifestLayer(
+      mediaType: diskV2MediaType,
+      size: 1,
+      digest: "sha256:disk-transport",
+      uncompressedSize: 1,
+      uncompressedContentDigest: "sha256:disk-chunk"
+    )
+
+    return OCIManifest(
+      config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+      layers: [
+        OCIManifestLayer(mediaType: configMediaType, size: 1, digest: "sha256:config"),
+        disk,
+        OCIManifestLayer(mediaType: nvramMediaType, size: 1, digest: "sha256:nvram"),
+      ]
+    )
+  }
+
+  private func stackedManifest(
+    baseContentDigest: String = "sha256:base",
+    overlayContentDigest: String = "sha256:overlay",
+    baseUncompressedSize: UInt64 = 1,
+    overlayUncompressedSize: UInt64 = 1
+  ) throws -> OCIManifest {
+    var manifest = try flatManifest()
+    manifest.annotations?[diskBlockSizeAnnotation] = "512"
+    manifest.annotations?[uncompressedDiskSizeAnnotation] = "4096"
+    manifest.layers[1].annotations?[diskFileContentDigestAnnotation] = baseContentDigest
+    manifest.layers[1].annotations?[uncompressedSizeAnnotation] = String(baseUncompressedSize)
+    var overlay = OCIManifestLayer(
+      mediaType: asifOverlayMediaType,
+      size: 1,
+      digest: "sha256:overlay-transport",
+      uncompressedSize: overlayUncompressedSize,
+      uncompressedContentDigest: "sha256:overlay-chunk"
+    )
+    overlay.annotations?[diskFileContentDigestAnnotation] = overlayContentDigest
+    overlay.annotations?[diskFileChunkCountAnnotation] = "1"
+    manifest.layers.insert(overlay, at: manifest.layers.count - 1)
+
+    return manifest
+  }
+
+  private func installContent(_ data: Data, contentDigest: String, into contentStore: ContentStore) throws {
+    let temporaryURL = try contentStore.temporaryContentURL(for: contentDigest)
+    try data.write(to: temporaryURL)
+    _ = try contentStore.install(temporaryURL, contentDigest: contentDigest)
+  }
+
+  private func pinnedBaseManifest(contentDigest: String) -> OCIManifest {
+    var disk = OCIManifestLayer(
+      mediaType: diskV2MediaType,
+      size: 1,
+      digest: "sha256:disk-transport",
+      uncompressedSize: 1,
+      uncompressedContentDigest: "sha256:disk-chunk"
+    )
+    disk.annotations?[diskFileContentDigestAnnotation] = contentDigest
+
+    return OCIManifest(
+      config: OCIManifestConfig(size: 1, digest: "sha256:oci-config"),
+      layers: [
+        OCIManifestLayer(mediaType: configMediaType, size: 1, digest: "sha256:config"),
+        disk,
+        OCIManifestLayer(mediaType: nvramMediaType, size: 1, digest: "sha256:nvram"),
+      ]
+    )
+  }
+
+  private func installContent(_ data: Data, into contentStore: ContentStore) throws -> (digest: String, url: URL) {
+    let digest = Digest.hash(data)
+    let temporaryURL = try contentStore.temporaryContentURL(for: digest)
+    try data.write(to: temporaryURL)
+
+    return (digest, try contentStore.install(temporaryURL, contentDigest: digest))
+  }
+
+  private func digestName(for manifest: OCIManifest) throws -> RemoteName {
+    RemoteName(
+      host: "example.com",
+      namespace: "org/image",
+      reference: Reference(digest: try manifest.digest())
+    )
+  }
+
+  private func withTemporaryTartHome(_ body: () throws -> Void) throws {
+    let home = try temporaryDirectory()
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", home.path, 1)
+    defer {
+      if let previousHome {
+        setenv("TART_HOME", previousHome, 1)
+      } else {
+        unsetenv("TART_HOME")
+      }
+    }
+
+    try body()
+  }
+
+  private func withTemporaryTartHome(_ body: () async throws -> Void) async throws {
+    let home = try temporaryDirectory()
+    let previousHome = ProcessInfo.processInfo.environment["TART_HOME"]
+    setenv("TART_HOME", home.path, 1)
+    defer {
+      if let previousHome {
+        setenv("TART_HOME", previousHome, 1)
+      } else {
+        unsetenv("TART_HOME")
+      }
+    }
+
+    try await body()
+  }
+
+  private func temporaryVMDirectory() throws -> VMDirectory {
+    VMDirectory(baseURL: try temporaryDirectory())
+  }
+
+  private func temporaryDirectory() throws -> URL {
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false)
+    addTeardownBlock {
+      try? FileManager.default.removeItem(at: url)
+    }
+
+    return url
+  }
+}

actool.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Set shell options to enable fail-fast behavior
+#
+# * -e: fail the script when an error occurs or command fails
+# * -u: fail the script when attempting to reference unset parameters
+# * -o pipefail: by default an exit status of a pipeline is that of its
+#                last command, this fails the pipe early if an error in
+#                any of its commands occurs
+#
+set -euo pipefail
+
+OUTPUT_PATH="Resources/actool"
+PLIST_PATH="$OUTPUT_PATH/Info.plist"
+
+rm -rf "${OUTPUT_PATH}"
+mkdir -p "${OUTPUT_PATH}"
+
+actool "Resources/UPW Tart.icon" \
+  --compile "${OUTPUT_PATH}" \
+  --output-format human-readable-text \
+  --notices \
+  --warnings \
+  --errors \
+  --app-icon "UPW Tart" \
+  --output-partial-info-plist $PLIST_PATH \
+  --include-all-app-icons \
+  --target-device mac \
+  --minimum-deployment-target 13.0 \
+  --platform macosx

benchmark/README.md

@@ -13,7 +13,7 @@ brew install go
 Finally, run the following command from this (`benchmark/`) directory:
 
 ```shell
-go run cmd/main.go fio --image ghcr.io/cirruslabs/macos-sequoia-base:latest --prepare 'sudo purge && sync'
+go run cmd/main.go fio --image ghcr.io/cirruslabs/macos-tahoe-base:latest --prepare 'sudo purge && sync'
 ```
 
 You can also enable the debugging output to diagnose issues:
@@ -22,6 +22,32 @@ You can also enable the debugging output to diagnose issues:
 go run cmd/main.go fio --debug
 ```
 
+To compare an empty Tart home with the same pull after its immutable base has
+been prewarmed, provide a standalone remote base image and a stacked image built
+from it. For example, create and push a stacked child of the public Tahoe base:
+
+```shell
+BASE_IMAGE=ghcr.io/cirruslabs/macos-tahoe-base:latest
+STACKED_IMAGE=ghcr.io/your-org/macos-tahoe-stacked:latest
+
+tart clone --stacked "$BASE_IMAGE" macos-tahoe-stacked
+tart push macos-tahoe-stacked "$STACKED_IMAGE"
+```
+
+Then benchmark that pair:
+
+```shell
+go run cmd/main.go stacked-oci \
+  --base-image "$BASE_IMAGE" \
+  --image "$STACKED_IMAGE"
+```
+
+The command first performs an unmeasured pull to warm registry, CDN, and
+filesystem caches. It then uses disposable `TART_HOME` directories for both
+measured scenarios. The prewarmed scenario keeps the VM created by
+`tart clone --stacked` alive while pulling the child, so the shared immutable
+base layer remains referenced and available for reuse.
+
 ## Results
 
 ### Mar 27, 2024