Ignore commented-out bootptab reservations (#1358)

* fix(control-socket): recover from transient accept errors

Keep the control socket alive when Darwin reports a transient fcntl failure while accepting a client connection.

Refs #1346

* test(control-socket): use synchronous pipeline lookup

* test(control-socket): query handler on event loop

* fix(control-socket): preserve channel backpressure

* test(control-socket): exercise accept error recovery

* test(control-socket): verify accepts continue after transient errors

Check that the real server inbound stream yields a client connection after
each simulated accept error. Keep the read-routing and unrelated-error
checks, bound the wait, and close the test connections.

Adapted from the regression test suggested in:
https://github.com/openai/tart/pull/1351#issuecomment-5851285933

---------

Co-authored-by: Yibo Zhuang <yzhuang@openai.com>

.ci/build-release.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+set -eu
+
+ARCH="$1"
+SCRATCH_PATH=".build/$ARCH"
+OUTPUT_PATH=".build/prebuilt/$ARCH"
+SWIFT_COMPATIBILITY_LIBRARY="$(dirname "$(xcrun --find swiftc)")/../lib/swift-6.2/macosx/libswiftCompatibilitySpan.dylib"
+
+swift build \
+  --build-system swiftbuild \
+  --scratch-path "$SCRATCH_PATH" \
+  --arch "$ARCH" \
+  --configuration release \
+  -Xlinker -weak_library \
+  -Xlinker "$SWIFT_COMPATIBILITY_LIBRARY" \
+  --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,5 +1,11 @@
 #!/bin/sh
 
+set -e
+
+: "${VERSION:?VERSION must be set}"
+
 TMPFILE=$(mktemp)
-envsubst < Sources/tart/CI/CI.swift > $TMPFILE
-mv $TMPFILE Sources/tart/CI/CI.swift
+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 Sonoma
+  name: Test
   alias: test
   persistent_worker:
     labels:
@@ -11,17 +11,19 @@ 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
     - export PATH=$(pwd)/.build/arm64-apple-macosx/debug:$PATH
     # Run integration tests
     - cd integration-tests
-    - HOMEBREW_NO_AUTO_UPDATE=1 brew install virtualenv
-    - virtualenv venv
+    - python3 -m venv --symlinks venv
     - 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
@@ -38,7 +40,7 @@ task:
   name: Lint
   alias: lint
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sonoma
+    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:
@@ -55,105 +57,21 @@ task:
   name: Build ($BUILD_ARCH)
   alias: build
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-runner:sonoma
+    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:sonoma
-  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 goreleaser/tap/goreleaser-pro
-    - brew install mitchellh/gon/gon
-  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:sonoma
-  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 goreleaser/tap/goreleaser-pro getsentry/tools/sentry-cli
-    - brew install mitchellh/gon/gon
-  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!]
-  deploy_script: 
+  deploy_script:
     - git config --global user.name "Cirrus CI"
     - git config --global user.name "hello@cirruslabs.org"
     - git remote set-url origin https://$DEPLOY_TOKEN@github.com/cirruslabs/tart/

.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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      - 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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      - 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@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        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/*

.gitignore

@@ -8,6 +8,9 @@ tart.xcodeproj/
 # AppCode
 .idea/
 
+# VS Code
+.vscode/
+
 # Swift
 .build/
 

.goreleaser.yml

@@ -1,11 +1,12 @@
+version: 2
+
 project_name: tart
 
 before:
   hooks:
     - .ci/set-version.sh
-    - swift build --arch x86_64 -c release --product tart
-    - swift build --arch arm64 -c release --product tart
-    - gon gon.hcl
+    - sh .ci/build-release.sh arm64
+    - sh .ci/build-release.sh x86_64
 
 builds:
   - id: tart
@@ -18,20 +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:
+        - 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 }}-{{ .Arch }}"
+  - 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:
@@ -39,19 +53,34 @@ release:
 
 brews:
   - name: tart
+    directory: Formula
     repository:
-      owner: cirruslabs
-      name: homebrew-cli
-    caveats: See the GitHub repository for more information
-    homepage: https://github.com/cirruslabs/tart
-    license: "Fair Source"
+      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:
+
+        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/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
@@ -29,6 +29,7 @@ Table of Contents
 
 1. Code should follow camel case
 2. Code should follow [SwiftFormat](https://github.com/nicklockwood/SwiftFormat#swift-package-manager-plugin) guidelines. You can auto-format the code by running the following command:
+
 ```bash
 swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore .
 ```

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

@@ -0,0 +1,64 @@
+# Profiling Tart
+
+## Using `time(1)`
+
+Perhaps, the easiest, but not the most comprehensive way to tell what's going on with Tart is to use the [`time(1)`](https://ss64.com/mac/time.html) command.
+
+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-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.
+
+**Note:** The `-l` command-line argument makes `time(1)` return much more useful information, for example, maximum memory usage.
+
+When running the command above, you'll see the `tart pull` output first as it pulls the image, and then the `time(1)` output, which will be printed once the Tart process finishes:
+
+```
+      172.17 real        10.29 user         8.36 sys
+           353796096  maximum resident set size
+                   0  average shared memory size
+                   0  average unshared data size
+                   0  average unshared stack size
+               23838  page reclaims
+                  35  page faults
+                   0  swaps
+                   0  block input operations
+                   0  block output operations
+                   8  messages sent
+                   8  messages received
+                   0  signals received
+                 146  voluntary context switches
+              222950  involuntary context switches
+         39683070975  instructions retired
+         27562035252  cycles elapsed
+           170920448  peak memory footprint
+```
+
+From the output above, you can tell that `tart pull` spent nearly 90% of time off-CPU (`real` > `user` + `sys`), which means that Tart was mostly waiting for the I/O (be it a network or disk), instead of decompressing disk layers or doing other useful computations.
+
+## Using `xctrace(1)`
+
+[`xctrace(1)`](https://keith.github.io/xcode-man-pages/xctrace.1.html) is a `.trace` format recorder for the [Instruments](https://en.wikipedia.org/wiki/Instruments_(software)) app, which yields much more powerful insights compared to `time(1)`. For example, it can tell which Tart functions spent the most time on the CPU, thus allowing the Tart developers to further optimize these functions.
+
+To use it, make sure that [Xcode](https://developer.apple.com/xcode/resources/) is installed. If you're installing Xcode for the first time on the machine, you'll need to launch it once and click the blue "Install" button. There's no need to choose any platforms except for the macOS.
+
+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-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:
+
+```
+Output file saved as: Launch_[...].trace
+```
+
+To view this trace in the Instruments app, simply find this directory in Finder and double-click it. Instruments app will appear:
+
+![](Resources/Instruments.png)
+
+To send this trace, right-click its directory in Finder and choose "Compress [...]". This will result in a similarly named file with a `.zip` at the end, which can now be conveniently sent via email or uploaded.

Package.resolved

@@ -1,13 +1,31 @@
 {
-  "originHash" : "2c514a4a1d7e106713db744bee89edb40d75da63e6611990ec2f4b0da53c0455",
+  "originHash" : "061dfe6cdf4e6dbf32b51c5e7023c4ae69726dcafb42a35b34e5489b0338c17f",
   "pins" : [
     {
       "identity" : "antlr4",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/antlr/antlr4",
       "state" : {
-        "branch" : "dev",
-        "revision" : "2703a8516c0fb7fe92db6b9c40e0113f577646d2"
+        "revision" : "cc82115a4e7f53d71d9d905caa2c2dfa4da58899",
+        "version" : "4.13.2"
+      }
+    },
+    {
+      "identity" : "cirruslabs_tart-guest-agent_apple_swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://buf.build/gen/swift/git/1.33.3-20260114140118-bd09c26a260f.1/cirruslabs_tart-guest-agent_apple_swift.git",
+      "state" : {
+        "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.27.1-20260114140118-bd09c26a260f.1/cirruslabs_tart-guest-agent_grpc_swift.git",
+      "state" : {
+        "branch" : "main",
+        "revision" : "4935078c2fe2508360843596d71a1f844ce639a6"
       }
     },
     {
@@ -19,22 +37,49 @@
         "revision" : "772883073d044bc754d401cabb6574624eb3778f"
       }
     },
+    {
+      "identity" : "grpc-swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/grpc/grpc-swift.git",
+      "state" : {
+        "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"
+      }
+    },
     {
       "identity" : "semaphore",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/groue/Semaphore",
       "state" : {
-        "revision" : "f1c4a0acabeb591068dea6cffdd39660b86dec28",
-        "version" : "0.0.8"
-      }
-    },
-    {
-      "identity" : "sentry-cocoa",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/getsentry/sentry-cocoa",
-      "state" : {
-        "revision" : "ef4fec9dfb8dd5027b09a4a5c9362feafd118e1a",
-        "version" : "8.24.0"
+        "revision" : "2543679282aa6f6c8ecf2138acd613ed20790bc2",
+        "version" : "0.1.0"
       }
     },
     {
@@ -51,17 +96,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-argument-parser",
       "state" : {
-        "revision" : "46989693916f56d1186bd59ac15124caef896560",
-        "version" : "1.3.1"
-      }
-    },
-    {
-      "identity" : "swift-async-algorithms",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-async-algorithms",
-      "state" : {
-        "branch" : "main",
-        "revision" : "f05e450f0b909c0e80670a47516c4b9700b9e5da"
+        "revision" : "309a47b2b1d9b5e991f36961c983ecec72275be3",
+        "version" : "1.6.1"
       }
     },
     {
@@ -69,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"
       }
     },
     {
@@ -78,8 +114,26 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-collections.git",
       "state" : {
-        "revision" : "f504716c27d2e5d4144fa4794b12129301d17729",
-        "version" : "1.0.3"
+        "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7",
+        "version" : "1.1.4"
+      }
+    },
+    {
+      "identity" : "swift-http-structured-headers",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-structured-headers.git",
+      "state" : {
+        "revision" : "db6eea3692638a65e2124990155cd220c2915903",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-http-types",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-types.git",
+      "state" : {
+        "revision" : "a0a57e949a8903563aba4615869310c0ebf14c03",
+        "version" : "1.4.0"
       }
     },
     {
@@ -87,8 +141,62 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-log.git",
       "state" : {
-        "revision" : "e97a6fcb1ab07462881ac165fdbb37f067e205d5",
-        "version" : "1.5.4"
+        "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"
+      }
+    },
+    {
+      "identity" : "swift-nio",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio.git",
+      "state" : {
+        "revision" : "233f61bc2cfbb22d0edeb2594da27a20d2ce514e",
+        "version" : "2.93.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-extras",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-extras.git",
+      "state" : {
+        "revision" : "f1f6f772198bee35d99dd145f1513d8581a54f2c",
+        "version" : "1.26.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-http2",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-http2.git",
+      "state" : {
+        "revision" : "4281466512f63d1bd530e33f4aa6993ee7864be0",
+        "version" : "1.36.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-ssl",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-ssl.git",
+      "state" : {
+        "revision" : "4b38f35946d00d8f6176fe58f96d83aba64b36c7",
+        "version" : "2.31.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-transport-services",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-transport-services.git",
+      "state" : {
+        "revision" : "cd1e89816d345d2523b11c55654570acd5cd4c56",
+        "version" : "1.24.0"
       }
     },
     {
@@ -100,13 +208,22 @@
         "version" : "1.0.2"
       }
     },
+    {
+      "identity" : "swift-protobuf",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-protobuf.git",
+      "state" : {
+        "revision" : "c169a5744230951031770e27e475ff6eefe51f9d",
+        "version" : "1.33.3"
+      }
+    },
     {
       "identity" : "swift-retry",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/fumoboy007/swift-retry",
       "state" : {
-        "revision" : "9f133487ffc2ab4539688c29efe57bb1ba31d7b0",
-        "version" : "0.2.3"
+        "revision" : "df9d7b185d2e433147ec0083a73c257e665eea0d",
+        "version" : "0.2.4"
       }
     },
     {
@@ -118,6 +235,15 @@
         "version" : "1.8.0"
       }
     },
+    {
+      "identity" : "swift-system",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-system.git",
+      "state" : {
+        "revision" : "a34201439c74b53f0fd71ef11741af7e7caf01e1",
+        "version" : "1.4.2"
+      }
+    },
     {
       "identity" : "swift-xattr",
       "kind" : "remoteSourceControl",
@@ -141,8 +267,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/nicklockwood/SwiftFormat",
       "state" : {
-        "revision" : "9df3b01f477163b33d5e63c5e2e5b9f946a49c56",
-        "version" : "0.53.6"
+        "revision" : "ab6844edb79a7b88dc6320e6cee0a0db7674dac3",
+        "version" : "0.54.5"
       }
     },
     {
@@ -162,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

@@ -10,38 +10,45 @@ let package = Package(
     .executable(name: "tart", targets: ["tart"])
   ],
   dependencies: [
-    .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.1"),
+    .package(url: "https://github.com/apple/swift-argument-parser", from: "1.6.1"),
     .package(url: "https://github.com/mhdhejazi/Dynamic", branch: "master"),
     .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
-    .package(url: "https://github.com/apple/swift-async-algorithms", branch: "main"),
     .package(url: "https://github.com/malcommac/SwiftDate", from: "7.0.0"),
-    .package(url: "https://github.com/antlr/antlr4", branch: "dev"),
+    .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.24.0"),
     .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.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: [
       .product(name: "Algorithms", package: "swift-algorithms"),
-      .product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
       .product(name: "ArgumentParser", package: "swift-argument-parser"),
       .product(name: "Dynamic", package: "Dynamic"),
       .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"),
       .product(name: "Semaphore", package: "Semaphore"),
       .product(name: "DMRetry", package: "swift-retry"),
       .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
-tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base
-tart run sonoma-base
+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

@@ -2,22 +2,28 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-    <key>CFBundleName</key>
-    <string>tart</string>
-    <key>CFBundleIdentifier</key>
-    <string>org.cirruslabs.tart</string>
-    <key>CFBundleExecutable</key>
-    <string>tart</string>
-    <key>LSBackgroundOnly</key>
-    <string>1</string>
-    <key>CFBundleIconFiles</key>
-    <array>
-        <string>AppIcon.png</string>
-    </array>
-    <key>NSAppTransportSecurity</key>
-    <dict>
-        <key>NSAllowsArbitraryLoads</key>
-        <true/>
-    </dict>
+	<key>CFBundleName</key>
+	<string>Tart</string>
+	<key>CFBundleDisplayName</key>
+	<string>Tart</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.github.cirruslabs.tart</string>
+	<key>CFBundleExecutable</key>
+	<string>tart</string>
+	<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>
+		<true/>
+	</dict>
+  <key>NSLocalNetworkUsageDescription</key>
+  <string>Access to OCI registries on the local network</string>
 </dict>
 </plist>

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

@@ -9,12 +9,10 @@ struct Clone: AsyncParsableCommand {
     Creates a local virtual machine by cloning either a remote or another local virtual machine.
 
     Due to copy-on-write magic in Apple File System, a cloned VM won't actually claim all the space right away.
-    Only changes to a cloned disk will be written and claim new space. By default, Tart checks available capacity
-    in Tart's home directory and checks if there is enough space for the worst possible scenario: when the whole disk
-    will be modified.
+    Only changes to a cloned disk will be written and claim new space. This also speeds up clones enormously.
 
-    This behaviour can be disabled by setting TART_NO_AUTO_PRUNE environment variable. This might be helpful
-    for use cases when the original image is very big and a workload is known to only modify a fraction of the cloned disk.
+    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the cloned image
+    to fit. This behaviour is called "automatic pruning" and can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
     """
   )
 
@@ -30,6 +28,18 @@ struct Clone: AsyncParsableCommand {
   @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
   var concurrency: UInt = 4
 
+  @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
+
+  @Flag(help: "overwrite an existing local VM")
+  var overwrite: 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")
@@ -41,16 +51,47 @@ 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) {
+    try rejectExistingDestination(localStorage)
+
+    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)
+      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
@@ -62,20 +103,66 @@ struct Clone: AsyncParsableCommand {
       let lock = try FileLock(lockURL: Config().tartHomeDir)
       try lock.lock()
 
+      try rejectExistingDestination(localStorage)
+
+      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)
 
       try lock.unlock()
 
-      // APFS is doing copy-on-write so the above cloning operation (just copying files on disk)
+      // APFS is doing copy-on-write, so the above cloning operation (just copying files on disk)
       // 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 a little bit of space for the VM to run.
-      try Prune.reclaimIfNeeded(UInt64(sourceVM.allocatedSizeBytes()), sourceVM)
+      //
+      // So, once we clone the VM let's try to claim the rest of space for the VM to run without errors.
+      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()
     })
   }
+
+  private func rejectExistingDestination(_ localStorage: VMStorageLocal) throws {
+    let destinationURL = localStorage.baseURL.appendingPathComponent(newName, isDirectory: true)
+    if !overwrite && FileManager.default.fileExists(atPath: destinationURL.path) {
+      throw ValidationError("VM \"\(newName)\" already exists, use --overwrite to replace it")
+    }
+  }
 }

Sources/tart/Commands/Create.swift

@@ -10,7 +10,7 @@ struct Create: AsyncParsableCommand {
   @Argument(help: "VM name")
   var name: String
 
-  @Option(help: ArgumentHelp("create a macOS VM using path to the IPSW file or URL (or \"latest\", to fetch the latest supported IPSW automatically)", valueName: "path"))
+  @Option(help: ArgumentHelp("create a macOS VM using path to the IPSW file or URL (or \"latest\", to fetch the latest supported IPSW automatically)", valueName: "path"), completion: .file())
   var fromIPSW: String?
 
   @Flag(help: "create a Linux VM")
@@ -19,6 +19,9 @@ struct Create: AsyncParsableCommand {
   @Option(help: ArgumentHelp("Disk size in GB"))
   var diskSize: UInt16 = 50
 
+  @Option(help: ArgumentHelp("Disk image format", discussion: "ASIF format provides better performance but requires macOS 26 Tahoe or later"))
+  var diskFormat: DiskImageFormat = .raw
+
   func validate() throws {
     if fromIPSW == nil && !linux {
       throw ValidationError("Please specify either a --from-ipsw or --linux option!")
@@ -28,6 +31,11 @@ struct Create: AsyncParsableCommand {
         throw ValidationError("Only Linux VMs are supported on Intel!")
       }
     #endif
+
+    // Validate disk format support
+    if !diskFormat.isSupported {
+      throw ValidationError("Disk format '\(diskFormat.rawValue)' is not supported on this system.")
+    }
   }
 
   func run() async throws {
@@ -58,14 +66,18 @@ struct Create: AsyncParsableCommand {
             ipswURL = URL(fileURLWithPath: NSString(string: fromIPSW).expandingTildeInPath)
           }
 
-          _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize)
+          _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize, diskFormat: diskFormat)
         }
       #endif
 
       if linux {
-        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
+        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize, diskFormat: diskFormat)
       }
 
+      // Publish under the same lock that run holds while opening VM files.
+      let storageLock = try FileLock(lockURL: Config().tartHomeDir)
+      try storageLock.lock()
+      defer { withExtendedLifetime(storageLock) {} }
       try VMStorageLocal().move(name, from: tmpVMDir)
     }, onCancel: {
       try? FileManager.default.removeItem(at: tmpVMDir.baseURL)

Sources/tart/Commands/Exec.swift

@@ -0,0 +1,225 @@
+import ArgumentParser
+import Foundation
+import GRPC
+import Cirruslabs_TartGuestAgent_Grpc_Swift
+
+struct ExecCustomExitCodeError: Error {
+  let exitCode: Int32
+}
+
+struct Exec: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Execute a command in a running VM", discussion: """
+  Requires Tart Guest Agent running in a guest VM.
+
+  Note that all non-vanilla Cirrus Labs VM images already have the Tart Guest Agent installed.
+  """)
+
+  @Flag(name: [.customShort("i")], help: "Attach host's standard input to a remote command")
+  var interactive: Bool = false
+
+  @Flag(name: [.customShort("t")], help: "Allocate a remote pseudo-terminal (PTY)")
+  var tty: Bool = false
+
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
+  var name: String
+
+  @Argument(parsing: .captureForPassthrough, help: "Command to execute")
+  var command: [String]
+
+  func run() async throws {
+    // We only have withThrowingDiscardingTaskGroup available starting from macOS 14
+    if #unavailable(macOS 14) {
+      throw RuntimeError.Generic("\"tart exec\" is only available on macOS 14 (Sonoma) or newer")
+    }
+
+    // Open VM's directory
+    let vmDir = try VMStorageLocal().open(name)
+
+    // Ensure that the VM is running
+    if try !vmDir.running() {
+      throw RuntimeError.VMNotRunning(name)
+    }
+
+    // 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.absoluteURL.path(percentEncoded: false))
+    }
+
+    // Switch controlling terminal into raw mode when remote pseudo-terminal is requested
+    var state: State? = nil
+
+    if tty && Term.IsTerminal() {
+      state = try Term.MakeRaw()
+    }
+    defer {
+      // Restore terminal to its initial state
+      if let state {
+        try! Term.Restore(state)
+      }
+    }
+
+    // Execute a command in a running VM
+    do {
+      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?")
+    }
+  }
+
+  private func execute(_ channel: GRPCChannel) async throws {
+    let agentAsyncClient = AgentAsyncClient(channel: channel)
+    let execCall = agentAsyncClient.makeExecCall()
+
+    try await execCall.requestStream.send(.with {
+      $0.type = .command(.with {
+        $0.name = command[0]
+        $0.args = Array(command.dropFirst(1))
+        $0.interactive = interactive
+        $0.tty = tty
+        if tty {
+          $0.terminalSize = .with {
+            let (width, height) = try! Term.GetSize()
+
+            $0.cols = UInt32(width)
+            $0.rows = UInt32(height)
+          }
+        }
+      })
+    })
+
+    // Process command events and optionally send our standard input and/or terminal dimensions
+    try await withThrowingTaskGroup { group in
+      // Stream host's standard input if interactive mode is enabled
+      if interactive {
+        let stdinStream = AsyncThrowingStream<Data, Error> { continuation in
+          let handle = FileHandle.standardInput
+
+          if isRegularFile(handle.fileDescriptor) {
+            // Standard input can be a regular file when input redirection (<) is used,
+            // in which case the handle won't receive any new readability events, so we
+            // just read the file normally here in chunks and consider done with it
+            //
+            // Ideally this is best handled by using non-blocking I/O, but Swift's
+            // standard library only offers inefficient bytes[1] property and SwiftNIO's
+            // NIOFileSystem doesn't seem to support opening raw file descriptors.
+            //
+            // [1]: https://developer.apple.com/documentation/foundation/filehandle/bytes
+            while true {
+              do {
+                let data = try handle.read(upToCount: 64 * 1024)
+                if let data = data {
+                  continuation.yield(data)
+                } else {
+                  continuation.finish()
+                  break
+                }
+              } catch (let error) {
+                continuation.finish(throwing: error)
+                break
+              }
+            }
+          } else {
+            handle.readabilityHandler = { handle in
+              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)
+              }
+            }
+          }
+        }
+
+        group.addTask {
+          for try await stdinData in stdinStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .standardInput(.with {
+                $0.data = stdinData
+              })
+            })
+          }
+
+          // Signal EOF as we're done reading standard input
+          try await execCall.requestStream.send(.with {
+            $0.type = .standardInput(.with {
+              $0.data = Data()
+            })
+          })
+        }
+      }
+
+      // Stream host's terminal dimensions if pseudo-terminal is requested
+      signal(SIGWINCH, SIG_IGN)
+      let sigwinchSrc = DispatchSource.makeSignalSource(signal: SIGWINCH)
+      sigwinchSrc.activate()
+
+      if tty {
+        let terminalDimensionsStream = AsyncStream { continuation in
+          sigwinchSrc.setEventHandler {
+            continuation.yield(try! Term.GetSize())
+          }
+        }
+
+        group.addTask {
+          for await (width, height) in terminalDimensionsStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .terminalResize(.with {
+                $0.cols = UInt32(width)
+                $0.rows = UInt32(height)
+              })
+            })
+          }
+        }
+      }
+
+      // Process command events
+      group.addTask {
+        for try await response in execCall.responseStream {
+          switch response.type {
+          case .standardOutput(let ioChunk):
+            try FileHandle.standardOutput.write(contentsOf: ioChunk.data)
+          case .standardError(let ioChunk):
+            try FileHandle.standardError.write(contentsOf: ioChunk.data)
+          case .exit(let exit):
+            throw ExecCustomExitCodeError(exitCode: exit.code)
+          default:
+            // Unknown event, do nothing
+            continue
+          }
+        }
+      }
+
+      while !group.isEmpty {
+        do {
+          try await group.next()
+        } catch {
+          group.cancelAll()
+
+          throw error
+        }
+      }
+    }
+  }
+}
+
+private func isRegularFile(_ fileDescriptor: Int32) -> Bool {
+  var stat = stat()
+
+  if fstat(fileDescriptor, &stat) != 0 {
+    return false
+  }
+
+  return (stat.st_mode & S_IFMT) == S_IFREG
+}

Sources/tart/Commands/Export.swift

@@ -7,7 +7,7 @@ struct Export: AsyncParsableCommand {
   @Argument(help: "Source VM name.", completion: .custom(completeMachines))
   var name: String
 
-  @Argument(help: "Path to the destination file.")
+  @Argument(help: "Path to the destination file.", completion: .file())
   var path: String?
 
   func run() async throws {
@@ -37,7 +37,7 @@ struct Export: AsyncParsableCommand {
   func userWantsOverwrite(_ filename: String) -> Bool {
     print("file \(filename) already exists, are you sure you want to overwrite it? (yes, [no])? ", terminator: "")
 
-    let answer = readLine()!
+    let answer = readLine()
 
     return answer == "yes"
   }

Sources/tart/Commands/Get.swift

@@ -5,8 +5,9 @@ fileprivate struct VMInfo: Encodable {
   let OS: OS
   let CPU: Int
   let Memory: UInt64
-  let Disk: Int
-  let Size: String
+  let Disk: HumanReadableByteCount
+  let DiskFormat: String
+  let Size: HumanReadableByteCount
   let Display: String
   let Running: Bool
   let State: String
@@ -26,7 +27,20 @@ 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(), 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,
+      // ASIF capacity lookup can fail while a running VM holds the disk open.
+      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,12 +2,11 @@ import ArgumentParser
 import Foundation
 import Network
 import SystemConfiguration
-import Sentry
 
 enum IPResolutionStrategy: String, ExpressibleByArgument, CaseIterable {
-  case dhcp, arp
+  case dhcp, arp, agent
 
-  private(set) static var allValueStrings: [String] = Format.allCases.map { "\($0)"}
+  private(set) static var allValueStrings: [String] = Self.allCases.map { "\($0)"}
 }
 
 struct IP: AsyncParsableCommand {
@@ -19,13 +18,11 @@ struct IP: AsyncParsableCommand {
   @Option(help: "Number of seconds to wait for a potential VM booting")
   var wait: UInt16 = 0
 
-  @Option(help: ArgumentHelp("Strategy for resolving IP address: dhcp or arp",
+  @Option(help: ArgumentHelp("Strategy for resolving IP address",
                              discussion: """
-                             By default, Tart is looking up and parsing DHCP lease file to determine the IP of the VM.\n
-                             This method is fast and the most reliable but only returns local IP adresses.\n
-                             Alternatively, Tart can call external `arp` executable and parse it's output.\n
-                             In case of enabled Bridged Networking this method will return VM's IP address on the network interface used for Bridged Networking.\n
-                             Note that `arp` strategy won't work for VMs using `--net-softnet`.
+                             By default, Tart is using a "dhcp" resolver which parses the DHCP reservation file, then the lease file on host and tries to find an entry containing the VM's MAC address. This method is fast and the most reliable, but only works for VMs not using the bridged networking.\n
+                             Alternatively, Tart has an "arp" resolver which calls an external "arp" executable and parses it's output. This works for VMs using bridged networking and returns their IP, but when they generate enough network activity to populate the host's ARP table. Note that "arp" strategy won't work for VMs using the Softnet networking.\n
+                             A third strategy, "agent" works in all cases reliably, but requires Guest agent for Tart VMs (https://github.com/cirruslabs/tart-guest-agent) to be installed inside of a VM.
                              """))
   var resolver: IPResolutionStrategy = .dhcp
 
@@ -34,14 +31,16 @@ struct IP: AsyncParsableCommand {
     let vmConfig = try VMConfig.init(fromURL: vmDir.configURL)
     let vmMACAddress = MACAddress(fromString: vmConfig.macAddress.string)!
 
-    guard let ip = try await IP.resolveIP(vmMACAddress, resolutionStrategy: resolver, secondsToWait: wait) else {
+    guard let ip = try await IP.resolveIP(vmMACAddress, resolutionStrategy: resolver, secondsToWait: wait, controlSocketURL: vmDir.controlSocketURL) else {
       var message = "no IP address found"
 
       if try !vmDir.running() {
         message += ", is your VM running?"
       }
 
-      if (vmConfig.os == .linux && resolver == .arp) {
+      if (resolver == .agent) {
+        message += " (also make sure that Guest agent for Tart is running inside of a VM)"
+      } else if (vmConfig.os == .linux && resolver == .arp) {
         message += " (not all Linux distributions are compatible with the ARP resolver)"
       }
 
@@ -51,7 +50,7 @@ struct IP: AsyncParsableCommand {
     print(ip)
   }
 
-  static public func resolveIP(_ vmMACAddress: MACAddress, resolutionStrategy: IPResolutionStrategy = .dhcp, secondsToWait: UInt16 = 0) async throws -> IPv4Address? {
+  static public func resolveIP(_ vmMACAddress: MACAddress, resolutionStrategy: IPResolutionStrategy = .dhcp, secondsToWait: UInt16 = 0, controlSocketURL: URL? = nil) async throws -> IPv4Address? {
     let waitUntil = Calendar.current.date(byAdding: .second, value: Int(secondsToWait), to: Date.now)!
 
     repeat {
@@ -61,9 +60,28 @@ struct IP: AsyncParsableCommand {
           return ip
         }
       case .dhcp:
+        if let bootptab = try Bootptab(), let ip = try bootptab.ResolveMACAddress(macAddress: vmMACAddress) {
+          return ip
+        }
         if let leases = try Leases(), let ip = leases.ResolveMACAddress(macAddress: vmMACAddress) {
           return ip
         }
+      case .agent:
+        guard let controlSocketURL = controlSocketURL else {
+          throw RuntimeError.Generic("Cannot perform IP resolution via Tart Guest Agent when control socket URL is not set")
+        }
+
+        // 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.absoluteURL.path(percentEncoded: false))
+        }
+
+        if let ip = try await AgentResolver.ResolveIP(controlSocketURL.relativePath) {
+          return ip
+        }
       }
 
       // wait a second

Sources/tart/Commands/Import.swift

@@ -4,10 +4,10 @@ import Foundation
 struct Import: AsyncParsableCommand {
   static var configuration = CommandConfiguration(abstract: "Import VM from a compressed .tvm file")
 
-  @Argument(help: "Path to a file created with \"tart export\".")
+  @Argument(help: "Path to a file created with \"tart export\".", completion: .file())
   var path: String
 
-  @Argument(help: "Destination VM name.")
+  @Argument(help: "Destination VM name.", completion: .custom(completeLocalMachines))
   var name: String
 
   func validate() throws {
@@ -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
 }
@@ -18,7 +18,7 @@ struct List: AsyncParsableCommand {
   @Option(help: ArgumentHelp("Only display VMs from the specified source (e.g. --source local, --source oci)."))
   var source: String?
 
-  @Option(help: "Output format: text or json")
+  @Option(help: "Output format: text or json", completion: .list(["text", "json"]))
   var format: Format = .text
 
   @Flag(name: [.short, .long], help: ArgumentHelp("Only display VM names."))
@@ -39,13 +39,30 @@ 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,
+          // ASIF capacity lookup can fail while a running VM holds the disk open.
+          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 +78,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,13 +1,13 @@
 import ArgumentParser
 import Dispatch
-import Sentry
+import OpenTelemetryApi
 import SwiftUI
 import SwiftDate
 
 struct Prune: AsyncParsableCommand {
   static var configuration = CommandConfiguration(abstract: "Prune OCI and IPSW caches or local VMs")
 
-  @Option(help: ArgumentHelp("Entries to remove: \"caches\" targets OCI and IPSW caches and \"vms\" targets local VMs."))
+  @Option(help: ArgumentHelp("Entries to remove: \"caches\" targets OCI and IPSW caches and \"vms\" targets local VMs."), completion: .list(["caches", "vms"]))
   var entries: String = "caches"
 
   @Option(help: ArgumentHelp("Remove entries that were last accessed more than n days ago",
@@ -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

@@ -9,8 +9,8 @@ struct Pull: AsyncParsableCommand {
     Pulls a virtual machine from a remote OCI-compatible registry. Supports authorization via Keychain (see "tart login --help"),
     Docker credential helpers defined in ~/.docker/config.json or via TART_REGISTRY_USERNAME/TART_REGISTRY_PASSWORD environment variables.
 
-    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the remote image to fit via "tart prune".
-    This behaviour can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
+    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the remote image
+    to fit. This behaviour is called "automatic pruning" and can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
     """
   )
 
@@ -23,6 +23,9 @@ struct Pull: AsyncParsableCommand {
   @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
   var concurrency: UInt = 4
 
+  @Flag(help: .hidden)
+  var deduplicate: Bool = false
+
   func validate() throws {
     if concurrency < 1 {
       throw ValidationError("network concurrency cannot be less than 1")
@@ -32,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
@@ -43,6 +46,6 @@ struct Pull: AsyncParsableCommand {
 
     defaultLogger.appendNewLine("pulling \(remoteName)...")
 
-    try await VMStorageOCI().pull(remoteName, registry: registry, concurrency: concurrency)
+    try await VMStorageOCI().pull(remoteName, registry: registry, concurrency: concurrency, deduplicate: deduplicate)
   }
 }

Sources/tart/Commands/Push.swift

@@ -26,15 +26,17 @@ struct Push: AsyncParsableCommand {
                              """))
   var chunkSize: Int = 0
 
-  @Option(help: .hidden)
-  var diskFormat: String = "v2"
+
+  @Option(name: [.customLong("label")], help: ArgumentHelp("additional metadata to attach to the OCI image configuration in key=value format",
+                                                           discussion: "Can be specified multiple times to attach multiple labels."))
+  var labels: [String] = []
 
   @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() {
@@ -67,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(
@@ -76,17 +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
+          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)
         }
       }
 
@@ -100,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)
@@ -115,6 +118,28 @@ struct Push: AsyncParsableCommand {
     return RemoteName(host: registry.host!, namespace: registry.namespace,
                       reference: Reference(digest: digest))
   }
+
+  // Helper method to convert labels array to dictionary
+  func parseLabels() -> [String: String] {
+    var result = [String: String]()
+
+    for label in labels {
+      let parts = label.trimmingCharacters(in: .whitespaces).split(separator: "=", maxSplits: 1, omittingEmptySubsequences: false)
+
+      let key = parts.count > 0 ? String(parts[0]) : ""
+      let value = parts.count > 1 ? String(parts[1]) : ""
+
+      // It sometimes makes sense to provide an empty value,
+      // but not an empty key
+      if key.isEmpty {
+        continue
+      }
+
+      result[key] = value
+    }
+
+    return result
+  }  
 }
 
 extension Collection where Element == RemoteName {

Sources/tart/Commands/Rename.swift

@@ -17,7 +17,10 @@ struct Rename: AsyncParsableCommand {
   }
 
   func run() async throws {
-    let localStorage = VMStorageLocal()
+    let localStorage = try VMStorageLocal()
+    let lock = try FileLock(lockURL: Config().tartHomeDir)
+    try lock.lock()
+    defer { withExtendedLifetime(lock) {} }
 
     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?
@@ -45,6 +45,23 @@ extension VZDiskImageSynchronizationMode {
   }
 }
 
+extension VZDiskImageCachingMode {
+  public init?(_ description: String) throws {
+    switch description {
+    case "automatic":
+      self = .automatic
+    case "cached":
+      self = .cached
+    case "uncached":
+      self = .uncached
+    case "":
+      return nil
+    default:
+      throw RuntimeError.VMConfigurationError("unsupported disk image caching mode: \"\(description)\"")
+    }
+  }
+}
+
 struct Run: AsyncParsableCommand {
   static var configuration = CommandConfiguration(abstract: "Run a VM")
 
@@ -64,7 +81,7 @@ struct Run: AsyncParsableCommand {
   @Option(help: ArgumentHelp(
     "Attach an externally created serial console",
     discussion: "Alternative to `--serial` flag for programmatic integrations."
-  ))
+  ), completion: .file())
   var serialPath: String?
 
   @Flag(help: ArgumentHelp("Force open a UI window, even when VNC is enabled.", visibility: .private))
@@ -73,9 +90,12 @@ struct Run: AsyncParsableCommand {
   @Flag(help: "Disable audio pass-through to host.")
   var noAudio: Bool = false
 
+  @Flag(help: "Disable USB accessories.")
+  var noUSBAccessories: Bool = false
+
   @Flag(help: ArgumentHelp(
     "Disable clipboard sharing between host and guest.",
-    discussion: "Only works with Linux-based guest operating systems."))
+    discussion: "Clipboard sharing requires spice-vdagent package on Linux and https://github.com/cirruslabs/tart-guest-agent on macOS."))
   var noClipboard: Bool = false
 
   #if arch(arm64)
@@ -100,7 +120,7 @@ struct Run: AsyncParsableCommand {
   var vncExperimental: Bool = false
 
   @Option(help: ArgumentHelp("""
-  Additional disk attachments with an optional read-only and synchronization options (e.g. --disk="disk.bin", --disk="ubuntu.iso:ro", --disk="/dev/disk0", --disk "ghcr.io/cirruslabs/xcode:16.0:ro" or --disk="nbd://localhost:10809/myDisk:sync=none")
+  Additional disk attachments with an optional read-only and synchronization options in the form of path[:options] (e.g. --disk="disk.bin", --disk="ubuntu.iso:ro", --disk="/dev/disk0", --disk "ghcr.io/cirruslabs/xcode:16.0:ro" or --disk="nbd://localhost:10809/myDisk:sync=none")
   """, discussion: """
   The disk attachment can be a:
 
@@ -117,12 +137,13 @@ 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 sonoma --disk=/dev/disk0
-  """, valueName: "path[:options]"))
+  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] = []
 
   #if arch(arm64)
@@ -141,7 +162,7 @@ struct Run: AsyncParsableCommand {
   #endif
   var rosettaTag: String?
 
-  @Option(help: ArgumentHelp("Additional directory shares with an optional read-only and mount tag options (e.g. --dir=\"~/src/build\" or --dir=\"~/src/sources:ro\")", discussion: """
+  @Option(help: ArgumentHelp("Additional directory shares with an optional read-only and mount tag options in the form of [name:]path[:options] (e.g. --dir=\"~/src/build\" or --dir=\"~/src/sources:ro\")", discussion: """
   Requires host to be macOS 13.0 (Ventura) or newer. macOS guests must be running macOS 13.0 (Ventura) or newer too.
 
   Options are comma-separated and are as follows:
@@ -153,9 +174,12 @@ struct Run: AsyncParsableCommand {
   Mount tag can be overridden by appending tag property to the directory share (e.g. --dir=\"~/src/build:tag=build\" or --dir=\"~/src/build:ro,tag=build\"). Then it can be mounted via "mount_virtiofs build ~/build" inside guest macOS and "mount -t virtiofs build ~/build" inside guest Linux.
 
   In case of passing multiple directories per mount tag it is required to prefix them with names e.g. --dir=\"build:~/src/build\" --dir=\"sources:~/src/sources:ro\". These names will be used as directory names under the mounting point inside guests. For the example above it will be "/Volumes/My Shared Files/build" and "/Volumes/My Shared Files/sources" respectively.
-  """, valueName: "[name:]path[:options]"))
+  """, valueName: "[name:]path[:options]"), completion: .directory)
   var dir: [String] = []
 
+  @Flag(help: ArgumentHelp("Enable nested virtualization if possible"))
+  var nested: Bool = false
+
   @Option(help: ArgumentHelp("""
   Use bridged networking instead of the default shared (NAT) networking \n(e.g. --net-bridged=en0 or --net-bridged=\"Wi-Fi\")
   """, discussion: """
@@ -163,17 +187,73 @@ struct Run: AsyncParsableCommand {
   """, valueName: "interface name"))
   var netBridged: [String] = []
 
-  @Flag(help: ArgumentHelp("Use software networking instead of the default shared (NAT) networking",
-                           discussion: "Learn how to configure Softnet for use with Tart here: https://github.com/cirruslabs/softnet"))
+  @Flag(help: ArgumentHelp("Use software networking provided by Softnet instead of the default shared (NAT) networking",
+                           discussion: """
+                           Softnet provides better network isolation and alleviates DHCP shortage on production systems. Tart invokes Softnet when this option is specified as a sub-process and communicates with it over socketpair(2).
+
+                           It is essentially a userspace packet filter which restricts the VM networking and prevents a class of security issues, such as ARP spoofing. By default, the VM will only be able to:
+
+                           * send traffic from its own MAC-address
+                           * send traffic from the IP-address assigned to it by the DHCP
+                           * send traffic to globally routable IPv4 addresses
+                           * send traffic to gateway IP of the vmnet bridge (this would normally be \"bridge100\" interface)
+                           * receive any incoming traffic
+
+                           In addition, Softnet tunes macOS built-in DHCP server to decrease its lease time from the default 86,400 seconds (one day) to 600 seconds (10 minutes). This is especially important when you use Tart to clone and run a lot of ephemeral VMs over a period of one day.
+
+                           More on Softnet here: https://github.com/cirruslabs/softnet
+                           """))
   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)", valueName: "comma-separated CIDRs"))
+  @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 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:
+
+  * EXTERNAL_PORT:INTERNAL_PORT — forward TCP traffic from the EXTERNAL_PORT on a host's egress interface (automatically detected and could be Wi-Fi, Ethernet and a VPN interface) to the INTERNAL_PORT on guest's IP (as reported by "tart ip")
+
+  Note that for the port forwarding to work correctly:
+
+  * the software in guest listening on INTERNAL_PORT should either listen on 0.0.0.0 or on an IP address assigned to that guest
+  * connection to the EXTERNAL_PORT should be performed from the local network that the host is attached to or from the internet, it's not possible to connect to that forwarded port from the host itself
+
+  Another thing to keep in mind is that regular Softnet restrictions will still apply even to port forwarding. So if you're planning to access your VM from local network, and your local network is 192.168.0.0/24, for example, then add --net-softnet-allow=192.168.0.0/24. If you only need port forwarding, to completely disable Softnet restrictions you can use --net-softnet-allow=0.0.0.0/0.
+
+  Implies --net-softnet.
+  """, valueName: "comma-separated port specifications"))
+  var netSoftnetExpose: String?
+
   @Flag(help: ArgumentHelp("Restrict network access to the host-only network"))
   var netHost: Bool = false
 
-  @Option(help: ArgumentHelp("Set the root disk options (e.g. --root-disk-opts=\"ro\" or --root-disk-opts=\"sync=none\")",
+  @Option(help: ArgumentHelp("Set the root disk options (e.g. --root-disk-opts=\"ro\" or --root-disk-opts=\"caching=cached,sync=none\")",
                              discussion: """
                              Options are comma-separated and are as follows:
 
@@ -184,6 +264,12 @@ struct Run: AsyncParsableCommand {
                              * sync=fsync — enable data synchronization with the permanent storage, but don't ensure that it was actually written (e.g. --root-disk-opts="sync=fsync")
 
                              * sync=full — enable data synchronization with the permanent storage and ensure that it was actually written (e.g. --root-disk-opts="sync=full")
+
+                             * caching=automatic — allows the virtualization framework to automatically determine whether to enable data caching
+
+                             * caching=cached — enabled data caching
+
+                             * caching=uncached — disables data caching
                              """, valueName: "options"))
   var rootDiskOpts: String = ""
 
@@ -198,12 +284,50 @@ struct Run: AsyncParsableCommand {
   #endif
   var captureSystemKeys: Bool = false
 
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp("Don't add trackpad as a pointing device on macOS VMs"))
+  #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")
     }
 
-    // check that not more than one network option is specified
+    // Automatically enable --net-softnet when any of its related options are specified
+    if netSoftnetAllow != nil || netSoftnetBlock != nil || netSoftnetExpose != nil || netSoftnetControlFd != nil {
+      netSoftnet = true
+    }
+
+    // Check that no more than one network option is specified
     var netFlags = 0
     if netBridged.count > 0 { netFlags += 1 }
     if netSoftnet { netFlags += 1 }
@@ -221,7 +345,15 @@ struct Run: AsyncParsableCommand {
       throw ValidationError("--captures-system-keys can only be used with the default VM view")
     }
 
-    let localStorage = VMStorageLocal()
+    if nested {
+      if #unavailable(macOS 15) {
+        throw ValidationError("Nested virtualization is supported on hosts starting with macOS 15 (Sequoia), and later.")
+      } else if !VZGenericPlatformConfiguration.isNestedVirtualizationSupported {
+        throw ValidationError("Nested virtualization is available for Mac with the M3 chip, and later.")
+      }
+    }
+
+    let localStorage = try VMStorageLocal()
     let vmDir = try localStorage.open(name)
     if try vmDir.state() == .Suspended {
       suspendable = true
@@ -232,11 +364,39 @@ struct Run: AsyncParsableCommand {
       if !(config.platform is PlatformSuspendable) {
         throw ValidationError("You can only suspend macOS VMs")
       }
-      if dir.count > 0 {
-        throw ValidationError("Suspending VMs with shared directories is not supported")
+
+      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 {
+        throw ValidationError("--no-trackpad can only be used with macOS VMs")
+      }
+    }
+
+    #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.")
@@ -245,10 +405,16 @@ 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
+    let vmConfig = try VMConfig(fromURL: vmDir.configURL)
+    if !vmConfig.diskFormat.isSupported {
+      throw ValidationError("Disk format '\(vmConfig.diskFormat.rawValue)' is not supported on this system.")
+    }
+
     let storageLock = try FileLock(lockURL: Config().tartHomeDir)
     try storageLock.lock()
     // check if there is a running VM with the same MAC address
@@ -262,7 +428,7 @@ struct Run: AsyncParsableCommand {
       try vmDir.regenerateMACAddress()
     }
 
-    if (netSoftnet || netHost) && isInteractiveSession() {
+    if netSoftnet && isInteractiveSession() {
       try Softnet.configureSUIDBitIfNeeded()
     }
 
@@ -287,16 +453,32 @@ 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,
+      nested: nested,
       audio: !noAudio,
       clipboard: !noClipboard,
-      sync: VZDiskImageSynchronizationMode(diskOptions.syncModeRaw)
+      noUSBAccessories: noUSBAccessories,
+      sync: VZDiskImageSynchronizationMode(diskOptions.syncModeRaw),
+      caching: VZDiskImageCachingMode(diskOptions.cachingModeRaw),
+      noTrackpad: noTrackpad,
+      noPointer: noPointer,
+      noKeyboard: noKeyboard
     )
 
     let vncImpl: VNC? = try {
@@ -346,7 +528,39 @@ struct Run: AsyncParsableCommand {
           }
         #endif
 
-        try await vm!.start(recovery: recovery, resume: resume)
+        do {
+          #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 = ""
+
+            do {
+              let runningVMs: [String] = try localStorage.list().compactMap { (name, vmDir) in
+                if try !vmDir.running() {
+                  return nil
+                }
+
+                return name
+              }
+
+              if !runningVMs.isEmpty {
+                let runningVMsJoined = runningVMs.joined(separator: ", ")
+
+                hint = " (other running VMs: \(runningVMsJoined))"
+              }
+            } catch {
+              // we can't provide any hint
+            }
+
+            throw RuntimeError.VirtualMachineLimitExceeded(hint)
+          }
+
+          throw error
+        }
 
         if let vncImpl = vncImpl {
           let vncURL = try await vncImpl.waitForURL(netBridged: !netBridged.isEmpty)
@@ -359,20 +573,29 @@ struct Run: AsyncParsableCommand {
           }
         }
 
+        if #available(macOS 14, *) {
+          let controlSocket = try await ControlSocket(vmDir.controlSocketURL)
+
+          ErrorReportingTask("Failed to run control socket") {
+            try await controlSocket.run()
+          }
+        }
+
         try await vm!.run()
 
         if let vncImpl = vncImpl {
           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)
       }
     }
@@ -406,12 +629,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)
         }
       }
@@ -423,7 +648,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()
       }
@@ -432,8 +657,10 @@ struct Run: AsyncParsableCommand {
 
     let useVNCWithoutGraphics = (vnc || vncExperimental) && !graphics
     if noGraphics || useVNCWithoutGraphics {
-      // enter the main even loop, without bringing up any UI,
-      // and just wait for the VM to exit.
+      // Enter the main event loop without bringing up any UI,
+      // waiting for the VM to exit.
+      NSApplication.shared.setActivationPolicy(.prohibited)
+
       NSApplication.shared.run()
     } else {
       runUI(suspendable, captureSystemKeys)
@@ -461,16 +688,26 @@ struct Run: AsyncParsableCommand {
       softnetExtraArguments += ["--allow", netSoftnetAllow]
     }
 
+    if let netSoftnetBlock = netSoftnetBlock {
+      softnetExtraArguments += ["--block", netSoftnetBlock]
+    }
+
+    if let netSoftnetExpose = netSoftnetExpose {
+      softnetExtraArguments += ["--expose", netSoftnetExpose]
+    }
+
     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)
+      guard #available(macOS 26, *) else {
+        throw ValidationError("--net-host requires macOS 26 (Tahoe) or newer")
+      }
 
-      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: ["--vm-net-type", "host"] + softnetExtraArguments)
+      return try NetworkHost()
     }
 
     if netBridged.count > 0 {
@@ -503,9 +740,9 @@ struct Run: AsyncParsableCommand {
     }
   }
 
-  func additionalDiskAttachments() throws -> [VZStorageDeviceConfiguration] {
+  func additionalDisks() throws -> [AdditionalDisk] {
     try disk.map {
-      try AdditionalDisk(parseFrom: $0).configuration
+      try AdditionalDisk(parseFrom: $0)
     }
   }
 
@@ -585,11 +822,16 @@ 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
 
-  @NSApplicationDelegateAdaptor private var appDelegate: MinimalMenuAppDelegate
+  @NSApplicationDelegateAdaptor private var appDelegate: AppDelegate
 
   var body: some Scene {
     WindowGroup(vm!.name) {
@@ -625,13 +867,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) {
@@ -645,13 +887,8 @@ struct MainApp: App {
   }
 }
 
-// The only way to fully remove Edit menu item.
-class MinimalMenuAppDelegate: NSObject, NSApplicationDelegate, ObservableObject {
-  let indexOfEditMenu = 2
-
+class AppDelegate: NSObject, NSApplicationDelegate, ObservableObject {
   func applicationDidFinishLaunching(_ : Notification) {
-    NSApplication.shared.mainMenu?.removeItem(at: indexOfEditMenu)
-
     let nsApp = NSApplication.shared
     nsApp.setActivationPolicy(.regular)
     nsApp.activate(ignoringOtherApps: true)
@@ -709,12 +946,12 @@ struct VMView: NSViewRepresentable {
 
     machineView.capturesSystemKeys = capturesSystemKeys
 
-    // Enable automatic display reconfiguration
-    // for guests that support it
+    // If not specified, enable automatic display
+    // reconfiguration for guests that support it
     //
     // This is disabled for Linux because of poor HiDPI
     // support, which manifests in fonts being too small
-    if #available(macOS 14.0, *), vm.config.os != .linux {
+    if #available(macOS 14.0, *), vm.config.displayRefit ?? (vm.config.os != .linux) {
       machineView.automaticallyReconfiguresDisplay = true
     }
 
@@ -728,14 +965,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) = Self.parseOptions(parseFrom)
+    let (diskPath, readOnly, syncModeRaw, cachingModeRaw) = Self.parseOptions(parseFrom)
 
-    self.configuration = try Self.craft(diskPath, readOnly: readOnly, syncModeRaw: syncModeRaw)
+    self = try Self.craft(
+      diskPath,
+      readOnly: readOnly,
+      syncModeRaw: syncModeRaw,
+      cachingModeRaw: cachingModeRaw
+    )
   }
 
-  static func craft(_ diskPath: String, readOnly diskReadOnly: Bool, syncModeRaw: 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)) {
@@ -750,7 +1005,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,
@@ -781,13 +1036,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.
@@ -800,7 +1079,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),
@@ -812,14 +1091,14 @@ struct AdditionalDisk {
     let diskImageAttachment = try VZDiskImageStorageDeviceAttachment(
       url: diskFileURL,
       readOnly: diskReadOnly,
-      cachingMode: .automatic,
+      cachingMode: try VZDiskImageCachingMode(cachingModeRaw) ?? .automatic,
       synchronizationMode: try VZDiskImageSynchronizationMode(syncModeRaw)
     )
 
-    return VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment)
+    return AdditionalDisk(configuration: VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment))
   }
 
-  static func parseOptions(_ parseFrom: String) -> (String, Bool, String) {
+  static func parseOptions(_ parseFrom: String) -> (String, Bool, String, String) {
     var arguments = parseFrom.split(separator: ":")
 
     let options = DiskOptions(String(arguments.last!))
@@ -827,13 +1106,14 @@ struct AdditionalDisk {
       arguments.removeLast()
     }
 
-    return (arguments.joined(separator: ":"), options.readOnly, options.syncModeRaw)
+    return (arguments.joined(separator: ":"), options.readOnly, options.syncModeRaw, options.cachingModeRaw)
   }
 }
 
 struct DiskOptions {
   var readOnly: Bool = false
   var syncModeRaw: String = ""
+  var cachingModeRaw: String = ""
   var foundAtLeastOneOption: Bool = false
 
   init(_ parseFrom: String) {
@@ -847,6 +1127,9 @@ struct DiskOptions {
       case option.hasPrefix("sync="):
         self.syncModeRaw = String(option.dropFirst("sync=".count))
         self.foundAtLeastOneOption = true
+      case option.hasPrefix("caching="):
+        self.cachingModeRaw = String(option.dropFirst("caching=".count))
+        self.foundAtLeastOneOption = true
       default:
         continue
       }
@@ -854,6 +1137,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
@@ -970,7 +1328,7 @@ struct DirectoryShare {
     process.standardInput = inPipe
     process.launch()
 
-    inPipe.fileHandleForWriting.write(response!.data)
+    try inPipe.fileHandleForWriting.write(contentsOf: response!.data)
     try inPipe.fileHandleForWriting.close()
     process.waitUntilExit()
 

Sources/tart/Commands/Set.swift

@@ -14,9 +14,12 @@ 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"))
+  var displayRefit: Bool? = nil
+
   @Flag(help: ArgumentHelp("Generate a new random MAC address for the VM."))
   var randomMAC: Bool = false
 
@@ -30,20 +33,20 @@ struct Set: AsyncParsableCommand {
 
   @Option(help: ArgumentHelp("Resize the VMs disk to the specified size in GB (note that the disk size can only be increased to avoid losing data)",
                              discussion: """
-                             Disk resizing works on most cloud-ready Linux distributions out-of-the box (e.g. Ubuntu Cloud Images
-                             have the \"cloud-initramfs-growroot\" package installed that runs on boot) and on the rest of the
-                             distributions by running the \"growpart\" or \"resize2fs\" commands.
-
-                             For macOS, however, things are a bit more complicated: you need to remove the recovery partition
-                             first and then run various \"diskutil\" commands, see Tart's packer plugin source code for more
-                             details[1].
-
-                             [1]: https://github.com/cirruslabs/packer-plugin-tart/blob/main/builder/tart/step_disk_resize.go
+                             See https://tart.run/faq/#disk-resizing for more details.
                              """))
   var diskSize: UInt16?
 
   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 {
@@ -61,15 +64,17 @@ struct Set: AsyncParsableCommand {
       if (display.height > 0) {
         vmConfig.display.height = display.height
       }
+      vmConfig.display.unit = display.unit
     }
 
+    vmConfig.displayRefit = displayRefit
+
     if randomMAC {
       vmConfig.macAddress = VZMACAddress.randomLocallyAdministered()
     }
 
     #if arch(arm64)
-      if randomSerial {
-        let oldPlatform = vmConfig.platform as! Darwin
+      if randomSerial, let oldPlatform = vmConfig.platform as? Darwin {
         vmConfig.platform = Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: oldPlatform.hardwareModel)
       }
     #endif
@@ -92,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

@@ -0,0 +1,146 @@
+import Foundation
+import Darwin
+import System
+import Virtualization
+import Network
+import os.log
+import NIO
+import NIOPosix
+
+@available(macOS 14, *)
+class ControlSocket {
+  typealias ServerChannel = NIOAsyncChannel<NIOAsyncChannel<ByteBuffer, ByteBuffer>, Never>
+
+  let controlSocketURL: URL
+  let vmPort: UInt32
+  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) async throws {
+    self.controlSocketURL = controlSocketURL
+    self.vmPort = vmPort
+    let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    self.eventLoopGroup = eventLoopGroup
+
+    // 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(at: 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.absoluteURL.path(percentEncoded: false))
+    }
+
+    do {
+      self.serverChannel = try await ServerBootstrap(group: eventLoopGroup)
+        .serverChannelInitializer { channel in
+          channel.pipeline.addHandler(
+            ControlSocketAcceptErrorHandler(),
+            name: "ControlSocketAcceptErrorHandler"
+          )
+        }
+        .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 {
+          group.addTask {
+            try await self.handleClient(clientChannel)
+          }
+        }
+      }
+    }
+  }
+
+  func handleClient(_ clientChannel: NIOAsyncChannel<ByteBuffer, ByteBuffer>) async throws {
+    self.logger.info("received new control socket connection from a client")
+
+    try await clientChannel.executeThenClose { clientInbound, clientOutbound in
+      self.logger.info("dialing to VM on port \(self.vmPort)...")
+
+      do {
+        guard let vmConnection = try await vm?.connect(toPort: self.vmPort) else {
+          throw RuntimeError.VMSocketFailed(self.vmPort, "VM is not running")
+        }
+
+        self.logger.info("running control socket proxy")
+
+        // Duplicate the connection's file descriptor
+        //
+        // This way VZVirtioSocketConnection and NIO won't race to close the same descriptor,
+        // which may result in "tart run" crashing because of NIO's fatal assertion on EBADF.
+        let vmSocket = try duplicateAndCloseConnection(vmConnection)
+
+        let vmChannel = try await ClientBootstrap(group: eventLoopGroup).withConnectedSocket(vmSocket) { childChannel in
+          childChannel.eventLoop.makeCompletedFuture {
+            try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+              wrappingChannelSynchronously: childChannel
+            )
+          }
+        }
+
+        try await vmChannel.executeThenClose { (vmInbound, vmOutbound) in
+          try await withThrowingDiscardingTaskGroup { group in
+            // Proxy data from a client (e.g. "tart exec") to a VM
+            group.addTask {
+              for try await message in clientInbound {
+                try await vmOutbound.write(message)
+              }
+            }
+
+            // Proxy data from a VM to a client (e.g. "tart exec")
+            group.addTask {
+              for try await message in vmInbound {
+                try await clientOutbound.write(message)
+              }
+            }
+          }
+        }
+
+        self.logger.info("control socket client disconnected")
+      } catch (let error) {
+        self.logger.error("control socket connection failed: \(error)")
+      }
+    }
+  }
+
+  private func duplicateAndCloseConnection(_ connection: VZVirtioSocketConnection) throws -> CInt {
+    defer { connection.close() }
+
+    let fd = fcntl(connection.fileDescriptor, F_DUPFD_CLOEXEC, 0)
+    guard fd >= 0 else {
+      throw Errno(rawValue: errno)
+    }
+
+    return fd
+  }
+}
+
+private final class ControlSocketAcceptErrorHandler: ChannelInboundHandler {
+  typealias InboundIn = Channel
+  typealias InboundOut = Channel
+
+  func errorCaught(context: ChannelHandlerContext, error: Error) {
+    if error is NIOFcntlFailedError {
+      context.channel.read()
+    } else {
+      context.fireErrorCaught(error)
+    }
+  }
+}

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) {
@@ -36,12 +38,17 @@ class DockerConfigCredentialsProvider: CredentialsProvider {
 
     process.launch()
 
-    inPipe.fileHandleForWriting.write("\(host)\n".data(using: .utf8)!)
+    do {
+      try inPipe.fileHandleForWriting.write(contentsOf: "\(host)\n".data(using: .utf8)!)
+    } catch {
+      throw CredentialsProviderError.Failed(message: "Failed to write host to Docker helper!")
+    }
     inPipe.fileHandleForWriting.closeFile()
 
+    let outputData = try outPipe.fileHandleForReading.readToEnd()
+
     process.waitUntilExit()
 
-    let outputData = try outPipe.fileHandleForReading.readToEnd()
     if !(process.terminationReason == .exit && process.terminationStatus == 0) {
       if let outputData = outputData {
         print(String(decoding: outputData, as: UTF8.self))

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

@@ -0,0 +1,43 @@
+import Foundation
+import ArgumentParser
+
+enum DiskImageFormat: String, CaseIterable, Codable {
+  case raw = "raw"
+  case asif = "asif"
+
+  var displayName: String {
+    switch self {
+    case .raw:
+      return "RAW"
+    case .asif:
+      return "ASIF (Apple Sparse Image Format)"
+    }
+  }
+
+
+  /// Check if the format is supported on the current system
+  var isSupported: Bool {
+    switch self {
+    case .raw:
+      return true
+    case .asif:
+      if #available(macOS 26, *) {
+        return true
+      } else {
+        return false
+      }
+    }
+  }
+
+
+}
+
+extension DiskImageFormat: ExpressibleByArgument {
+  init?(argument: String) {
+    self.init(rawValue: argument.lowercased())
+  }
+
+  static var allValueStrings: [String] {
+    return allCases.map { $0.rawValue }
+  }
+}

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/Fetcher.swift

@@ -1,69 +1,6 @@
 import Foundation
-import AsyncAlgorithms
 
-fileprivate let urlSession = createURLSession()
-
-class DownloadDelegate: NSObject, URLSessionTaskDelegate {
-  let progress: Progress
-  init(_ progress: Progress) throws {
-    self.progress = progress
-  }
-
-  func urlSession(_ session: URLSession, didCreateTask task: URLSessionTask) {
-    self.progress.addChild(task.progress, withPendingUnitCount: self.progress.totalUnitCount)
-  }
-}
-
-class Fetcher {
-  static func fetch(_ request: URLRequest, viaFile: Bool = false, progress: Progress? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    let delegate = progress != nil ? try DownloadDelegate(progress!) : nil
-
-    if viaFile {
-      return try await fetchViaFile(request, delegate: delegate)
-    }
-
-    return try await fetchViaMemory(request, delegate: delegate)
-  }
-
-  private static func fetchViaMemory(_ request: URLRequest, delegate: URLSessionTaskDelegate? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    let dataCh = AsyncThrowingChannel<Data, Error>()
-
-    let (data, response) = try await urlSession.data(for: request, delegate: delegate)
-
-    Task {
-      await dataCh.send(data)
-
-      dataCh.finish()
-    }
-
-    return (dataCh, response as! HTTPURLResponse)
-  }
-
-  private static func fetchViaFile(_ request: URLRequest, delegate: URLSessionTaskDelegate? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    let dataCh = AsyncThrowingChannel<Data, Error>()
-
-    let (fileURL, response) = try await urlSession.download(for: request, delegate: delegate)
-
-    // Acquire a handle to the downloaded file and then remove it.
-    //
-    // This keeps a working reference to that file, yet we don't
-    // have to deal with the cleanup any more.
-    let mappedFile = try Data(contentsOf: fileURL, options: [.alwaysMapped])
-    try FileManager.default.removeItem(at: fileURL)
-
-    Task {
-      for chunk in (0 ..< mappedFile.count).chunks(ofCount: 64 * 1024 * 1024) {
-        await dataCh.send(mappedFile.subdata(in: chunk))
-      }
-
-      dataCh.finish()
-    }
-
-    return (dataCh, response as! HTTPURLResponse)
-  }
-}
-
-fileprivate func createURLSession() -> URLSession {
+fileprivate var urlSession: URLSession = {
   let config = URLSessionConfiguration.default
 
   // Harbor expects a CSRF token to be present if the HTTP client
@@ -77,4 +14,84 @@ fileprivate func createURLSession() -> URLSession {
   config.httpShouldSetCookies = false
 
   return URLSession(configuration: config)
+}()
+
+class Fetcher {
+  static func fetch(_ request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
+    let task = urlSession.dataTask(with: request)
+
+    let delegate = Delegate()
+    task.delegate = delegate
+
+    let stream = AsyncThrowingStream<Data, Error> { continuation in
+      delegate.streamContinuation = continuation
+    }
+
+    let response = try await withCheckedThrowingContinuation { continuation in
+      delegate.responseContinuation = continuation
+      task.resume()
+    }
+
+    return (stream, response as! HTTPURLResponse)
+  }
+}
+
+fileprivate class Delegate: NSObject, URLSessionDataDelegate {
+  var responseContinuation: CheckedContinuation<URLResponse, Error>?
+  var streamContinuation: AsyncThrowingStream<Data, Error>.Continuation?
+
+  private var buffer: Data = Data()
+  private let bufferFlushSize = 16 * 1024 * 1024
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive response: URLResponse,
+    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+  ) {
+    // Soft-limit for the maximum buffer capacity
+    let capacity = min(response.expectedContentLength, Int64(bufferFlushSize))
+
+    // Pre-initialize buffer as we now know the capacity
+    buffer = Data(capacity: Int(capacity))
+
+    responseContinuation?.resume(returning: response)
+    responseContinuation = nil
+    completionHandler(.allow)
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive data: Data
+  ) {
+    buffer.append(data)
+
+    if buffer.count >= bufferFlushSize {
+      streamContinuation?.yield(buffer)
+      buffer.removeAll(keepingCapacity: true)
+    }
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    didCompleteWithError error: Error?
+  ) {
+    if let error = error {
+      responseContinuation?.resume(throwing: error)
+      responseContinuation = nil
+
+      streamContinuation?.finish(throwing: error)
+      streamContinuation = nil
+    } else {
+      if !buffer.isEmpty {
+        streamContinuation?.yield(buffer)
+        buffer.removeAll(keepingCapacity: true)
+      }
+
+      streamContinuation?.finish()
+      streamContinuation = nil
+    }
+  }
 }

Sources/tart/Formatter/HumanReadableByteCount.swift

@@ -0,0 +1,30 @@
+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 = byteCount.map(encodedAs)
+  }
+
+  var description: String {
+    guard let byteCount else {
+      return "-"
+    }
+
+    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/ARPCache.swift

@@ -52,6 +52,11 @@ struct ARPCache {
     process.standardInput = FileHandle.nullDevice
 
     try process.run()
+
+    guard let arpCommandOutput = try pipe.fileHandleForReading.readToEnd() else {
+      throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
+    }
+
     process.waitUntilExit()
 
     if !(process.terminationReason == .exit && process.terminationStatus == 0) {
@@ -60,10 +65,6 @@ struct ARPCache {
         terminationStatus: process.terminationStatus)
     }
 
-    guard let arpCommandOutput = try pipe.fileHandleForReading.readToEnd() else {
-      throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
-    }
-
     self.arpCommandOutput = arpCommandOutput
   }
 

Sources/tart/MACAddressResolver/AgentResolver.swift

@@ -0,0 +1,28 @@
+import Foundation
+import Network
+import GRPC
+import Cirruslabs_TartGuestAgent_Apple_Swift
+import Cirruslabs_TartGuestAgent_Grpc_Swift
+
+class AgentResolver {
+  static func ResolveIP(_ controlSocketPath: String) async throws -> IPv4Address? {
+    do {
+      return try await resolveIP(controlSocketPath)
+    } catch is GRPCConnectionPoolError {
+      return nil
+    }
+  }
+
+  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)
+    }
+  }
+}

Sources/tart/MACAddressResolver/Bootptab.swift

@@ -0,0 +1,70 @@
+import Foundation
+import Network
+
+struct Bootptab {
+  private var reservations: [MACAddress: Swift.Set<IPv4Address>] = [:]
+
+  init?(_ fromURL: URL = URL(fileURLWithPath: "/etc/bootptab")) throws {
+    let contents: String
+
+    do {
+      contents = try String(contentsOf: fromURL, encoding: .utf8)
+    } catch {
+      if error.isFileNotFound() {
+        return nil
+      }
+
+      throw error
+    }
+
+    for line in contents.split(whereSeparator: \.isNewline) {
+      // Skip comment lines
+      guard !line.hasPrefix("#") else {
+        continue
+      }
+
+      let fields = line.split(whereSeparator: \.isWhitespace)
+
+      // Skip lines that don't look like reservation fields
+      guard fields.count >= 4 else {
+        continue
+      }
+
+      // Assign reservation fields
+      let hardwareType = fields[1]
+      let hardwareAddress = fields[2]
+      let ipAddress = fields[3]
+
+      // Skip non-Ethernet reservations
+      guard hardwareType == "1" else {
+        continue
+      }
+
+      // Skip malformed MAC addresses
+      guard let mac = MACAddress(fromString: String(hardwareAddress)) else {
+        continue
+      }
+
+      // Skip malformed IPv4 addresses
+      guard let ip = IPv4Address(String(ipAddress)) else {
+        continue
+      }
+
+      reservations[mac, default: []].insert(ip)
+    }
+  }
+
+  func ResolveMACAddress(macAddress: MACAddress) throws -> IPv4Address? {
+    guard let addresses = reservations[macAddress] else {
+      return nil
+    }
+
+    if addresses.count > 1 {
+      let addresses = addresses.map { $0.debugDescription }.sorted().joined(separator: ", ")
+
+      throw RuntimeError.Generic("multiple DHCP reservations in /etc/bootptab for \(macAddress): \(addresses)")
+    }
+
+    return addresses.first
+  }
+}

Sources/tart/MACAddressResolver/MACAddress.swift

@@ -11,7 +11,11 @@ struct MACAddress: Equatable, Hashable, CustomStringConvertible {
     }
 
     for (index, component) in components.enumerated() {
-      mac[index] = UInt8(component, radix: 16)!
+      guard let byte = UInt8(component, radix: 16) else {
+        return nil
+      }
+
+      mac[index] = byte
     }
   }
 

Sources/tart/Network/NetworkHost.swift

@@ -0,0 +1,61 @@
+import Foundation
+import Semaphore
+import Virtualization
+import vmnet
+
+@available(macOS 26, *)
+class NetworkHost: Network {
+  private let attachment: VZNetworkDeviceAttachment
+
+  init() throws {
+    var status = vmnet_return_t.VMNET_SUCCESS
+    guard let configuration = vmnet_network_configuration_create(.VMNET_HOST_MODE, &status) else {
+      throw RuntimeError.Generic("Failed to create a vmnet configuration for host-only networking: \(status)")
+    }
+    defer { Unmanaged<CFTypeRef>.fromOpaque(UnsafeRawPointer(configuration)).release() }
+
+    guard let network = vmnet_network_create(configuration, &status) else {
+      var message = "Failed to create a vmnet network for host-only networking: \(status)"
+
+      if status == .VMNET_NOT_AUTHORIZED {
+        message += ". Creating a vmnet network requires root privileges or a properly signed app with the com.apple.vm.networking entitlement."
+      }
+
+      throw RuntimeError.Generic(message)
+    }
+    defer { Unmanaged<CFTypeRef>.fromOpaque(UnsafeRawPointer(network)).release() }
+
+    attachment = VZVmnetNetworkDeviceAttachment(network: network)
+  }
+
+  func attachments() -> [VZNetworkDeviceAttachment] {
+    [attachment]
+  }
+
+  func run(_ sema: AsyncSemaphore) throws {
+    // no-op, only used for Softnet
+  }
+
+  func stop() async throws {
+    // no-op, only used for Softnet
+  }
+}
+
+extension vmnet_return_t: @retroactive CustomStringConvertible {
+  public var description: String {
+    switch self {
+    case .VMNET_SUCCESS: return "successfully completed"
+    case .VMNET_FAILURE: return "general failure"
+    case .VMNET_MEM_FAILURE: return "memory allocation failure"
+    case .VMNET_INVALID_ARGUMENT: return "invalid argument specified"
+    case .VMNET_SETUP_INCOMPLETE: return "interface setup is not complete"
+    case .VMNET_INVALID_ACCESS: return "permission denied"
+    case .VMNET_PACKET_TOO_BIG: return "packet size larger than MTU"
+    case .VMNET_BUFFER_EXHAUSTED: return "buffers exhausted in kernel"
+    case .VMNET_TOO_MANY_PACKETS: return "packet count exceeds limit"
+    case .VMNET_SHARING_SERVICE_BUSY: return "vmnet interface cannot be started as conflicting sharing service is in use"
+    case .VMNET_NOT_AUTHORIZED: return "the operation could not be completed due to missing authorization"
+    @unknown default: return "unknown vmnet status (\(rawValue))"
+    }
+  }
+}

Sources/tart/Network/Softnet.swift

@@ -11,12 +11,22 @@ enum SoftnetError: Error {
 
 class Softnet: Network {
   private let process = Process()
+  private var controlFileHandle: FileHandle?
   private var monitorTask: Task<Void, Error>? = nil
   private let monitorTaskFinished = ManagedAtomic<Bool>(false)
 
   let vmFD: Int32
 
-  init(vmMACAddress: String, extraArguments: [String] = []) throws {
+  init(vmMACAddress: String, extraArguments: [String] = [], controlFD: Int32? = nil) throws {
+    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 +43,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 +94,8 @@ class Softnet: Network {
   }
 
   func run(_ sema: AsyncSemaphore) throws {
+    defer { try? controlFileHandle?.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 pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache?) async throws
+  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) 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 {
-        disk.write(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

@@ -7,7 +7,29 @@ class DiskV2: Disk {
   private static let bufferSizeBytes = 4 * 1024 * 1024
   private static let layerLimitBytes = 512 * 1024 * 1024
 
-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer] {
+  // A zero chunk for faster than byte-by-byte comparisons
+  //
+  // Assumes that the other Data(...) is equal in size, but it's fine to get a false-negative
+  // on the last block since it costs only 4 MiB of excess data per 512 MiB layer.
+  //
+  // Some simple benchmarks ("sync && sudo purge" command was used to negate the disk caching effects):
+  // +--------------------------------------+---------------------------------------------------+
+  // | Operation                            | time(1) result                                    |
+  // +--------------------------------------+---------------------------------------------------+
+  // | Data(...) == zeroChunk               | 2.16s user 11.71s system 73% cpu 18.928 total     |
+  // | Data(...).contains(where: {$0 != 0}) | 603.68s user 12.97s system 99% cpu 10:22.85 total |
+  // +--------------------------------------+---------------------------------------------------+
+  private static let holeGranularityBytes = 4 * 1024 * 1024
+  private static let zeroChunk = Data(count: holeGranularityBytes)
+
+  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
@@ -29,7 +51,7 @@ class DiskV2: Disk {
           let compressedData = try (data as NSData).compressed(using: .lz4) as Data
           let compressedDataDigest = Digest.hash(compressedData)
 
-          try await retry(maxAttempts: 5, backoff: .exponentialWithFullJitter(baseDelay: .seconds(5), maxDelay: .seconds(60))) {
+          try await retry(maxAttempts: 5) {
             if try await !registry.blobExists(compressedDataDigest) {
               _ = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb, digest: compressedDataDigest)
             }
@@ -48,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),
@@ -69,12 +91,12 @@ class DiskV2: Disk {
     }
   }
 
-  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil) async throws {
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil, deduplicate: Bool = false) async throws {
     // Support resumable pulls
     let pullResumed = FileManager.default.fileExists(atPath: diskURL.path)
 
     if !pullResumed {
-      if let localLayerCache = localLayerCache {
+      if deduplicate, let localLayerCache = localLayerCache {
         // Clone the local layer cache's disk and use it as a base, potentially
         // reducing the space usage since some blocks won't be written at all
         try FileManager.default.copyItem(at: localLayerCache.diskURL, to: diskURL)
@@ -151,26 +173,31 @@ class DiskV2: Disk {
 
           // Also open the disk file for reading and verifying
           // its contents in case the local layer cache is used
-          let rdisk: FileHandle? = if localLayerCache != nil {
+          let rdisk: FileHandle? = if deduplicate && localLayerCache != nil {
             try FileHandle(forReadingFrom: diskURL)
           } else {
             nil
           }
 
-          // Check if we already have this layer contents in the local layer cache
-          if let localLayerCache = localLayerCache, let localLayerInfo = localLayerCache.findInfo(digest: diskLayer.digest, offsetHint: diskWritingOffset) {
-            // indicates that the locally cloned disk image has the same content at the given offset
-            let localHit = localLayerInfo.uncompressedContentDigest == uncompressedLayerContentDigest
-              && localLayerInfo.range.lowerBound == diskWritingOffset
-            // doesn't seem that localHit can ever be false if the localLayerCache is not nil
-            // but let's just add extra safety here and check it
-            if !localHit {
+          // Check if we already have this layer contents in the local layer cache,
+          // or perhaps even on the cloned disk (when the deduplication is enabled)
+          if let localLayerCache = localLayerCache,
+             let localLayerInfo = localLayerCache.findInfo(digest: diskLayer.digest, offsetHint: diskWritingOffset),
+             localLayerInfo.uncompressedContentDigest == uncompressedLayerContentDigest {
+            if deduplicate && localLayerInfo.range.lowerBound == diskWritingOffset {
+              // Do nothing, because the data is already on the disk that we've inherited from
+            } else {
               // Fulfil the layer contents from the local blob cache
               let data = localLayerCache.subdata(localLayerInfo.range)
               _ = try zeroSkippingWrite(disk, rdisk, fsBlockSize, diskWritingOffset, data)
             }
+
             try disk.close()
 
+            if let rdisk = rdisk {
+              try rdisk.close()
+            }
+
             // Update the progress
             progress.completedUnitCount += Int64(diskLayer.size)
 
@@ -188,16 +215,35 @@ class DiskV2: Disk {
             diskWritingOffset = try zeroSkippingWrite(disk, rdisk, fsBlockSize, diskWritingOffset, data)
           }
 
-          try await registry.pullBlob(diskLayer.digest) { data in
-            try filter.write(data)
+          var rangeStart: Int64 = 0
 
-            // Update the progress
-            progress.completedUnitCount += Int64(data.count)
+          try await retry(maxAttempts: 5) {
+            try await registry.pullBlob(diskLayer.digest, rangeStart: rangeStart) { data in
+              try filter.write(data)
+
+              // Update the progress
+              progress.completedUnitCount += Int64(data.count)
+
+              // Update the current range start
+              rangeStart += Int64(data.count)
+            }
+          } recoverFromFailure: { error in
+            if error is URLError {
+              print("Error pulling disk layer \(index + 1): \"\(error.localizedDescription)\", attempting to re-try...")
+
+              return .retry
+            }
+
+            return .throw
           }
 
           try filter.finalize()
 
           try disk.close()
+
+          if let rdisk = rdisk {
+            try rdisk.close()
+          }
         }
 
         globalDiskWritingOffset += uncompressedLayerSize
@@ -206,22 +252,6 @@ class DiskV2: Disk {
   }
 
   private static func zeroSkippingWrite(_ disk: FileHandle, _ rdisk: FileHandle?, _ fsBlockSize: UInt64, _ offset: UInt64, _ data: Data) throws -> UInt64 {
-    let holeGranularityBytes = 64 * 1024
-
-    // A zero chunk for faster than byte-by-byte comparisons
-    //
-    // Assumes that the other Data(...) is equal in size, but it's fine to get a false-negative
-    // on the last block since it costs only 64 KiB of excess data per 500 MB layer.
-    //
-    // Some simple benchmarks ("sync && sudo purge" command was used to negate the disk caching effects):
-    // +--------------------------------------+---------------------------------------------------+
-    // | Operation                            | time(1) result                                    |
-    // +--------------------------------------+---------------------------------------------------+
-    // | Data(...) == zeroChunk               | 2.16s user 11.71s system 73% cpu 18.928 total     |
-    // | Data(...).contains(where: {$0 != 0}) | 603.68s user 12.97s system 99% cpu 10:22.85 total |
-    // +--------------------------------------+---------------------------------------------------+
-    let zeroChunk = Data(count: holeGranularityBytes)
-
     var offset = offset
 
     for chunk in data.chunks(ofCount: holeGranularityBytes) {
@@ -245,7 +275,7 @@ class DiskV2: Disk {
 
           if chunk != actualContentsOnDisk {
             try disk.seek(toOffset: offset)
-            disk.write(chunk)
+            try disk.write(contentsOf: chunk)
           }
         }
 
@@ -259,7 +289,7 @@ class DiskV2: Disk {
       // is zeroed via truncate(2)
       if chunk != zeroChunk {
         try disk.seek(toOffset: offset)
-        disk.write(chunk)
+        try disk.write(contentsOf: chunk)
       }
 
       offset += UInt64(chunk.count)

Sources/tart/OCI/Manifest.swift

@@ -6,17 +6,66 @@ 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"
 
 // 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
@@ -61,11 +110,126 @@ 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 {
   var architecture: Architecture = .arm64
   var os: OS = .darwin
+  var config: ConfigContainer?
+
+  struct ConfigContainer: Codable {
+    var Labels: [String: String]?
+  }
 
   func toJSON() throws -> Data {
     try Config.jsonEncoder().encode(self)
@@ -114,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/Reference/Generated/ReferenceBaseListener.swift

@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 
 import Antlr4
 

Sources/tart/OCI/Reference/Generated/ReferenceLexer.swift

@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4
 
 open class ReferenceLexer: Lexer {
@@ -49,7 +49,7 @@ open class ReferenceLexer: Lexer {
 
 	public
 	required init(_ input: CharStream) {
-	    RuntimeMetaData.checkVersion("4.11.1", RuntimeMetaData.VERSION)
+	    RuntimeMetaData.checkVersion("4.13.2", RuntimeMetaData.VERSION)
 		super.init(input)
 		_interp = LexerATNSimulator(self, ReferenceLexer._ATN, ReferenceLexer._decisionToDFA, ReferenceLexer._sharedContextCache)
 	}

Sources/tart/OCI/Reference/Generated/ReferenceListener.swift

@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4
 
 /**

Sources/tart/OCI/Reference/Generated/ReferenceParser.swift

@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4
 
 open class ReferenceParser: Parser {
@@ -41,7 +41,7 @@ open class ReferenceParser: Parser {
 	static let VOCABULARY = Vocabulary(_LITERAL_NAMES, _SYMBOLIC_NAMES)
 
 	override open
-	func getGrammarFileName() -> String { return "java-escape" }
+	func getGrammarFileName() -> String { return "Reference.g4" }
 
 	override open
 	func getRuleNames() -> [String] { return ReferenceParser.ruleNames }
@@ -60,7 +60,7 @@ open class ReferenceParser: Parser {
 
 	override public
 	init(_ input:TokenStream) throws {
-	    RuntimeMetaData.checkVersion("4.11.1", RuntimeMetaData.VERSION)
+	    RuntimeMetaData.checkVersion("4.13.2", RuntimeMetaData.VERSION)
 		try super.init(input)
 		_interp = ParserATNSimulator(self,ReferenceParser._ATN,ReferenceParser._decisionToDFA, ReferenceParser._sharedContextCache)
 	}
@@ -460,7 +460,7 @@ open class ReferenceParser: Parser {
 		 		setState(63)
 		 		try _errHandler.sync(self)
 		 		_la = try _input.LA(1)
-		 		if ((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0) {
+		 		if (((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
 		 			setState(62)
 		 			try separator()
 
@@ -611,7 +611,7 @@ open class ReferenceParser: Parser {
 		 	setState(84)
 		 	try _errHandler.sync(self)
 		 	_la = try _input.LA(1)
-		 	while ((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0) {
+		 	while (((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
 		 		setState(79)
 		 		try separator()
 		 		setState(80)
@@ -664,7 +664,7 @@ open class ReferenceParser: Parser {
 		 	try enterOuterAlt(_localctx, 1)
 		 	setState(87)
 		 	_la = try _input.LA(1)
-		 	if (!((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
+		 	if (!(((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0))) {
 		 	try _errHandler.recoverInline(self)
 		 	}
 		 	else {

Sources/tart/OCI/Registry.swift

@@ -1,6 +1,5 @@
 import Foundation
 import Algorithms
-import AsyncAlgorithms
 
 enum RegistryError: Error {
   case UnexpectedHTTPStatusCode(when: String, code: Int, details: String = "")
@@ -21,6 +20,7 @@ enum HTTPCode: Int {
   case Ok = 200
   case Created = 201
   case Accepted = 202
+  case PartialContent = 206
   case Unauthorized = 401
   case NotFound = 404
 }
@@ -29,14 +29,26 @@ extension Data {
   func asText() -> String {
     String(decoding: self, as: UTF8.self)
   }
+
+  func asTextPreview(limit: Int = 1000) -> String {
+    guard count > limit else {
+      return asText()
+    }
+
+    return "\(asText().prefix(limit))..."
+  }
 }
 
-extension AsyncThrowingChannel<Data, Error> {
-  func asData() async throws -> Data {
+extension AsyncThrowingStream<Data, Error> {
+  func asData(limitBytes: Int64? = nil) async throws -> Data {
     var result = Data()
 
     for try await chunk in self {
       result += chunk
+
+      if let limitBytes, result.count > limitBytes {
+        return result
+      }
     }
 
     return result
@@ -99,27 +111,24 @@ struct TokenResponse: Decodable, Authentication {
 }
 
 class Registry {
-  private let baseURL: URL
+  let baseURL: URL
   let namespace: String
   let credentialsProviders: [CredentialsProvider]
   let authenticationKeeper = AuthenticationKeeper()
 
-  var host: String? {
-    guard let host = baseURL.host else { return nil }
-
-    if let port = baseURL.port {
-      return "\(host):\(port)"
-    }
-
-    return host
-  }
+  // Host with an optional port (e.g. "127.0.0.1:5000"), which is used for naming
+  // and credentials lookup. For Docker Hub it stays "docker.io", while baseURL
+  // points to registry-1.docker.io.
+  let host: String?
 
   init(baseURL: URL,
        namespace: String,
+       host: String? = nil,
        credentialsProviders: [CredentialsProvider] = [EnvironmentCredentialsProvider(), DockerConfigCredentialsProvider(), KeychainCredentialsProvider()]
   ) throws {
     self.baseURL = baseURL
     self.namespace = namespace
+    self.host = host ?? Registry.hostWithPort(of: baseURL)
     self.credentialsProviders = credentialsProviders
   }
 
@@ -130,9 +139,9 @@ class Registry {
     credentialsProviders: [CredentialsProvider] = [EnvironmentCredentialsProvider(), DockerConfigCredentialsProvider(), KeychainCredentialsProvider()]
   ) throws {
     let proto = insecure ? "http" : "https"
-    let baseURLComponents = URLComponents(string: proto + "://" + host + "/v2/")!
+    var baseURLComponents = URLComponents(string: proto + "://" + host + "/v2/")!
 
-    guard let baseURL = baseURLComponents.url else {
+    guard var baseURL = baseURLComponents.url else {
       var hint = ""
 
       if host.hasPrefix("http://") || host.hasPrefix("https://") {
@@ -142,7 +151,33 @@ class Registry {
       throw RuntimeError.ImproperlyFormattedHost(host, hint)
     }
 
-    try self.init(baseURL: baseURL, namespace: namespace, credentialsProviders: credentialsProviders)
+    // Naming and credentials lookup use the host and port of the original URL,
+    // so it's "docker.io" for Docker Hub and "127.0.0.1:5000" for "127.0.0.1:05000"
+    let normalizedHost = Registry.hostWithPort(of: baseURL)
+
+    // Docker Hub serves its registry API from registry-1.docker.io, while docker.io,
+    // the host used in image names, redirects to Docker's website. URLSession follows
+    // these redirects, so we'd get an HTML page with HTTP 200 instead of an API
+    // response, which breaks pushing, pulling and "tart login" credentials validation.
+    //
+    // Host names are case insensitive, and only the host is replaced,
+    // so an explicit port like in "Docker.IO:443" is kept.
+    if baseURLComponents.host?.lowercased() == "docker.io" {
+      baseURLComponents.host = "registry-1.docker.io"
+      baseURL = baseURLComponents.url!
+    }
+
+    try self.init(baseURL: baseURL, namespace: namespace, host: normalizedHost, credentialsProviders: credentialsProviders)
+  }
+
+  private static func hostWithPort(of url: URL) -> String? {
+    guard let host = url.host else { return nil }
+
+    if let port = url.port {
+      return "\(host):\(port)"
+    }
+
+    return host
   }
 
   func ping() async throws {
@@ -160,7 +195,7 @@ class Registry {
                                                  body: manifestJSON)
     if response.statusCode != HTTPCode.Created.rawValue {
       throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing manifest", code: response.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
     }
 
     return Digest.hash(manifestJSON)
@@ -171,7 +206,7 @@ class Registry {
                                                  headers: ["Accept": ociManifestMediaType])
     if response.statusCode != HTTPCode.Ok.rawValue {
       throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling manifest", code: response.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
     }
 
     let manifest = try OCIManifest(fromJSON: data)
@@ -197,7 +232,7 @@ class Registry {
                                                      headers: ["Content-Length": "0"])
     if postResponse.statusCode != HTTPCode.Accepted.rawValue {
       throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (POST)", code: postResponse.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
     }
 
     // Figure out where to upload the blob
@@ -218,7 +253,7 @@ class Registry {
       )
       if response.statusCode != HTTPCode.Created.rawValue {
         throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (PUT) to \(uploadLocation)",
-                                                     code: response.statusCode, details: data.asText())
+                                                     code: response.statusCode, details: data.asTextPreview())
       }
       return digest
     }
@@ -241,7 +276,7 @@ class Registry {
       // always accept both statuses since AWS ECR is not following specification
       if response.statusCode != HTTPCode.Created.rawValue && response.statusCode != HTTPCode.Accepted.rawValue {
         throw RegistryError.UnexpectedHTTPStatusCode(when: "streaming blob to \(uploadLocation)",
-                                                     code: response.statusCode, details: data.asText())
+                                                     code: response.statusCode, details: data.asTextPreview())
       }
       uploadedBytes += chunk.count
       // Update location for the next chunk
@@ -260,14 +295,26 @@ class Registry {
     case HTTPCode.NotFound.rawValue:
       return false
     default:
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "checking blob", code: response.statusCode, details: data.asText())
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "checking blob", code: response.statusCode, details: data.asTextPreview())
     }
   }
 
-  public func pullBlob(_ digest: String, handler: (Data) async throws -> Void) async throws {
-    let (channel, response) = try await channelRequest(.GET, endpointURL("\(namespace)/blobs/\(digest)"), viaFile: true)
-    if response.statusCode != HTTPCode.Ok.rawValue {
-      let body = try await channel.asData().asText()
+  public func pullBlob(_ digest: String, rangeStart: Int64 = 0, handler: (Data) async throws -> Void) async throws {
+    var expectedStatusCode = HTTPCode.Ok
+    var headers: [String: String] = [:]
+
+    // Send Range header and expect HTTP 206 in return
+    //
+    // However, do not send Range header at all when rangeStart is 0,
+    // because it makes no sense and we might get HTTP 200 in return
+    if rangeStart != 0 {
+      expectedStatusCode = HTTPCode.PartialContent
+      headers["Range"] = "bytes=\(rangeStart)-"
+    }
+
+    let (channel, response) = try await channelRequest(.GET, endpointURL("\(namespace)/blobs/\(digest)"), headers: headers, viaFile: true)
+    if response.statusCode != expectedStatusCode.rawValue {
+      let body = try await channel.asData(limitBytes: 4096).asTextPreview()
       throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling blob", code: response.statusCode,
                                                    details: body)
     }
@@ -307,7 +354,7 @@ class Registry {
     body: Data? = nil,
     doAuth: Bool = true,
     viaFile: Bool = false
-  ) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  ) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
     var urlComponents = urlComponents
 
     if urlComponents.queryItems == nil && !parameters.isEmpty {
@@ -327,12 +374,11 @@ class Registry {
       request.httpBody = body
     }
 
-    var (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile)
+    var (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile, doAuth: doAuth)
 
     if doAuth && response.statusCode == HTTPCode.Unauthorized.rawValue {
-      _ = try await channel.asData()
       try await auth(response: response)
-      (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile)
+      (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile, doAuth: doAuth)
     }
 
     return (channel, response)
@@ -392,32 +438,34 @@ class Registry {
     let (data, response) = try await dataRequest(.GET, authenticateURL, headers: headers, doAuth: false)
     if response.statusCode != HTTPCode.Ok.rawValue {
       throw RegistryError.AuthFailed(why: "received unexpected HTTP status code \(response.statusCode) "
-        + "while retrieving an authentication token", details: data.asText())
+        + "while retrieving an authentication token", details: data.asTextPreview())
     }
 
     await authenticationKeeper.set(try TokenResponse.parse(fromData: data))
   }
 
-  private func lookupCredentials() throws -> (String, String)? {
-    var host = baseURL.host!
-
-    if let port = baseURL.port {
-      host += ":\(port)"
-    }
+  func lookupCredentials() throws -> (String, String)? {
+    let host = self.host!
 
     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
   }
 
-  private func authAwareRequest(request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  private func authAwareRequest(request: URLRequest, viaFile: Bool = false, doAuth: Bool) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
     var request = request
 
-    if let (name, value) = await authenticationKeeper.header() {
-      request.addValue(value, forHTTPHeaderField: name)
+    if doAuth {
+      if let (name, value) = await authenticationKeeper.header() {
+        request.addValue(value, forHTTPHeaderField: name)
+      }
     }
 
     request.setValue("Tart/\(CI.version) (\(DeviceInfo.os); \(DeviceInfo.model))",

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/PIDLock.swift

@@ -11,7 +11,7 @@ class PIDLock {
     if fd == -1 {
       let details = Errno(rawValue: CInt(errno))
 
-      throw RuntimeError.PIDLockFailed("failed to open lock file \(url): \(details)")
+      throw RuntimeError.PIDLockMissing("failed to open lock file \(url): \(details)")
     }
   }
 

Sources/tart/Platform/Darwin.swift

@@ -38,7 +38,7 @@ struct UnsupportedHostOSError: Error, CustomStringConvertible {
         throw DecodingError.dataCorruptedError(forKey: .hardwareModel, in: container, debugDescription: "")
       }
       guard let hardwareModel = VZMacHardwareModel.init(dataRepresentation: data) else {
-        throw DecodingError.dataCorruptedError(forKey: .hardwareModel, in: container, debugDescription: "")
+        throw UnsupportedHostOSError()
       }
       self.hardwareModel = hardwareModel
     }
@@ -58,7 +58,11 @@ struct UnsupportedHostOSError: Error, CustomStringConvertible {
       VZMacOSBootLoader()
     }
 
-    func platform(nvramURL: URL) throws -> VZPlatformConfiguration {
+    func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration {
+      if needsNestedVirtualization {
+        throw RuntimeError.VMConfigurationError("macOS virtual machines do not support nested virtualization")
+      }
+
       let result = VZMacPlatformConfiguration()
 
       result.machineIdentifier = ecid
@@ -78,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)
@@ -100,35 +104,42 @@ struct UnsupportedHostOSError: Error, CustomStringConvertible {
       return result
     }
 
-    func keyboards() -> [VZKeyboardConfiguration] {
+    func keyboards(noUSB: Bool) -> [VZKeyboardConfiguration] {
+      var devices: [VZKeyboardConfiguration] = noUSB ? [] : [VZUSBKeyboardConfiguration()]
       if #available(macOS 14, *) {
         // Mac keyboard is only supported by guests starting with macOS Ventura
-        return [VZUSBKeyboardConfiguration(), VZMacKeyboardConfiguration()]
-      } else {
-        return [VZUSBKeyboardConfiguration()]
+        devices.append(VZMacKeyboardConfiguration())
       }
+      return devices
     }
 
-    func keyboardsSuspendable() -> [VZKeyboardConfiguration] {
+    func keyboardsSuspendable(noUSB: Bool) -> [VZKeyboardConfiguration] {
       if #available(macOS 14, *) {
         return [VZMacKeyboardConfiguration()]
       } else {
         // fallback to the regular configuration
-        return keyboards()
+        return keyboards(noUSB: noUSB)
       }
     }
 
-    func pointingDevices() -> [VZPointingDeviceConfiguration] {
+    func pointingDevices(noUSB: Bool) -> [VZPointingDeviceConfiguration] {
       // Trackpad is only supported by guests starting with macOS Ventura
-      [VZUSBScreenCoordinatePointingDeviceConfiguration(), VZMacTrackpadConfiguration()]
+      var devices: [VZPointingDeviceConfiguration] = noUSB ? [] : [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+      devices.append(VZMacTrackpadConfiguration())
+      return devices
     }
 
-    func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration] {
+    func pointingDevicesSimplified(noUSB: Bool) -> [VZPointingDeviceConfiguration] {
+      // Only include the USB pointing device, not the trackpad
+      return noUSB ? [] : [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+    }
+
+    func pointingDevicesSuspendable(noUSB: Bool) -> [VZPointingDeviceConfiguration] {
       if #available(macOS 14, *) {
         return [VZMacTrackpadConfiguration()]
       } else {
         // fallback to the regular configuration
-        return pointingDevices()
+        return pointingDevices(noUSB: noUSB)
       }
     }
   }

Sources/tart/Platform/Linux.swift

@@ -14,8 +14,12 @@ struct Linux: Platform {
     return result
   }
 
-  func platform(nvramURL: URL) throws -> VZPlatformConfiguration {
-    VZGenericPlatformConfiguration()
+  func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration {
+    let config = VZGenericPlatformConfiguration()
+    if #available(macOS 15, *) {
+      config.isNestedVirtualizationEnabled = needsNestedVirtualization
+    }
+    return config
   }
 
   func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
@@ -31,11 +35,16 @@ struct Linux: Platform {
     return result
   }
 
-  func keyboards() -> [VZKeyboardConfiguration] {
-    [VZUSBKeyboardConfiguration()]
+  func keyboards(noUSB: Bool) -> [VZKeyboardConfiguration] {
+    noUSB ? [] : [VZUSBKeyboardConfiguration()]
   }
 
-  func pointingDevices() -> [VZPointingDeviceConfiguration] {
-    [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+  func pointingDevices(noUSB: Bool) -> [VZPointingDeviceConfiguration] {
+    noUSB ? [] : [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+  }
+
+  func pointingDevicesSimplified(noUSB: Bool) -> [VZPointingDeviceConfiguration] {
+    // Linux doesn't support trackpad, so just return the regular pointing devices
+    return pointingDevices(noUSB: noUSB)
   }
 }

Sources/tart/Platform/Platform.swift

@@ -3,13 +3,14 @@ import Virtualization
 protocol Platform: Codable {
   func os() -> OS
   func bootLoader(nvramURL: URL) throws -> VZBootLoader
-  func platform(nvramURL: URL) throws -> VZPlatformConfiguration
+  func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration
   func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration
-  func keyboards() -> [VZKeyboardConfiguration]
-  func pointingDevices() -> [VZPointingDeviceConfiguration]
+  func keyboards(noUSB: Bool) -> [VZKeyboardConfiguration]
+  func pointingDevices(noUSB: Bool) -> [VZPointingDeviceConfiguration]
+  func pointingDevicesSimplified(noUSB: Bool) -> [VZPointingDeviceConfiguration]
 }
 
 protocol PlatformSuspendable: Platform {
-  func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration]
-  func keyboardsSuspendable() -> [VZKeyboardConfiguration]
+  func pointingDevicesSuspendable(noUSB: Bool) -> [VZPointingDeviceConfiguration]
+  func keyboardsSuspendable(noUSB: Bool) -> [VZKeyboardConfiguration]
 }

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 {
@@ -18,6 +20,7 @@ struct Root: AsyncParsableCommand {
       Login.self,
       Logout.self,
       IP.self,
+      Exec.self,
       Pull.self,
       Push.self,
       Import.self,
@@ -29,95 +32,160 @@ struct Root: AsyncParsableCommand {
       FQN.self,
     ])
 
-  public static func main() async throws {
-    // 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)
-        }
-      }
-    }
-
+  // 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 and run command
+    // 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 {
-      var command = try parseAsRoot()
-
-      // 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)
-        }
-      }
-
-      if var asyncCommand = command as? AsyncParsableCommand {
-        try await asyncCommand.run()
-      } else {
-        try command.run()
-      }
+      command = try parseAsRoot()
     } catch {
-      // Capture the error into Sentry
-      SentrySDK.capture(error: error)
-      SentrySDK.flush(timeout: 2.seconds.timeInterval)
+      exit(withError: error)
+    }
 
-      // 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)
+    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 any other exception, including ArgumentParser's ones
-      exit(withError: error)
+      // 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
@@ -126,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/ShellCompletions/ShellCompletions.swift

@@ -5,7 +5,7 @@ fileprivate func normalizeName(_ name: String) -> String {
   return name.replacingOccurrences(of: ":", with: "\\:")
 }
 
-func completeMachines(_ arguments: [String]) -> [String] {
+func completeMachines(_ arguments: [String], _ argumentIdx: Int, _ argumentPrefix: String) -> [String] {
   let localVMs = (try? VMStorageLocal().list().map { name, _ in
     normalizeName(name)
   }) ?? []
@@ -15,12 +15,12 @@ func completeMachines(_ arguments: [String]) -> [String] {
   return (localVMs + ociVMs)
 }
 
-func completeLocalMachines(_ arguments: [String]) -> [String] {
+func completeLocalMachines(_ arguments: [String], _ argumentIdx: Int, _ argumentPrefix: String) -> [String] {
   let localVMs = (try? VMStorageLocal().list()) ?? []
   return localVMs.map { name, _ in normalizeName(name) }
 }
 
-func completeRunningMachines(_ arguments: [String]) -> [String] {
+func completeRunningMachines(_ arguments: [String], _ argumentIdx: Int, _ argumentPrefix: String) -> [String] {
   let localVMs = (try? VMStorageLocal().list()) ?? []
   return localVMs
     .filter { _, vmDir in (try? vmDir.state() == .Running) ?? false}

Sources/tart/Term.swift

@@ -0,0 +1,60 @@
+import Foundation
+import System
+
+struct State {
+  fileprivate let termios: termios
+}
+
+class Term {
+  static func IsTerminal() -> Bool {
+    var termios = termios()
+
+    return tcgetattr(FileHandle.standardInput.fileDescriptor, &termios) != -1
+  }
+
+  static func MakeRaw() throws -> State {
+    var termiosOrig = termios()
+
+    var ret = tcgetattr(FileHandle.standardInput.fileDescriptor, &termiosOrig)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to retrieve terminal parameters: \(details)")
+    }
+
+    var termiosRaw = termiosOrig
+    cfmakeraw(&termiosRaw)
+
+    ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termiosRaw)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+
+    return State(termios: termiosOrig)
+  }
+
+  static func Restore(_ state: State) throws {
+    var termios = state.termios
+
+    let ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termios)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+  }
+
+  static func GetSize() throws -> (width: UInt16, height: UInt16) {
+    var winsize = winsize()
+
+    guard ioctl(STDOUT_FILENO, TIOCGWINSZ, &winsize) != -1 else {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to get terminal size: \(details)")
+    }
+
+    return (width: winsize.ws_col, height: winsize.ws_row)
+  }
+}

Sources/tart/URL+AccessDate.swift

@@ -1,4 +1,5 @@
 import Foundation
+import System
 
 extension URL {
   func accessDate() throws -> Date {
@@ -7,19 +8,21 @@ extension URL {
   }
 
   func updateAccessDate(_ accessDate: Date = Date()) throws {
-    let attrs = try resourceValues(forKeys: [.contentAccessDateKey])
-    let modificationDate = attrs.contentAccessDate!
-
-    let times = [accessDate.asTimeval(), modificationDate.asTimeval()]
-    let ret = utimes(path, times)
+    let times = [accessDate.asTimespec(), timespec(tv_sec: 0, tv_nsec: Int(UTIME_OMIT))]
+    let ret = utimensat(AT_FDCWD, path, times, 0)
     if ret != 0 {
-      throw RuntimeError.FailedToUpdateAccessDate("utimes(2) failed: \(ret.explanation())")
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.FailedToUpdateAccessDate("utimensat(2) failed: \(details)")
     }
   }
 }
 
 extension Date {
-  func asTimeval() -> timeval {
-    timeval(tv_sec: Int(timeIntervalSince1970), tv_usec: 0)
+  func asTimespec() -> timespec {
+    let seconds = floor(timeIntervalSince1970)
+    let nanoseconds = (timeIntervalSince1970 - seconds) * 1_000_000_000
+
+    return timespec(tv_sec: Int(seconds), tv_nsec: Int(nanoseconds))
   }
 }

Sources/tart/Utils.swift

@@ -1,5 +1,26 @@
 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>
+
+  // Inherit the caller's actor context, exactly as Task.init does. Without this, an
+  // operation written inside a @MainActor function runs on the cooperative pool
+  // rather than the main queue, trapping in callees that assert their queue.
+  @discardableResult
+  init(_ context: String, @_inheritActorContext 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

@@ -1,6 +1,5 @@
 import Foundation
 import Virtualization
-import AsyncAlgorithms
 import Semaphore
 
 struct UnsupportedRestoreImageError: Error {
@@ -47,9 +46,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
        directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
        serialPorts: [VZSerialPortConfiguration] = [],
        suspendable: Bool = false,
+       nested: Bool = false,
        audio: Bool = true,
        clipboard: Bool = true,
-       sync: VZDiskImageSynchronizationMode = .full
+       noUSBAccessories: Bool = false,
+       sync: VZDiskImageSynchronizationMode = .full,
+       caching: VZDiskImageCachingMode? = nil,
+       noTrackpad: Bool = false,
+       noPointer: Bool = false,
+       noKeyboard: Bool = false
   ) throws {
     name = vmDir.name
     config = try VMConfig.init(fromURL: vmDir.configURL)
@@ -60,15 +65,21 @@ 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,
                                                 serialPorts: serialPorts,
                                                 suspendable: suspendable,
+                                                nested: nested,
                                                 audio: audio,
                                                 clipboard: clipboard,
-                                                sync: sync
+                                                noUSBAccessories: noUSBAccessories,
+                                                sync: sync,
+                                                caching: caching,
+                                                noTrackpad: noTrackpad,
+                                                noPointer: noPointer,
+                                                noKeyboard: noKeyboard
     )
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
@@ -96,16 +107,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     // Download the IPSW
     defaultLogger.appendNewLine("Fetching \(remoteURL.lastPathComponent)...")
 
-    let downloadProgress = Progress(totalUnitCount: 100)
-    ProgressObserver(downloadProgress).log(defaultLogger)
-
     let request = URLRequest(url: remoteURL)
-    let (channel, response) = try await Fetcher.fetch(request, viaFile: true, progress: downloadProgress)
+    let (channel, response) = try await Fetcher.fetch(request, viaFile: true)
 
     let temporaryLocation = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString + ".ipsw")
-    defaultLogger.appendNewLine("Computing digest for \(temporaryLocation.path)...")
-    let digestProgress = Progress(totalUnitCount: response.expectedContentLength)
-    ProgressObserver(digestProgress).log(defaultLogger)
+
+    let progress = Progress(totalUnitCount: response.expectedContentLength)
+    ProgressObserver(progress).log(defaultLogger)
 
     FileManager.default.createFile(atPath: temporaryLocation.path, contents: nil)
     let lock = try FileLock(lockURL: temporaryLocation)
@@ -115,10 +123,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     let digest = Digest()
 
     for try await chunk in channel {
-      let chunkAsData = Data(chunk)
-      fileHandle.write(chunkAsData)
-      digest.update(chunkAsData)
-      digestProgress.completedUnitCount += Int64(chunk.count)
+      try fileHandle.write(contentsOf: chunk)
+      digest.update(chunk)
+      progress.completedUnitCount += Int64(chunk.count)
     }
 
     try fileHandle.close()
@@ -142,6 +149,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       vmDir: VMDirectory,
       ipswURL: URL,
       diskSizeGB: UInt16,
+      diskFormat: DiskImageFormat = .raw,
       network: Network = NetworkShared(),
       additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
       directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
@@ -174,14 +182,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       _ = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)
 
       // Create disk
-      try vmDir.resizeDisk(diskSizeGB)
+      try vmDir.resizeDisk(diskSizeGB, format: diskFormat)
 
       name = vmDir.name
       // Create config
       config = VMConfig(
         platform: Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: requirements.hardwareModel),
         cpuCountMin: requirements.minimumSupportedCPUCount,
-        memorySizeMin: requirements.minimumSupportedMemorySize
+        memorySizeMin: requirements.minimumSupportedMemorySize,
+        diskFormat: diskFormat
       )
       // allocate at least 4 CPUs because otherwise VMs are frequently freezing
       try config.setCPU(cpuCount: max(4, requirements.minimumSupportedCPUCount))
@@ -189,7 +198,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,
@@ -223,30 +233,43 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   #endif
 
   @available(macOS 13, *)
-  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16) async throws -> VM {
+  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16, diskFormat: DiskImageFormat = .raw) async throws -> VM {
     // Create NVRAM
     _ = try VZEFIVariableStore(creatingVariableStoreAt: vmDir.nvramURL)
 
     // Create disk
-    try vmDir.resizeDisk(diskSizeGB)
+    try vmDir.resizeDisk(diskSizeGB, format: diskFormat)
 
     // Create config
-    let config = VMConfig(platform: Linux(), cpuCountMin: 4, memorySizeMin: 4096 * 1024 * 1024)
+    let config = VMConfig(platform: Linux(), cpuCountMin: 4, memorySizeMin: 4096 * 1024 * 1024, diskFormat: diskFormat)
     try config.save(toURL: vmDir.configURL)
 
     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)
     }
   }
 
+  @MainActor
+  func connect(toPort: UInt32) async throws -> VZVirtioSocketConnection {
+    guard let socketDevice = virtualMachine.socketDevices.first else {
+      throw RuntimeError.VMSocketFailed(toPort, ", VM has no socket devices configured")
+    }
+
+    guard let virtioSocketDevice = socketDevice as? VZVirtioSocketDevice else {
+      throw RuntimeError.VMSocketFailed(toPort, ", expected VM's first socket device to have a type of VZVirtioSocketDevice, got \(type(of: socketDevice)) instead")
+    }
+
+    return try await virtioSocketDevice.connect(toPort: toPort)
+  }
+
   func run() async throws {
     do {
       try await sema.waitUnlessCancelled()
@@ -266,10 +289,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()
@@ -287,7 +315,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   }
 
   static func craftConfiguration(
-    diskURL: URL,
+    vmDir: VMDirectory,
     nvramURL: URL,
     vmConfig: VMConfig,
     network: Network = NetworkShared(),
@@ -295,9 +323,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     directorySharingDevices: [VZDirectorySharingDeviceConfiguration],
     serialPorts: [VZSerialPortConfiguration],
     suspendable: Bool = false,
+    nested: Bool = false,
     audio: Bool = true,
     clipboard: Bool = true,
-    sync: VZDiskImageSynchronizationMode = .full
+    noUSBAccessories: Bool = false,
+    sync: VZDiskImageSynchronizationMode = .full,
+    caching: VZDiskImageCachingMode? = nil,
+    noTrackpad: Bool = false,
+    noPointer: Bool = false,
+    noKeyboard: Bool = false
   ) throws -> VZVirtualMachineConfiguration {
     let configuration = VZVirtualMachineConfiguration()
 
@@ -309,7 +343,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     configuration.memorySize = vmConfig.memorySize
 
     // Platform
-    configuration.platform = try vmConfig.platform.platform(nvramURL: nvramURL)
+    configuration.platform = try vmConfig.platform.platform(nvramURL: nvramURL, needsNestedVirtualization: nested)
 
     // Display
     configuration.graphicsDevices = [vmConfig.platform.graphicsDevice(vmConfig: vmConfig)]
@@ -317,25 +351,31 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     // Audio
     let soundDeviceConfiguration = VZVirtioSoundDeviceConfiguration()
 
-    let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
-    let outputAudioStreamConfiguration = VZVirtioSoundDeviceOutputStreamConfiguration()
-
     if audio && !suspendable {
+      let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
+      let outputAudioStreamConfiguration = VZVirtioSoundDeviceOutputStreamConfiguration()
+
       inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
       outputAudioStreamConfiguration.sink = VZHostAudioOutputStreamSink()
+
+      soundDeviceConfiguration.streams = [inputAudioStreamConfiguration, outputAudioStreamConfiguration]
+    } else {
+      // just a null speaker
+      soundDeviceConfiguration.streams = [VZVirtioSoundDeviceOutputStreamConfiguration()]
     }
 
-    soundDeviceConfiguration.streams = [inputAudioStreamConfiguration, outputAudioStreamConfiguration]
     configuration.audioDevices = [soundDeviceConfiguration]
 
     // Keyboard and mouse
-    if suspendable, let platformSuspendable = vmConfig.platform.self as? PlatformSuspendable {
-      configuration.keyboards = platformSuspendable.keyboardsSuspendable()
-      configuration.pointingDevices = platformSuspendable.pointingDevicesSuspendable()
-    } else {
-      configuration.keyboards = vmConfig.platform.keyboards()
-      configuration.pointingDevices = vmConfig.platform.pointingDevices()
-    }
+    configureInputDevices(
+      configuration,
+      platform: vmConfig.platform,
+      suspendable: suspendable,
+      noUSBAccessories: noUSBAccessories,
+      noTrackpad: noTrackpad,
+      noPointer: noPointer,
+      noKeyboard: noKeyboard
+    )
 
     // Networking
     configuration.networkDevices = network.attachments().map {
@@ -346,28 +386,39 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     // Clipboard sharing via Spice agent
-    if clipboard && vmConfig.os == .linux {
+    if clipboard {
       let spiceAgentConsoleDevice = VZVirtioConsoleDeviceConfiguration()
       let spiceAgentPort = VZVirtioConsolePortConfiguration()
       spiceAgentPort.name = VZSpiceAgentPortAttachment.spiceAgentPortName
-      spiceAgentPort.attachment = VZSpiceAgentPortAttachment()
+      let spiceAgentPortAttachment = VZSpiceAgentPortAttachment()
+      spiceAgentPortAttachment.sharesClipboard = true
+      spiceAgentPort.attachment = spiceAgentPortAttachment
       spiceAgentConsoleDevice.ports[0] = spiceAgentPort
       configuration.consoleDevices.append(spiceAgentConsoleDevice)
     }
 
     // Storage
-    let attachment: VZDiskImageStorageDeviceAttachment = vmConfig.os == .linux ?
-      // Use "cached" caching mode for virtio drive to prevent fs corruption on linux
-      try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false, cachingMode: .cached, synchronizationMode: sync) :
-      try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false, cachingMode: .automatic, synchronizationMode: sync)
-
-    var device: VZStorageDeviceConfiguration
-    if #available(macOS 14, *), vmConfig.os == .linux {
-      device = VZNVMExpressControllerDeviceConfiguration(attachment: attachment)
+    // 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 {
-      device = VZVirtioBlockDeviceConfiguration(attachment: attachment)
+      attachment = try VZDiskImageStorageDeviceAttachment(
+        url: vmDir.diskURL,
+        readOnly: false,
+        cachingMode: cachingMode,
+        synchronizationMode: sync
+      )
     }
-    var devices: [VZStorageDeviceConfiguration] = [device]
+
+    var devices: [VZStorageDeviceConfiguration] = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]
     devices.append(contentsOf: additionalStorageDevices)
     configuration.storageDevices = devices
 
@@ -386,21 +437,47 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     //
     // A dummy console device useful for implementing
     // host feature checks in the guest agent software.
-    if !suspendable {
-      let consolePort = VZVirtioConsolePortConfiguration()
-      consolePort.name = "tart-version-\(CI.version)"
+    let consolePort = VZVirtioConsolePortConfiguration()
+    consolePort.name = "tart-version-\(CI.version)"
 
-      let consoleDevice = VZVirtioConsoleDeviceConfiguration()
-      consoleDevice.ports[0] = consolePort
+    let consoleDevice = VZVirtioConsoleDeviceConfiguration()
+    consoleDevice.ports[0] = consolePort
 
-      configuration.consoleDevices.append(consoleDevice)
-    }
+    configuration.consoleDevices.append(consoleDevice)
+
+    // Socket device
+    configuration.socketDevices = [VZVirtioSocketDeviceConfiguration()]
 
     try configuration.validate()
 
     return configuration
   }
 
+  static func configureInputDevices(
+    _ configuration: VZVirtualMachineConfiguration,
+    platform: Platform,
+    suspendable: Bool = false,
+    noUSBAccessories: Bool = false,
+    noTrackpad: Bool = false,
+    noPointer: Bool = false,
+    noKeyboard: Bool = false
+  ) {
+    if suspendable, let platformSuspendable = platform as? PlatformSuspendable {
+      configuration.keyboards = platformSuspendable.keyboardsSuspendable(noUSB: noUSBAccessories)
+      configuration.pointingDevices = platformSuspendable.pointingDevicesSuspendable(noUSB: noUSBAccessories)
+    } else {
+      configuration.keyboards = noKeyboard ? [] : platform.keyboards(noUSB: noUSBAccessories)
+
+      if noPointer {
+        configuration.pointingDevices = []
+      } else if noTrackpad {
+        configuration.pointingDevices = platform.pointingDevicesSimplified(noUSB: noUSBAccessories)
+      } else {
+        configuration.pointingDevices = platform.pointingDevices(noUSB: noUSBAccessories)
+      }
+    }
+  }
+
   func guestDidStop(_ virtualMachine: VZVirtualMachine) {
     print("guest has stopped the virtual machine")
     sema.signal()

Sources/tart/VMConfig.swift

@@ -24,20 +24,32 @@ enum CodingKeys: String, CodingKey {
   case memorySize
   case macAddress
   case display
+  case displayRefit
+  case diskFormat
 
   // macOS-specific keys
   case ecid
   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)"
+    }
   }
 }
 
@@ -52,12 +64,15 @@ struct VMConfig: Codable {
   private(set) var memorySize: UInt64
   var macAddress: VZMACAddress
   var display: VMDisplayConfig = VMDisplayConfig()
+  var displayRefit: Bool?
+  var diskFormat: DiskImageFormat = .raw
 
   init(
     platform: Platform,
     cpuCountMin: Int,
     memorySizeMin: UInt64,
-    macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered()
+    macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered(),
+    diskFormat: DiskImageFormat = .raw
   ) {
     self.os = platform.os()
     self.arch = CurrentArchitecture()
@@ -65,6 +80,7 @@ struct VMConfig: Codable {
     self.macAddress = macAddress
     self.cpuCountMin = cpuCountMin
     self.memorySizeMin = memorySizeMin
+    self.diskFormat = diskFormat
     cpuCount = cpuCountMin
     memorySize = memorySizeMin
   }
@@ -83,7 +99,7 @@ struct VMConfig: Codable {
 
   func save(toURL: URL) throws {
     let encoder = JSONEncoder()
-    encoder.outputFormatting = .prettyPrinted
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
     try encoder.encode(self).write(to: toURL)
   }
 
@@ -121,6 +137,9 @@ struct VMConfig: Codable {
     self.macAddress = macAddress
 
     display = try container.decodeIfPresent(VMDisplayConfig.self, forKey: .display) ?? VMDisplayConfig()
+    displayRefit = try container.decodeIfPresent(Bool.self, forKey: .displayRefit)
+    let diskFormatString = try container.decodeIfPresent(String.self, forKey: .diskFormat) ?? "raw"
+    diskFormat = DiskImageFormat(rawValue: diskFormatString) ?? .raw
   }
 
   func encode(to encoder: Encoder) throws {
@@ -136,6 +155,10 @@ struct VMConfig: Codable {
     try container.encode(memorySize, forKey: .memorySize)
     try container.encode(macAddress.string, forKey: .macAddress)
     try container.encode(display, forKey: .display)
+    if let displayRefit = displayRefit {
+      try container.encode(displayRefit, forKey: .displayRefit)
+    }
+    try container.encode(diskFormat.rawValue, forKey: .diskFormat)
   }
 
   mutating func setCPU(cpuCount: Int) throws {

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,18 +1,19 @@
 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
 }
 
 extension VMDirectory {
-  func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt, localLayerCache: LocalLayerCache?) async throws {
-    // Pull VM's config file layer and re-serialize it into a config file
+  func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt, localLayerCache: LocalLayerCache?, deduplicate: Bool) async throws {
+    // Pull VM's config file layer and store it as the local config file.
     let configLayers = manifest.layers.filter {
       $0.mediaType == configMediaType
     }
@@ -24,26 +25,30 @@ extension VMDirectory {
     }
     let configFile = try FileHandle(forWritingTo: configURL)
     try await registry.pullBlob(configLayers.first!.digest) { data in
-      configFile.write(data)
+      try configFile.write(contentsOf: data)
     }
     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,18 +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)
+      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 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...")
 
@@ -78,39 +107,72 @@ extension VMDirectory {
     }
     let nvram = try FileHandle(forWritingTo: nvramURL)
     try await registry.pullBlob(nvramLayers.first!.digest) { data in
-      nvram.write(data)
+      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) 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
     let config = try VMConfig(fromURL: configURL)
+
+    // Add disk format label automatically
+    var labels = labels
+    labels[diskFormatLabel] = config.diskFormat.rawValue
     let configJSON = try JSONEncoder().encode(config)
     defaultLogger.appendNewLine("pushing config...")
     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...")
@@ -120,15 +182,16 @@ extension VMDirectory {
     layers.append(OCIManifestLayer(mediaType: nvramMediaType, size: nvram.count, digest: nvramDigest))
 
     // Craft a stub OCI config for Docker Hub compatibility
-    let ociConfigJSON = try OCIConfig(architecture: config.arch, os: config.os).toJSON()
+    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)...")
@@ -137,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

@@ -26,6 +26,12 @@ struct VMDirectory: Prunable {
   var manifestURL: URL {
     baseURL.appendingPathComponent("manifest.json")
   }
+  var overlayURL: URL {
+    baseURL.appendingPathComponent("overlay.asif")
+  }
+  var controlSocketURL: URL {
+    URL(fileURLWithPath: "control.sock", relativeTo: baseURL)
+  }
 
   var explicitlyPulledMark: URL {
     baseURL.appendingPathComponent(".explicitly-pulled")
@@ -84,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 {
@@ -100,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 {
@@ -108,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)"
+      )
     }
   }
 
@@ -139,14 +230,65 @@ struct VMDirectory: Prunable {
     try vmConfig.save(toURL: configURL)
   }
 
-  func resizeDisk(_ sizeGB: UInt16) throws {
-    if !FileManager.default.fileExists(atPath: diskURL.path) {
-      FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
+  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 {
+      // Existing disk - resize it
+      try resizeExistingDisk(sizeGB)
+    } else {
+      // New disk - create it with the specified format
+      try createDisk(sizeGB: sizeGB, format: format)
+    }
+  }
+
+  private func resizeExistingDisk(_ sizeGB: UInt16) throws {
+    // Check if this is an ASIF disk by reading the VM config
+    let vmConfig = try VMConfig(fromURL: configURL)
+
+    if vmConfig.diskFormat == .asif {
+      try resizeASIFDisk(sizeGB)
+    } else {
+      try resizeRawDisk(sizeGB)
+    }
+  }
+
+  private func resizeRawDisk(_ sizeGB: UInt16) throws {
     let diskFileHandle = try FileHandle.init(forWritingTo: diskURL)
     let currentDiskFileLength = try diskFileHandle.seekToEnd()
     let desiredDiskFileLength = UInt64(sizeGB) * 1000 * 1000 * 1000
+
     if desiredDiskFileLength < currentDiskFileLength {
       let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentDiskFileLength))
       let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredDiskFileLength))
@@ -158,6 +300,84 @@ struct VMDirectory: Prunable {
     try diskFileHandle.close()
   }
 
+  private func resizeASIFDisk(_ sizeGB: UInt16) throws {
+    do {
+      let diskImageInfo = try Diskutil.imageInfo(diskURL)
+
+      let currentSizeBytes = try diskImageInfo.totalBytes()
+      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)
+      } else {
+        // If sizes are equal, no action needed
+      }
+    } catch let error as RuntimeError {
+      throw error
+    } catch {
+      throw RuntimeError.FailedToResizeDisk("\(error)")
+    }
+  }
+
+  private func performASIFResize(_ sizeGB: UInt16) throws {
+    guard let diskutilURL = resolveBinaryPath("diskutil") else {
+      throw RuntimeError.FailedToResizeDisk("diskutil not found in PATH")
+    }
+
+    let process = Process()
+    process.executableURL = diskutilURL
+    process.arguments = [
+      "image", "resize",
+      "--size", "\(sizeGB)G",
+      diskURL.path
+    ]
+
+    let pipe = Pipe()
+    process.standardOutput = pipe
+    process.standardError = pipe
+
+    do {
+      try process.run()
+      process.waitUntilExit()
+
+      let data = pipe.fileHandleForReading.readDataToEndOfFile()
+
+      if process.terminationStatus != 0 {
+        let output = String(data: data, encoding: .utf8) ?? "Unknown error"
+        throw RuntimeError.FailedToResizeDisk("Failed to resize ASIF disk image: \(output)")
+      }
+    } catch {
+      throw RuntimeError.FailedToResizeDisk("Failed to execute diskutil resize: \(error)")
+    }
+  }
+
+  private func createDisk(sizeGB: UInt16, format: DiskImageFormat) throws {
+    switch format {
+    case .raw:
+      try createRawDisk(sizeGB: sizeGB)
+    case .asif:
+      try Diskutil.imageCreate(diskURL: diskURL, sizeGB: sizeGB)
+    }
+  }
+
+  private func createRawDisk(sizeGB: UInt16) throws {
+    // Create traditional raw disk image
+    FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
+
+    let diskFileHandle = try FileHandle.init(forWritingTo: diskURL)
+    let desiredDiskFileLength = UInt64(sizeGB) * 1000 * 1000 * 1000
+    try diskFileHandle.truncate(atOffset: desiredDiskFileLength)
+    try diskFileHandle.close()
+  }
+
+
   func delete() throws {
     let lock = try lock()
 
@@ -165,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 {
@@ -183,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 {
@@ -191,13 +427,48 @@ 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 markExplicitlyPulled() {
     FileManager.default.createFile(atPath: explicitlyPulledMark.path, contents: nil)
   }
@@ -205,4 +476,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

@@ -24,6 +24,8 @@ class VMStorageHelper {
   private static func missingVMWrap<R: Any>(_ name: String, closure: () throws -> R) throws -> R {
     do {
       return try closure()
+    } catch RuntimeError.PIDLockMissing {
+      throw RuntimeError.VMDoesNotExist(name: name)
     } catch {
       if error.isFileNotFound() {
         throw RuntimeError.VMDoesNotExist(name: name)
@@ -36,7 +38,8 @@ class VMStorageHelper {
 
 extension NSError {
   func isFileNotFound() -> Bool {
-    return self.code == NSFileNoSuchFileError || self.code == NSFileReadNoSuchFileError
+    return self.domain == NSCocoaErrorDomain &&
+      (self.code == NSFileNoSuchFileError || self.code == NSFileReadNoSuchFileError)
   }
 }
 
@@ -47,6 +50,7 @@ extension Error {
 }
 
 enum RuntimeError : Error {
+  case Generic(_ message: String)
   case VMConfigurationError(_ message: String)
   case VMDoesNotExist(name: String)
   case VMMissingFiles(_ message: String)
@@ -57,8 +61,11 @@ enum RuntimeError : Error {
   case DiskAlreadyInUse(_ message: String)
   case FailedToOpenBlockDevice(_ path: String, _ explanation: String)
   case InvalidDiskSize(_ message: String)
+  case FailedToCreateDisk(_ message: String)
+  case FailedToResizeDisk(_ message: String)
   case FailedToUpdateAccessDate(_ message: String)
   case PIDLockFailed(_ message: String)
+  case PIDLockMissing(_ message: String)
   case FailedToParseRemoteName(_ message: String)
   case VMTerminationFailed(_ message: String)
   case ImproperlyFormattedHost(_ host: String, _ hint: String)
@@ -68,9 +75,11 @@ 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)
+  case VMSocketFailed(_ port: UInt32, _ explanation: String)
+  case TerminalOperationFailed(_ message: String)
 }
 
 protocol HasExitCode {
@@ -80,6 +89,8 @@ protocol HasExitCode {
 extension RuntimeError : CustomStringConvertible {
   public var description: String {
     switch self {
+    case .Generic(let message):
+      return message
     case .VMConfigurationError(let message):
       return message
     case .VMDoesNotExist(let name):
@@ -100,10 +111,16 @@ extension RuntimeError : CustomStringConvertible {
       return "failed to open block device \(path): \(explanation)"
     case .InvalidDiskSize(let message):
       return message
+    case .FailedToCreateDisk(let message):
+      return message
+    case .FailedToResizeDisk(let message):
+      return message
     case .FailedToUpdateAccessDate(let message):
       return message
     case .PIDLockFailed(let message):
       return message
+    case .PIDLockMissing(let message):
+      return message
     case .FailedToParseRemoteName(let cause):
       return "failed to parse remote name: \(cause)"
     case .VMTerminationFailed(let message):
@@ -122,12 +139,16 @@ 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):
       return message
+    case .VirtualMachineLimitExceeded(let hint):
+      return "The number of VMs exceeds the system limit\(hint)"
+    case .VMSocketFailed(let port, let explanation):
+      return "Failed to establish a VM socket connection to port \(port): \(explanation)"
+    case .TerminalOperationFailed(let message):
+      return message
     }
   }
 }
@@ -146,14 +167,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,36 @@ 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 {
+    // Replacing a running VM's directory unlinks its locked config and disks,
+    // leaving a live VM that list and stop can no longer find by name.
+    let destinationLock = FileManager.default.fileExists(atPath: destination.configURL.path)
+      ? try destination.lock() : nil
+    if let destinationLock, try !destinationLock.trylock() {
+      throw RuntimeError.VMIsRunning(destination.name)
+    }
+    defer { withExtendedLifetime(destinationLock) {} }
+
+    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 {
@@ -27,12 +128,12 @@ class VMStorageOCI: PrunableStorage {
     return digest
   }
 
-  func open(_ name: RemoteName) throws -> VMDirectory {
+  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()
+    try vmDir.baseURL.updateAccessDate(accessDate)
 
     return vmDir
   }
@@ -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) 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,52 +430,101 @@ 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
+      _ = try? open(name, Date(timeIntervalSince1970: 0))
 
       // Lock the temporary VM directory to prevent it's garbage collection
       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, backoff: .exponentialWithFullJitter(baseDelay: .seconds(5), maxDelay: .seconds(60))) {
-          // Choose the best base image which has the most deduplication ratio
-          let localLayerCache = try await chooseLocalLayerCache(name, manifest, registry)
+        try await retry(maxAttempts: 5) {
+          // 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)
 
-            defaultLogger.appendNewLine("found an image \(llc.name) that will allow us to deduplicate \(deduplicatedHuman), using it as a base...")
+            if deduplicate {
+              defaultLogger.appendNewLine("found an image \(llc.name) that will allow us to deduplicate \(deduplicatedHuman), using it as a base...")
+            } else {
+              defaultLogger.appendNewLine("found an image \(llc.name) that will allow us to avoid fetching \(deduplicatedHuman), will try use it...")
+            }
           }
 
-          try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency, localLayerCache: localLayerCache)
+          try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency, localLayerCache: localLayerCache, deduplicate: deduplicate)
         } recoverFromFailure: { error in
-          if error is Retryable {
-            print("Error: \(error.localizedDescription)")
-            print("Attempting to re-try...")
+          if error is URLError {
+            print("Error pulling image: \"\(error.localizedDescription)\", attempting to re-try...")
 
             return .retry
           }
 
           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...")
@@ -235,6 +538,118 @@ class VMStorageOCI: PrunableStorage {
       // are excluded from garbage collection
       VMDirectory(baseURL: vmURL(name)).markExplicitlyPulled()
     }
+
+    // to explicitly set the image as being accessed so it won't get pruned immediately
+    _ = 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 {
@@ -247,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()
   }
@@ -264,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
       }
 
@@ -279,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
@@ -289,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
@@ -306,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 {