@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/bootstrap/fleet-remote-bootstrap.sh

@@ -0,0 +1,185 @@
+#!/bin/sh
+# Executed over strict SSH from the selected verified Git revision. stdin is a
+# base64 Git bundle. All executable content remains in this tracked source.
+set -eu
+umask 077
+revision=$1
+bundle_sha=$2
+node=$3
+source_mode=${4:-transfer}
+case "$source_mode" in cached|transfer) ;; *) exit 2;; esac
+case "$revision" in *[!a-f0-9]*|'') exit 2;; esac
+[ "${#revision}" = 40 ] || exit 2
+case "$bundle_sha" in *[!a-f0-9]*|'') exit 2;; esac
+[ "${#bundle_sha}" = 64 ] || exit 2
+case "$node" in *[!a-z0-9-]*|'') exit 2;; esac
+phase=bootstrap
+bundle=''
+code=0
+failure_code=REMOTE_BOOTSTRAP_INCOMPLETE
+die() { failure_code=$1; exit 1; }
+fail() {
+  printf '{"version":1,"checks":[{"id":"bootstrap:%s","status":"fail","summary":"%s","remedy":{"action":"Inspect prerequisites and the remote operation lock, then retry the approved revision. No success receipt advanced."}}]}\n' "$phase" "$failure_code"
+}
+trap 'code=$?; [ -z "$bundle" ] || rm -f -- "$bundle"; if [ "$code" != 0 ]; then fail; fi' EXIT
+# Preserve the lock holder if its SSH channel disappears mid-install.
+trap '' HUP
+trap 'exit 1' INT TERM
+# No shell startup assumptions, and no implicit root development user.
+[ "$(id -u)" != 0 ] || die ROOT_DEVELOPMENT_USER_REJECTED
+# Ubuntu 26.04 is the accepted worker platform; macOS 14+ follows the same
+# phases best effort with launchd instead of systemd.
+platform=$(uname -s)
+case "$platform" in
+  Linux)
+    # shellcheck source=/dev/null
+    . /etc/os-release
+    [ "$ID" = ubuntu ] && [ "$VERSION_ID" = 26.04 ] || die UBUNTU_BASELINE_MISMATCH
+    case "$(uname -m)" in x86_64|aarch64) ;; *) die UBUNTU_ARCHITECTURE_UNSUPPORTED;; esac ;;
+  Darwin)
+    major=$(sw_vers -productVersion | cut -d. -f1)
+    case "$major" in ''|*[!0-9]*) die MACOS_BASELINE_MISMATCH;; esac
+    [ "$major" -ge 14 ] || die MACOS_BASELINE_MISMATCH
+    case "$(uname -m)" in arm64|x86_64) ;; *) die MACOS_ARCHITECTURE_UNSUPPORTED;; esac ;;
+  *) die PLATFORM_UNSUPPORTED;;
+esac
+root="$HOME/.local/share/personal/fleet"
+# Refuse symlinked state roots rather than allowing writes through them.
+for path in "$HOME/.local" "$HOME/.local/share" "$HOME/.local/share/personal" "$root"; do
+  [ ! -L "$path" ] || die FLEET_STATE_PATH_UNSAFE
+done
+mkdir -p "$root"
+phase=lock
+[ ! -L "$root/remote-operation.lock" ] || exit 1
+exec 9>"$root/remote-operation.lock"
+# macOS has no flock(1); lock the same descriptor through fcntl. The lock
+# follows this shell's open descriptor and is released when it exits.
+if command -v flock >/dev/null 2>&1; then
+  flock -n 9 || die FLEET_REMOTE_LOCKED
+else
+  command -v python3 >/dev/null 2>&1 || die BOOTSTRAP_LOCK_TOOL_REQUIRED
+  python3 -c 'import fcntl; fcntl.flock(9, fcntl.LOCK_EX | fcntl.LOCK_NB)' 9>&9 || die FLEET_REMOTE_LOCKED
+fi
+printf '{"version":1,"pid":%s,"revision":"%s","node":"%s"}\n' "$$" "$revision" "$node" >"$root/remote-operation.json"
+phase=resources
+# A bootstrap floor protects source transfer and minimal prerequisites. The
+# Workstation baseline subsequently enforces its stricter declared capacity.
+free_kib=$(df -Pk "$root" | awk 'END {print $4}')
+free_inodes=$(df -Pi "$root" | awk 'END {print $4}')
+case "$free_kib:$free_inodes" in *[!0-9:]*|:*|*:) die BOOTSTRAP_CAPACITY_UNVERIFIED;; esac
+[ "$free_kib" -ge 2097152 ] && [ "$free_inodes" -ge 50000 ] || die BOOTSTRAP_DISK_CAPACITY_REQUIRED
+phase=source-transfer
+if [ "$source_mode" = transfer ]; then
+bundle=$(mktemp "$root/source.XXXXXX")
+# Leave no executable payload copies; this temporary file is only Git data.
+base64 -d >"$bundle"
+if command -v sha256sum >/dev/null 2>&1; then
+  printf '%s  %s\n' "$bundle_sha" "$bundle" | sha256sum -c - >/dev/null 2>&1 || die SOURCE_DIGEST_MISMATCH
+else
+  [ "$(shasum -a 256 "$bundle" | cut -d' ' -f1)" = "$bundle_sha" ] || die SOURCE_DIGEST_MISMATCH
+fi
+fi
+phase=prerequisites
+if [ "$platform" = Linux ]; then
+missing=''
+for package in git curl ca-certificates unzip xz-utils build-essential python3 ansible-core; do
+  dpkg-query -W -f='${db:Status-Status}' "$package" 2>/dev/null | grep -qx installed || missing="$missing $package"
+done
+if [ -n "$missing" ]; then
+  sudo -n true >/dev/null 2>&1 || die SUDO_AUTHORIZATION_REQUIRED
+  # Never remove APT locks or kill package processes. Timeout keeps genuine
+  # transactions bounded; Ubuntu archive signatures/TLS remain enabled.
+  sudo -n timeout 300 apt-get -o DPkg::Lock::Timeout=120 update >/dev/null 2>&1 || die APT_UPDATE_FAILED
+  # shellcheck disable=SC2086
+  sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=120 --no-install-recommends install -y $missing >/dev/null 2>&1 || die APT_INSTALL_FAILED
+fi
+else
+  # Apple Command Line Tools provide git and python3; Ansible runs through the
+  # pinned uv tool runner installed by the shared mise toolchain below.
+  xcode-select -p >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
+  command -v git >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
+fi
+phase=source-verification
+deployment="$root/revisions/$revision"
+[ ! -L "$root/revisions" ] && [ ! -L "$deployment" ] || exit 1
+mkdir -p "$deployment"
+if [ ! -e "$deployment/.git" ]; then
+  [ -z "$(ls -A "$deployment")" ] || exit 1
+  git -C "$deployment" init -q >/dev/null 2>&1 || exit 1
+fi
+# An interrupted initial fetch/checkout can leave an empty initialized repository.
+# Resume only that state; an existing commit or untracked work is never reset.
+if ! git -C "$deployment" rev-parse --verify HEAD >/dev/null 2>&1; then
+  [ "$source_mode" = transfer ] || die SOURCE_CACHE_CHANGED
+  [ "$(git -C "$deployment" rev-parse --show-toplevel)" = "$deployment" ] || exit 1
+  clean=$(git -C "$deployment" status --porcelain) || die SOURCE_STATUS_FAILED
+  [ -z "$clean" ] || die SOURCE_CHECKOUT_CONFLICT
+  # The bundle holds this commit without its history: declare the checkout
+  # shallow at it so Git accepts a commit whose parents are absent.
+  printf '%s\n' "$revision" >"$deployment/.git/shallow"
+  git -C "$deployment" fetch --no-tags "$bundle" "$revision" >/dev/null 2>&1 || exit 1
+  git -C "$deployment" checkout --detach "$revision" >/dev/null 2>&1 || exit 1
+fi
+[ -z "$bundle" ] || rm -f "$bundle"
+bundle=''
+[ "$(git -C "$deployment" rev-parse HEAD)" = "$revision" ] || exit 1
+[ "$(git -C "$deployment" rev-parse --show-toplevel)" = "$deployment" ] || exit 1
+clean=$(git -C "$deployment" status --porcelain) || die SOURCE_STATUS_FAILED
+[ -z "$clean" ] || die SOURCE_CHECKOUT_CONFLICT
+phase=toolchain
+cd "$deployment"
+export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:/usr/local/bin:/usr/bin:/bin"
+status_file="$root/toolchain-status.json"
+ready_file="$root/toolchain-ready"
+[ ! -L "$status_file" ] && [ ! -L "$ready_file" ] || die FLEET_STATE_PATH_UNSAFE
+# Warm: the same toolchain inputs (tool pins, locks and the setup code itself)
+# passed within a day, so a revision that changes none of them skips the full
+# setup. Changed inputs, a failure or an older stamp run it; agent versions
+# are still checked (and reinstalled on drift) by node convergence.
+toolchain_key=$(git rev-parse HEAD:mise.toml HEAD:mise.lock HEAD:.mise HEAD:bun.lock HEAD:package.json HEAD:bootstrap 2>/dev/null | tr '\n' ' ')
+[ -n "$toolchain_key" ] || toolchain_key=$revision
+if [ "$(cat "$ready_file" 2>/dev/null)" = "$toolchain_key" ] && [ -n "$(find "$ready_file" -mmin -1440 2>/dev/null)" ]; then
+  toolchain_warm=1
+else
+  toolchain_warm=''
+  rm -f -- "$status_file" "$ready_file"
+fi
+if command -v timeout >/dev/null 2>&1; then bounded='timeout 1800'; else bounded=''; fi
+# shellcheck disable=SC2086
+if [ -z "$toolchain_warm" ] && ! $bounded bash bootstrap/bootstrap.sh --worker --non-interactive --status-file "$status_file" >/dev/null 2>&1; then
+  tool_phase=$(sed -n 's/.*"phase":"\([a-z0-9-]*\)".*/\1/p' "$status_file" 2>/dev/null) || tool_phase=''
+  case "$tool_phase" in
+    managed-config) die TOOLCHAIN_CONFIG_CONFLICT;;
+    mise) die TOOLCHAIN_MISE_FAILED;;
+    aws) die TOOLCHAIN_AWS_FAILED;;
+    t3) die TOOLCHAIN_T3_FAILED;;
+    global-config|shell) die TOOLCHAIN_PATH_CONFIGURATION_FAILED;;
+    dependencies) die TOOLCHAIN_FROZEN_DEPENDENCIES_FAILED;;
+    *) die TOOLCHAIN_CONVERGENCE_FAILED;;
+  esac
+fi
+# A new revision's checkout still needs its own (cached, frozen) dependencies.
+if [ -n "$toolchain_warm" ] && [ ! -d node_modules ]; then
+  # shellcheck disable=SC2086
+  $bounded mise exec --locked bun -- bun install --frozen-lockfile >/dev/null 2>&1 || die TOOLCHAIN_FROZEN_DEPENDENCIES_FAILED
+fi
+[ -n "$toolchain_warm" ] || printf '%s' "$toolchain_key" >"$ready_file"
+# Every synced revision is a full checkout with its own dependencies (about
+# 1 GB). Keep this one, the one T3's providers launch from and the two most
+# recently used others; the rest would slowly fill the disk.
+phase=cleanup
+touch "$deployment"
+applied=$(basename "$(readlink "$root/current" 2>/dev/null || true)")
+kept=0
+# shellcheck disable=SC2012
+for old in $(ls -1t "$root/revisions"); do
+  case "$old" in *[!a-f0-9]*) continue;; esac
+  [ "${#old}" = 40 ] || continue
+  [ "$old" != "$revision" ] && [ "$old" != "$applied" ] || continue
+  kept=$((kept + 1))
+  [ "$kept" -gt 2 ] || continue
+  rm -rf -- "${root:?}/revisions/$old" || true
+done
+phase=configuration
+trap - EXIT INT TERM
+exec mise exec --locked bun -- bun src/node-converge.ts "$node" "$revision"

package/bootstrap/global-config.ts

@@ -0,0 +1,113 @@
+/** Publish one managed global mise config without clobbering unrelated configuration. */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const MARKER = '# Managed by dev-fleet bootstrap/setup.ts\n';
+/**
+ * Where agent harnesses create a fresh checkout per task. Every new path would
+ * need its own `mise trust`, and an untrusted mise.toml makes every mise shim
+ * (claude, codex, bun, ...) exit before the agent starts. mise honours this
+ * setting only in the global config, so it is added at publish time and never
+ * written into the repository's mise.toml.
+ */
+export const AGENT_WORKTREE_ROOTS = ['~/.t3/worktrees'];
+const MANAGED = /^# Managed by \S+ \S*setup\.ts\n/;
+export const workspaceRoot = join(import.meta.dirname, '..');
+
+export function globalConfigDir(): string {
+  if (process.env['MISE_GLOBAL_CONFIG_FILE']) {
+    throw new Error(
+      'Unset MISE_GLOBAL_CONFIG_FILE before applying the shared toolchain.'
+    );
+  }
+  return (
+    process.env['MISE_CONFIG_DIR'] ??
+    join(process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config'), 'mise')
+  );
+}
+
+export function assertManagedConfig(dir: string): void {
+  const config = join(dir, 'config.toml');
+  const lock = join(dir, 'mise.lock');
+  // Any earlier owner name counts: the marker text identifies the file as
+  // managed, never the repository or path it was published from.
+  const managed =
+    existsSync(config) && MANAGED.test(readFileSync(config, 'utf8'));
+  if ((existsSync(config) && !managed) || (existsSync(lock) && !managed)) {
+    throw new Error(
+      `Existing mise configuration at ${dir}. Back up and move config.toml and mise.lock, then rerun. Nothing was overwritten.`
+    );
+  }
+}
+
+export function publishGlobalConfig(dir: string, root = workspaceRoot): void {
+  assertManagedConfig(dir);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'config.toml');
+  const previous = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+  const config =
+    MARKER +
+    withTrustedPaths(
+      readFileSync(join(root, 'mise.toml'), 'utf8'),
+      trustedPaths(previous)
+    );
+  if (previous !== config) writeFileSync(path, config);
+  cpSync(join(root, 'mise.lock'), join(dir, 'mise.lock'), {
+    filter: changedFile,
+  });
+  const sidecars = join(root, '.mise/locks');
+  if (existsSync(sidecars))
+    cpSync(sidecars, join(dir, '.mise/locks'), {
+      recursive: true,
+      filter: changedFile,
+    });
+}
+
+/**
+ * The managed roots plus any entries already in the published config, so a
+ * local `mise settings add trusted_config_paths ...` survives the next publish.
+ */
+export function trustedPaths(previous: string | undefined): string[] {
+  let local: unknown;
+  try {
+    local = previous
+      ? (Bun.TOML.parse(previous) as { settings?: Record<string, unknown> })
+          .settings?.['trusted_config_paths']
+      : undefined;
+  } catch {
+    local = undefined;
+  }
+  const extra = Array.isArray(local)
+    ? local.filter((path): path is string => typeof path === 'string')
+    : [];
+  return [...new Set([...AGENT_WORKTREE_ROOTS, ...extra])];
+}
+
+/** Adds trusted_config_paths to the [settings] table, creating it if absent. */
+export function withTrustedPaths(config: string, paths: string[]): string {
+  const line = `trusted_config_paths = [${paths.map((path) => JSON.stringify(path)).join(', ')}]`;
+  if (/^trusted_config_paths\s*=/m.test(config))
+    throw new Error(
+      'mise.toml sets trusted_config_paths; mise ignores it outside the global config. Add roots to AGENT_WORKTREE_ROOTS instead.'
+    );
+  const header = /^\[settings\][^\S\n]*\n/m;
+  return header.test(config)
+    ? config.replace(header, (match) => `${match}${line}\n`)
+    : `${config.replace(/\n*$/, '\n')}\n[settings]\n${line}\n`;
+}
+
+function changedFile(source: string, destination: string): boolean {
+  return (
+    statSync(source).isDirectory() ||
+    !existsSync(destination) ||
+    !readFileSync(source).equals(readFileSync(destination))
+  );
+}

package/bootstrap/install-launcher.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Links ~/.local/bin/devfleet to this checkout (or the one given). Idempotent.
+set -eu
+root=${1:-$(cd "$(dirname "$0")/.." && pwd)}
+[ -x "$root/bootstrap/devfleet" ] || exit 1
+mkdir -p "$HOME/.local/bin"
+ln -sfn "$root/bootstrap/devfleet" "$HOME/.local/bin/devfleet"

package/bootstrap/native-aws.ts

@@ -0,0 +1,86 @@
+/** AWS v2's official Windows MSI; aqua only packages AWS for Unix. */
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { workspaceRoot } from './global-config';
+
+type AwsConfig = {
+  tools: { aws: { version: string } };
+  vars: { aws_windows_msi_sha256: string };
+};
+export function awsWindowsArtifact(config: AwsConfig): {
+  url: string;
+  sha256: string;
+  version: string;
+} {
+  const version = config.tools.aws.version;
+  const sha256 = config.vars.aws_windows_msi_sha256;
+  if (!/^2\.\d+\.\d+$/.test(version) || !/^[a-f0-9]{64}$/.test(sha256))
+    throw new Error('Invalid pinned AWS Windows artifact.');
+  return {
+    version,
+    url: `https://awscli.amazonaws.com/AWSCLIV2-${version}.msi`,
+    sha256,
+  };
+}
+
+export async function installNativeAws(): Promise<void> {
+  if (process.platform !== 'win32') return;
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as AwsConfig;
+  const artifact = awsWindowsArtifact(config);
+  const bin = join(
+    process.env['ProgramFiles'] ?? 'C:\\Program Files',
+    'Amazon',
+    'AWSCLIV2'
+  );
+  const executable = join(bin, 'aws.exe');
+  const probe = () =>
+    spawnSync(executable, ['--version'], { encoding: 'utf8', timeout: 30_000 });
+  if (!probe().stdout?.includes(`aws-cli/${artifact.version} `)) {
+    const directory = mkdtempSync(join(tmpdir(), 'workspace-aws-'));
+    try {
+      const response = await fetch(artifact.url);
+      if (!response.ok)
+        throw new Error(`AWS MSI download failed (${response.status}).`);
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (createHash('sha256').update(bytes).digest('hex') !== artifact.sha256)
+        throw new Error('AWS MSI checksum mismatch.');
+      const msi = join(directory, 'aws.msi');
+      await Bun.write(msi, bytes);
+      const script = String.raw`$arguments = @('/i', ('"' + $env:WORKSPACE_AWS_MSI + '"'), '/qn', '/norestart'); $options = @{FilePath='msiexec.exe'; ArgumentList=$arguments; Wait=$true; PassThru=$true}; if ($env:WORKSPACE_AWS_ELEVATE -eq '1') { $options.Verb = 'RunAs' }; $p = Start-Process @options; exit $p.ExitCode`;
+      const result = spawnSync(
+        'powershell.exe',
+        ['-NoProfile', '-Command', script],
+        {
+          stdio: 'inherit',
+          env: {
+            ...process.env,
+            WORKSPACE_AWS_MSI: msi,
+            WORKSPACE_AWS_ELEVATE:
+              process.argv.includes('--non-interactive') || process.env['CI']
+                ? '0'
+                : '1',
+          },
+        }
+      );
+      if (result.status !== 0 && result.status !== 3010)
+        throw new Error(
+          `AWS MSI installation failed (exit ${result.status}, signal ${result.signal}, error ${result.error?.message ?? 'none'}); check for a conflicting installed version or run the reviewed bootstrap as Administrator.`
+        );
+    } finally {
+      rmSync(directory, { recursive: true, force: true });
+    }
+  }
+  if (!probe().stdout?.includes(`aws-cli/${artifact.version} `))
+    throw new Error(
+      `Expected AWS CLI ${artifact.version}; resolve the existing installation before retrying.`
+    );
+  process.env['PATH'] = `${bin};${process.env['PATH'] ?? ''}`;
+  // Persist across subsequent hosted-runner steps; normal users reopen the shell.
+  if (process.env['GITHUB_PATH'])
+    appendFileSync(process.env['GITHUB_PATH'], `${bin}\n`);
+}

package/bootstrap/native-t3.ts

@@ -0,0 +1,154 @@
+/** Pinned Ubuntu T3 distribution. Shared tool installation owns artifacts;
+ * Workstation owns services. Never touches ~/.t3 or replaces an existing launcher.
+ */
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { workspaceRoot } from './global-config';
+interface Configuration {
+  vars: {
+    t3_version: string;
+    t3_linux_x64_sha256: string;
+    t3_linux_arm64_sha256: string;
+    t3_desktop_amd64_sha256: string;
+    t3_desktop_arm64_sha256: string;
+  };
+}
+/** Pinned desktop .deb for Ubuntu workers. The GUI app is the worker's only T3
+ * process and embeds the server; the CLI tarball stays for policy commands. */
+export function desktopT3Artifact(config: Configuration, architecture: string) {
+  const deb = { x64: 'amd64', arm64: 'arm64' }[architecture];
+  if (!deb) throw new Error('Unsupported T3 architecture.');
+  const version = config.vars.t3_version;
+  const sha256 =
+    deb === 'amd64'
+      ? config.vars.t3_desktop_amd64_sha256
+      : config.vars.t3_desktop_arm64_sha256;
+  if (
+    !/^\d+\.\d+\.\d+(?:-nightly\.\d{8}\.\d+)?$/.test(version) ||
+    !/^[a-f0-9]{64}$/.test(sha256)
+  )
+    throw new Error('Invalid T3 desktop pin.');
+  const name = `T3-Code-${version}-${deb}.deb`;
+  return {
+    version,
+    sha256,
+    name,
+    url: `https://github.com/pingdotgg/t3code/releases/download/v${version}/${name}`,
+  };
+}
+export function managedT3Desktop() {
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as Configuration;
+  return desktopT3Artifact(config, process.arch);
+}
+export function nativeT3Artifact(config: Configuration, architecture: string) {
+  if (!['x64', 'arm64'].includes(architecture))
+    throw new Error('Unsupported T3 architecture.');
+  const version = config.vars.t3_version;
+  const sha256 =
+    architecture === 'x64'
+      ? config.vars.t3_linux_x64_sha256
+      : config.vars.t3_linux_arm64_sha256;
+  if (
+    !/^\d+\.\d+\.\d+(?:-nightly\.\d{8}\.\d+)?$/.test(version) ||
+    !/^[a-f0-9]{64}$/.test(sha256)
+  )
+    throw new Error('Invalid T3 pin.');
+  const name = `t3-${version}-linux-${architecture}`;
+  return {
+    version,
+    sha256,
+    name,
+    url: `https://github.com/pingdotgg/t3code/releases/download/v${version}/${name}.tar.gz`,
+  };
+}
+export function managedT3(): { path: string; version: string } {
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as Configuration;
+  const artifact = nativeT3Artifact(config, process.arch);
+  return {
+    path: join(homedir(), '.local/share/personal/tools', artifact.name, 't3'),
+    version: artifact.version,
+  };
+}
+export async function installNativeT3(): Promise<void> {
+  if (process.platform !== 'linux') return;
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as Configuration;
+  const artifact = nativeT3Artifact(config, process.arch);
+  const root = join(homedir(), '.local/share/personal/tools');
+  const archive = join(root, `${artifact.name}.tar.gz`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  if (!existsSync(archive)) {
+    const response = await fetch(artifact.url, {
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!response.ok) throw new Error('Pinned T3 artifact unavailable.');
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (createHash('sha256').update(bytes).digest('hex') !== artifact.sha256)
+      throw new Error('T3 artifact checksum mismatch.');
+    writeFileSync(`${archive}.partial`, bytes, { mode: 0o600 });
+    renameSync(`${archive}.partial`, archive);
+  }
+  if (
+    createHash('sha256').update(readFileSync(archive)).digest('hex') !==
+    artifact.sha256
+  )
+    throw new Error(
+      'T3 cached artifact drift; preserve running service and review maintenance recovery.'
+    );
+  const directory = join(root, artifact.name);
+  if (!existsSync(directory)) {
+    const staging = join(root, `${artifact.name}.staging`);
+    mkdirSync(staging, { recursive: true, mode: 0o700 });
+    try {
+      if (
+        spawnSync(
+          'tar',
+          ['--same-permissions', '-xzf', archive, '-C', staging],
+          { timeout: 120_000 }
+        ).status !== 0
+      )
+        throw new Error('T3 extraction failed.');
+      verifyArchive(archive, staging);
+      renameSync(join(staging, artifact.name), directory);
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+    }
+  } else verifyArchive(archive, root);
+  const version = spawnSync(join(directory, 't3'), ['--version'], {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  if (
+    version.status !== 0 ||
+    version.stdout.trim() !== `t3 v${artifact.version}`
+  )
+    throw new Error('Pinned T3 executable verification failed.');
+}
+
+function verifyArchive(archive: string, root: string): void {
+  if (
+    spawnSync(
+      'python3',
+      [join(workspaceRoot, 'bootstrap/verify-t3-archive.py'), archive, root],
+      { timeout: 120_000 }
+    ).status !== 0
+  )
+    throw new Error(
+      'Managed T3 files differ from the pinned artifact; maintenance is required.'
+    );
+}