feat(lifecycle): ship supervisor with CLI installations

.github/workflows/ci.yml

@@ -308,12 +308,13 @@ jobs:
           "$RUNNER_TEMP/config-schema/bin/python" scripts/check-config-schema.py
       - name: Test transport, projections and compiled bundle without host toolchains
         run: |
-          bunx ultracite check scripts/build-config-compiler.ts scripts/build-release.ts scripts/check-release-config-compiler.ts scripts/check-config-compiler-cli.ts tests/config-compiler-build.test.ts tests/native-config-compiler.test.ts tests/native-config-command.test.ts tests/native-config-dto.test.ts tests/native-project-inputs.test.ts tests/native-project-inputs-acquisition-race.test.ts tests/release-download-installer.test.ts
+          bunx ultracite check scripts/build-lifecycle-supervisor.ts scripts/check-release-lifecycle-supervisor.ts scripts/build-config-compiler.ts scripts/build-release.ts scripts/check-release-config-compiler.ts scripts/check-config-compiler-cli.ts tests/config-compiler-build.test.ts tests/native-config-compiler.test.ts tests/native-config-command.test.ts tests/native-config-dto.test.ts tests/native-project-inputs.test.ts tests/native-project-inputs-acquisition-race.test.ts tests/release-download-installer.test.ts
           bun test tests/config-compiler-build.test.ts tests/native-config-compiler.test.ts tests/native-config-command.test.ts tests/native-config-dto.test.ts tests/native-project-inputs.test.ts tests/native-project-inputs-acquisition-race.test.ts
           bun run --cwd packages/cli typecheck
           bun test tests/release-download-installer.test.ts
           bun run build:release --skip-tests --out=dist/config-compiler-release
           bun scripts/check-release-config-compiler.ts dist/config-compiler-release
+          bun scripts/check-release-lifecycle-supervisor.ts dist/config-compiler-release
           bun scripts/check-config-compiler-cli.ts
           bunx ultracite check scripts/check-native-env-plan-cli.ts tests/native-env-plan-transport.test.ts tests/native-env-metadata.test.ts
           bun test tests/native-env-plan-transport.test.ts tests/native-env-metadata.test.ts tests/project-env-config.test.ts tests/project-env-metadata.test.ts
@@ -650,7 +651,7 @@ jobs:
             --tag hack-runtime-ci:slim
       - name: Smoke slim runtime image defaults
         run: |
-          docker run --rm --entrypoint sh hack-runtime-ci:slim -lc 'command -v bun >/dev/null && command -v hack >/dev/null && test "${HACK_EXECUTION_MODE}" = "codex" && test "${HACK_DAEMON_DISABLE_DOCKER_EVENTS}" = "1" && hack --help >/tmp/hack-help.txt && grep -q "Usage:" /tmp/hack-help.txt'
+          docker run --rm --entrypoint sh hack-runtime-ci:slim -lc 'command -v bun >/dev/null && command -v hack >/dev/null && test -x /usr/local/bin/hack-lifecycle-supervisor && test "${HACK_EXECUTION_MODE}" = "codex" && test "${HACK_DAEMON_DISABLE_DOCKER_EVENTS}" = "1" && hack --help >/tmp/hack-help.txt && grep -q "Usage:" /tmp/hack-help.txt'
       - name: Smoke slim runtime mounted-project env flow
         run: bash scripts/portable-container-smoke.sh hack-runtime-ci:slim linux/amd64
 

.github/workflows/release.yml

@@ -121,6 +121,8 @@ jobs:
         run: bun run build:release "--version=$RELEASE_VERSION" --skip-tests
       - name: Qualify installed release compiler without host runtimes or network
         run: bun scripts/check-release-config-compiler.ts dist/release
+      - name: Qualify installed lifecycle supervisor
+        run: bun scripts/check-release-lifecycle-supervisor.ts dist/release
       - name: Upload tarball
         env:
           GH_TOKEN: ${{ github.token }}

.hack/README.md

@@ -16,6 +16,7 @@ hack run --profile toolchain toolchain -- test
 hack run --profile toolchain toolchain -- check
 hack run --profile toolchain toolchain -- rust
 hack run --profile toolchain toolchain -- rust-check
+hack run --profile toolchain toolchain -- lifecycle-supervisor
 hack run --profile toolchain toolchain -- config-compiler
 hack run --profile toolchain toolchain -- build
 hack run --profile toolchain toolchain -- exec bun index.ts --help

.hack/tasks.json

@@ -34,7 +34,7 @@
         "inputs": [
           {
             "path": ".hack/toolchain/run.sh",
-            "sha256": "0690919e0937c49638ea1c8318d731df3c45df26c3865c6a37ae263e8854e6a5"
+            "sha256": "d71945600ee66cf53a2ffb23f7aa7603fd217fde8a6875e97668b72ccce4fad5"
           },
           {
             "path": ".hack/toolchain/Dockerfile",
@@ -97,7 +97,7 @@
         "inputs": [
           {
             "path": ".hack/toolchain/run.sh",
-            "sha256": "0690919e0937c49638ea1c8318d731df3c45df26c3865c6a37ae263e8854e6a5"
+            "sha256": "d71945600ee66cf53a2ffb23f7aa7603fd217fde8a6875e97668b72ccce4fad5"
           },
           {
             "path": ".hack/toolchain/Dockerfile",
@@ -154,7 +154,7 @@
         "inputs": [
           {
             "path": ".hack/toolchain/run.sh",
-            "sha256": "0690919e0937c49638ea1c8318d731df3c45df26c3865c6a37ae263e8854e6a5"
+            "sha256": "d71945600ee66cf53a2ffb23f7aa7603fd217fde8a6875e97668b72ccce4fad5"
           },
           {
             "path": ".hack/toolchain/Dockerfile",

.hack/toolchain/run.sh

@@ -20,6 +20,7 @@ case "$task" in
   check) install_deps; bun run typecheck; exec bun run check ;;
   rust-check) cargo fmt --manifest-path packages/runtime-core/Cargo.toml --check; exec cargo clippy --locked --manifest-path packages/runtime-core/Cargo.toml --target-dir /build/rust --all-targets --all-features --jobs 2 -- -D warnings ;;
   rust) exec cargo test --all-features --locked --manifest-path packages/runtime-core/Cargo.toml --target-dir /build/rust --jobs 2 "$@" ;;
+  lifecycle-supervisor) exec bun scripts/build-lifecycle-supervisor.ts ;;
   config-compiler)
     install_deps
     cargo fmt --manifest-path packages/config-compiler/Cargo.toml --check
@@ -30,6 +31,7 @@ case "$task" in
     ;;
   build)
     install_deps
+    bun scripts/build-lifecycle-supervisor.ts
     # Bun 1.3.9 stages in cwd; its cross-device fallback can emit zero-filled
     # executables when cwd is the host bind mount and dist is a named volume.
     cd /app/dist
@@ -38,5 +40,5 @@ case "$task" in
     exec /app/dist/hack --version
     ;;
   exec) exec "$@" ;;
-  *) echo "Tasks: models, install, test [paths], check, rust [args], rust-check, config-compiler, build, exec <command>" >&2; exit 2 ;;
+  *) echo "Tasks: models, install, test [paths], check, rust [args], rust-check, lifecycle-supervisor, config-compiler, build, exec <command>" >&2; exit 2 ;;
 esac

docker/slim-runtime/Dockerfile

@@ -1,5 +1,10 @@
 # syntax=docker/dockerfile:1.7
 
+FROM rust:1.97.1-slim-bookworm AS supervisor-build
+WORKDIR /src
+COPY packages/lifecycle-supervisor ./packages/lifecycle-supervisor
+RUN cargo +1.97.1 build --locked --release --jobs 2 --manifest-path packages/lifecycle-supervisor/Cargo.toml --target-dir /build
+
 FROM oven/bun:1.4.4 AS hack-build
 
 WORKDIR /src
@@ -33,8 +38,9 @@ RUN apt-get update \
   && rm -rf /var/lib/apt/lists/*
 
 COPY --from=hack-build /out/hack /usr/local/bin/hack
+COPY --from=supervisor-build /build/release/hack-lifecycle-supervisor /usr/local/bin/hack-lifecycle-supervisor
 
-RUN chmod +x /usr/local/bin/hack \
+RUN chmod 755 /usr/local/bin/hack /usr/local/bin/hack-lifecycle-supervisor \
   && mkdir -p /var/lib/hack /workspace
 
 ENV HOME=/var/lib/hack

docs/guides/prereleases.md

@@ -265,3 +265,24 @@ exec, run, restart and retaining shutdown, then exercise its browser sign-in,
 data-backed pages and assets. Record the bundle version and source commit with
 the result. Unit tests, hosted CI and a responding health endpoint do not replace
 that application check.
+
+### Lifecycle supervisor packaging
+
+New release archives include `hack-lifecycle-supervisor` beside the CLI. The
+standard and slim installers install it with executable mode 0755; Homebrew keeps
+it beside `libexec/hack`. Source installs prepare it with
+`bun run build:lifecycle-supervisor` (Rust 1.97.1, locked dependencies).
+The slim runtime image includes the same sibling executable.
+
+Stable archives build it for macOS arm64/x86_64 and Linux arm64/x86_64. Existing
+prerelease bundles remain macOS arm64 only: their supervisor is ad-hoc signed and
+covered by the bundle checksums. Retained managers accept older bundles without
+this helper. Packaging does not change the lifecycle runner default.
+
+Self-upgrades stage the helper before publishing the CLI, retain its previous
+bytes and SHA-256 in the backup, and restore it if publication fails.
+Before publishing anything, a self-upgrade asks the staged CLI which helper
+handshake it requires and refuses the release, leaving the installation
+unchanged, if the staged helper is missing or answers differently. Releases
+whose CLI predates the helper are still accepted. Keep the
+helper with its matching CLI when moving an installation.

docs/versions/v5/install.md

@@ -110,3 +110,24 @@ anything, run `hack update --check --json --observe` through the same launcher;
 it prints the upgrade command for this install.
 For a candidate rollback or return to stable, use
 [the full procedure](../guides/candidate-install.md#upgrade-roll-back-and-return-to-stable).
+
+### Lifecycle supervisor packaging
+
+New release archives include `hack-lifecycle-supervisor` beside the CLI. The
+standard and slim installers install it with executable mode 0755; Homebrew keeps
+it beside `libexec/hack`. Source installs prepare it with
+`bun run build:lifecycle-supervisor` (Rust 1.97.1, locked dependencies).
+The slim runtime image includes the same sibling executable.
+
+Stable archives build it for macOS arm64/x86_64 and Linux arm64/x86_64. Existing
+prerelease bundles remain macOS arm64 only: their supervisor is ad-hoc signed and
+covered by the bundle checksums. Retained managers accept older bundles without
+this helper. Packaging does not change the lifecycle runner default.
+
+Self-upgrades stage the helper before publishing the CLI, retain its previous
+bytes and SHA-256 in the backup, and restore it if publication fails.
+Before publishing anything, a self-upgrade asks the staged CLI which helper
+handshake it requires and refuses the release, leaving the installation
+unchanged, if the staged helper is missing or answers differently. Releases
+whose CLI predates the helper are still accepted. Keep the
+helper with its matching CLI when moving an installation.

index.ts

@@ -1,5 +1,9 @@
 #!/usr/bin/env bun
 
+import {
+  LIFECYCLE_SUPERVISOR_HANDSHAKE_ARGUMENT,
+  LIFECYCLE_SUPERVISOR_VERSION,
+} from "./src/lib/lifecycle-supervisor-handshake.ts";
 import {
   finishNativeCpuDiagnostics,
   initializeNativeCpuDiagnostics,
@@ -25,6 +29,11 @@ if (Bun.argv[2] === NATIVE_DETACHED_OWNER_ARGUMENT) {
   );
 }
 
+if (Bun.argv[2] === LIFECYCLE_SUPERVISOR_HANDSHAKE_ARGUMENT) {
+  process.stdout.write(`${LIFECYCLE_SUPERVISOR_VERSION}\n`);
+  process.exit(0);
+}
+
 if (Bun.argv[2] === TTY_SUPERVISOR_ARGUMENT && process.send) {
   process.exit(await runTtySupervisor());
 }

package.json

@@ -16,6 +16,7 @@
     "dev": "bun run --cwd packages/cli dev",
     "build": "bun run --cwd packages/cli build",
     "build:local": "sh scripts/build-hack-local.sh",
+    "build:lifecycle-supervisor": "bun scripts/build-lifecycle-supervisor.ts",
     "build:config-compiler": "bun scripts/build-config-compiler.ts",
     "check:config-compiler": "cargo fmt --manifest-path packages/config-compiler/Cargo.toml --check && cargo clippy --locked --manifest-path packages/config-compiler/Cargo.toml --target-dir .hack-local/config-compiler-target --all-targets --jobs 2 -- -D warnings",
     "test:config-compiler": "bash scripts/test-rust.sh --crate=config-compiler",

packages/cli/package.json

@@ -6,12 +6,12 @@
   "module": "index.ts",
   "scripts": {
     "dev": "bun run ../../index.ts",
-    "build": "cd ../.. && bun build index.ts --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig --no-compile-autoload-tsconfig --no-compile-autoload-package-json --outfile dist/hack",
+    "build": "cd ../.. && bun scripts/build-lifecycle-supervisor.ts && bun build index.ts --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig --no-compile-autoload-tsconfig --no-compile-autoload-package-json --outfile dist/hack",
     "build:release": "cd ../.. && bun run scripts/build-release.ts",
     "build:runtime-image": "cd ../.. && bun run scripts/build-node-runtime-image.ts",
     "build:node-runtime-image": "cd ../.. && bun run scripts/build-node-runtime-image.ts --variant node-runtime",
     "build:slim-runtime-image": "cd ../.. && bun run scripts/build-node-runtime-image.ts --variant slim",
-    "install:dev": "cd ../.. && bun run scripts/install-cli.ts --mode=dev --force",
+    "install:dev": "cd ../.. && bun scripts/build-lifecycle-supervisor.ts && bun run scripts/install-cli.ts --mode=dev --force",
     "install:bin": "cd ../.. && bun run scripts/install-cli.ts --mode=bin --force",
     "install:status": "cd ../.. && bun run scripts/install-status.ts",
     "uninstall:local": "cd ../.. && bun run scripts/uninstall-cli.ts",

scripts/build-lifecycle-supervisor.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+import { chmod, copyFile, mkdir, mkdtemp, rename, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { verifyConfigCompilerBuildPath } from "./build-config-compiler.ts";
+
+/** Build the host sibling with locked dependencies and bounded Cargo parallelism. */
+export async function buildLifecycleSupervisor(): Promise<void> {
+  const root = resolve(import.meta.dir, "..");
+  const target = join(root, ".hack-local/lifecycle-supervisor-target");
+  const output = join(root, "dist/hack-lifecycle-supervisor");
+  for (const path of [
+    join(root, ".hack-local"),
+    target,
+    join(root, "dist"),
+    output,
+  ]) {
+    await verifyConfigCompilerBuildPath({ path });
+  }
+  const child = Bun.spawn(
+    [
+      "cargo",
+      "+1.97.1",
+      "build",
+      "--locked",
+      "--release",
+      "--jobs",
+      "2",
+      "--manifest-path",
+      "packages/lifecycle-supervisor/Cargo.toml",
+      "--target-dir",
+      target,
+    ],
+    {
+      cwd: root,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      timeout: 300_000,
+    }
+  );
+  if ((await child.exited) !== 0) {
+    throw new Error("Lifecycle supervisor build failed.");
+  }
+  const binary = join(target, "release/hack-lifecycle-supervisor");
+  await verifyConfigCompilerBuildPath({
+    path: binary,
+    allowCargoHardLink: true,
+  });
+  await mkdir(join(root, "dist"), { recursive: true });
+  const stage = await mkdtemp(join(root, "dist/.lifecycle-supervisor-build-"));
+  try {
+    const staged = join(stage, "hack-lifecycle-supervisor");
+    await copyFile(binary, staged);
+    await chmod(staged, 0o755);
+    if (process.platform === "darwin") {
+      for (const args of [
+        ["--force", "--sign", "-"],
+        ["--verify", "--strict"],
+      ]) {
+        const signature = Bun.spawn(["/usr/bin/codesign", ...args, staged], {
+          stdin: "ignore",
+          stdout: "inherit",
+          stderr: "inherit",
+          timeout: 30_000,
+        });
+        if ((await signature.exited) !== 0) {
+          throw new Error(
+            "Lifecycle supervisor signature verification failed."
+          );
+        }
+      }
+    }
+    // A locally installed helper may still be supervising work. Replace its
+    // directory entry instead of writing to that running executable's inode.
+    await verifyConfigCompilerBuildPath({ path: output });
+    await rename(staged, output);
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  await buildLifecycleSupervisor();
+}

scripts/build-native-candidate.sh

@@ -118,6 +118,11 @@ if [ -n "$version" ]; then
 else
   bun build index.ts --compile --outfile "$out/hack-cli"
 fi
+bun scripts/build-lifecycle-supervisor.ts
+cp dist/hack-lifecycle-supervisor "$out/hack-lifecycle-supervisor"
+chmod 755 "$out/hack-lifecycle-supervisor"
+/usr/bin/codesign --force --sign - "$out/hack-lifecycle-supervisor"
+/usr/bin/codesign --verify --strict "$out/hack-lifecycle-supervisor"
 bun scripts/build-config-compiler.ts
 cp dist/hack-config-compiler "$out/hack-config-compiler"
 cp packages/config-compiler/generated/hack.project.schema.json "$out/hack.project.schema.json"
@@ -158,7 +163,7 @@ fi
   else
     shasum -a 256 hack-native hack-relay-guest hack-storage-root-witness native-storage-tool.json hack-cli hack-v5 provider-pins.json README.md > SHA256SUMS
   fi
-  shasum -a 256 hack-config-compiler hack.project.schema.json hack.local.schema.json >> SHA256SUMS
+  shasum -a 256 hack-lifecycle-supervisor hack-config-compiler hack.project.schema.json hack.local.schema.json >> SHA256SUMS
   shasum -a 256 mcp/*/manifest.json mcp/*/hack-mcp-adapter mcp/*/hack-mcp-owner mcp/*/hack-mcp-backend >> SHA256SUMS
 )
 echo "Candidate bundle: $out"

scripts/build-release.ts

@@ -10,6 +10,7 @@ import {
   renderProjectManagedEnvSchemaJson,
 } from "../src/templates.ts";
 import { buildConfigCompiler } from "./build-config-compiler.ts";
+import { buildLifecycleSupervisor } from "./build-lifecycle-supervisor.ts";
 
 interface BuildArgs {
   readonly outDirRaw: string | null;
@@ -80,6 +81,7 @@ async function main({ args }: { readonly args: BuildArgs }): Promise<number> {
   }
 
   await buildConfigCompiler();
+  await buildLifecycleSupervisor();
   const binaryPath = resolve(distRoot, "hack");
   const buildExit = await run({
     cmd: [
@@ -112,6 +114,14 @@ async function main({ args }: { readonly args: BuildArgs }): Promise<number> {
   });
   await chmodExecutable({ path: compilerPath });
 
+  await copyFile({
+    from: resolve(distRoot, "hack-lifecycle-supervisor"),
+    to: resolve(releaseDir, "hack-lifecycle-supervisor"),
+  });
+  await chmodExecutable({
+    path: resolve(releaseDir, "hack-lifecycle-supervisor"),
+  });
+
   const assetsDir = resolve(releaseDir, "assets");
   const gifsDir = resolve(assetsDir, "gifs");
   const schemasDir = resolve(assetsDir, "schemas");
@@ -390,6 +400,7 @@ export function renderInstallScript(): string {
     ...installExecutableFunction(),
     'mkdir -p "$INSTALL_BIN" "$INSTALL_ASSETS"',
     'install_executable "$ROOT/hack-config-compiler" "$INSTALL_BIN/hack-config-compiler"',
+    'install_executable "$ROOT/hack-lifecycle-supervisor" "$INSTALL_BIN/hack-lifecycle-supervisor"',
     'install_executable "$ROOT/hack" "$INSTALL_BIN/hack"',
     "",
     'if [ -d "$ASSETS_DIR" ]; then',
@@ -516,6 +527,7 @@ export function renderCodexSlimInstallScript(): string {
     ...installExecutableFunction(),
     'mkdir -p "$INSTALL_BIN" "$INSTALL_ASSETS"',
     'install_executable "$ROOT/hack-config-compiler" "$INSTALL_BIN/hack-config-compiler"',
+    'install_executable "$ROOT/hack-lifecycle-supervisor" "$INSTALL_BIN/hack-lifecycle-supervisor"',
     'install_executable "$ROOT/hack" "$REAL_BIN"',
     "",
     'if [ -d "$ASSETS_DIR" ]; then',