[roodboi]

Summary

HACK-2189 is the first unit of the upgrade assistant (HACK-2188) and the foundation the later units build on. The goal: moving a machine from v4 to v5 becomes one guided, resumable and reversible flow, replacing a hand-written rollback sheet. This PR adds a read-only check, a snapshot and rollback library, and three commands on top of them.

flowchart LR
  C["hack upgrade check<br/>(read-only)"] -->|blockers| F[fix the named blocker] --> C
  C -->|plan| S["hack upgrade snapshot"] --> A["plan steps<br/>(later: hack upgrade apply)"]
  A -->|undo| R["hack upgrade rollback<br/>--rollback-manifest"]

Loading

hack upgrade check [--json]

It checks the machine and every registered project.

Machine:

• The running version and channel (stable or next; candidate launcher).
• The hack on PATH: its version and install kind.
• hackd: whether it runs, who runs it, and whether a login service is registered (systemd or launchd).
• The projects registry. Dead entries (the checkout, its .hack/, or all of hack.config.json, hack.toml and docker-compose.yml are gone) are counted apart from live entries that cannot be read. Dead ones point at hack projects prune --dry-run.
• Hack's global proxy and DNS (installed and running), the fix(compose): verify loopback proxy reachability #773 loopback proxy ports check, and the Linux DNS route.
• The global secret store and key. It reuses the feat(secrets): retire a store whose key is gone, and fail doctor only where the store is read (HACK-2177) #779 code, and reads the key file directly, so it never prompts the keychain.

Per live checkout (each project's primary checkout and each registered linked worktree):

• Env format: YAML layers, legacy JSON, legacy dotenv, or a conflict.
• Env key: present, private and untracked (doctor's key audit).
• Tracked machine-local or sensitive files, and the committed .hack/.gitignore.
• Agent integration files (hack setup state).
• On Apple Silicon, the native preflight verdict. It runs in-process only and is never a blocker, because native is optional.

Output: an ordered plan and the single next command. Blockers come first, then hack upgrade snapshot, then machine steps, then project steps. The command exits 0 when nothing blocks. Otherwise it exits 1 and names the blockers. A blocker is something that would make the upgrade fail or lose data:

• an env layer conflict;
• a tracked secret key, or an env key error;
• an unreadable or invalid registry;
• a global store whose key is gone while a registered project reads it.

Changes nothing: no file, registry, service, container or key is written, started or provisioned, and nothing prompts. A test compares the whole fixture tree (paths, modes, digests) before and after. Doctor functions with side effects are avoided:

• globalStatus/ensureDockerRunning can start Docker;
• hack projects touches the registry;
• the native runtime review spawns the binary and writes a temporary directory.

collectProjectNativePreflight is split out of the doctor command so the report can be collected without printing it or running the runtime review.

Fast: dead entries cost one stat. Live projects are checked eight at a time, with an 8-second limit per check and a shared 24-second budget. When the budget runs out, the remaining checks report "not checked" rather than running. Host probes have time limits too. An 80-entry fake registry (76 dead) finished its checks in about 130 ms.

Hermetic:

• Every host probe is injected: Docker, the resolver, service managers, the PATH hack and native preflight.
• HACK_HOST_PROBES_DISABLE=1 refuses them all and is set by the test preload, like HACK_SYSTEMD_DISABLE.
• A refused or failed probe reports "not checked", never a pass.

Snapshot and rollback library: src/lib/upgrade-snapshot.ts

The API is posted in a comment for HACK-2191: #790 (comment). It is modelled on the hack setup migrate backup manifest, with these differences:

• No content in the manifest. It holds only path, label, kind (file | absent), size, mode and SHA-256, before and after. Bytes live in content-addressed blobs/<sha256>, because env files hold secrets.
• Private storage outside every working tree. Directories are 0700 and files 0600, created with no-follow exclusive opens and owner-checked on every read. A snapshot root inside a Git working tree is refused. Manifest writes are atomic: temporary file, fsync, rename.
• All or nothing. A link, directory, unreadable or oversized target refuses the whole snapshot before anything is written.
• Restore puts back exact bytes and modes. It writes a no-follow temporary file and renames it over the target.
• It refuses a target that changed since the step recorded it (recordUpgradeSnapshotAfter) unless told to overwrite. A target with no recorded after state also needs overwrite.
• It never deletes. What it replaces or removes is kept in the snapshot and named in keptAs.
• It is idempotent, and reports every target it could not restore with a closed reason.

Commands

• hack upgrade snapshot [--json] keeps:

  • the global config, the registry, and the secret store and key (when a file store is used);
  • per live checkout: the env migration's write set, which is its .hack/ config, env contract, Compose file, dotenv files, YAML layers (the base, machine-local and per-overlay layers it would create, recorded as absent when they don't exist yet), .hack/.gitignore and in-checkout env key files.

  It skips links. Printed commands run the CLI that produced them: during the prerelease, the hack-next launcher, with HACK_RUNTIME_BACKEND=compose for a Compose run.

• hack upgrade rollback --rollback-manifest <manifest> [--overwrite] [--json] restores the files. Without a manifest it lists the snapshots and changes nothing, because non-interactive mode never guesses.

Docs

• The upgrade guide gains a "Check first" section.
• docs/cli.md lists the commands.
• docs/reference/cli.md is regenerated.

Validation

• New tests in tests/upgrade-snapshot.test.ts and tests/upgrade-check.test.ts (19, all passing), using a temporary HOME. No Docker, no daemon autostart, no real home or registry. They cover:
  • snapshot, then mutate, delete and create, then rollback: byte-for-byte equal with exact modes; the created file moved aside and kept; idempotent;
  • refusal on a changed target; overwrite keeps the edit; a target with no after state; a race during restore;
  • unsafe targets and roots; a non-private manifest; a damaged blob;
  • sentinel values absent from every manifest, result and report, with storage modes 0700/0600;
  • dead vs unreadable registry entries: 79 entries, 77 dead; a TOML-only or Compose-only project counts as live;
  • plan ordering; ready with an empty plan; secret-store blocker only when a project reads the store;
  • the check changes nothing (whole-tree digest); disabled or failing probes report not checked; the time budget;
  • tracked files, ignore rules and a tracked secret key in a real temporary Git repo;
  • CLI: check exits 1 naming blockers, and snapshot → mutate → rollback refuses without --overwrite and restores with it.
• Related suites: 143 pass across 11 files. The one failure is "recovers a confirmed dead registry owner", which times out on this host on next as well, plus the unhandled error it leaves behind.
• Gates: typecheck clean; check at the 44-warning baseline (none in touched files); docs:prepare then docs:check pass; privacy ok; gitleaks clean.

Review round 2 (head 3118605): what changed

• Readiness: ready needs no blockers and no incomplete checks. A required check that fails or times out, disabled host probes, a key only the keychain could confirm, or a registry cut short by the deadline are all incomplete. The exit code is 1 when not ready. A live checkout whose config cannot be read blocks.
• Commands vs actions: commands are built from the running CLI's prefix plus separately quoted arguments, never by rewriting text, so a path containing " hack " survives. Plan steps carry a command or a manual action. next_command is null when the first step is manual, and next_action then says what to do. The snapshot step now comes first.
• Global key: read-only inspectStoreKeyState follows the runtime's order and refusals (env key, then the key file through the runtime's reader: link, mode, Git tracking). It never asks the keychain. An absent store is not a lost key.
• Snapshot coverage: it includes the migration's own overlay selection, so layers for overlays only the secret store holds are recorded as absent. When those can only be listed through the keychain, the snapshot reports the gap.
• Restore never loses an edit: the current entry is displaced by one rename to an invocation-owned sibling and its exact bytes are kept. Publication uses a hard link that refuses an occupied target, and a late edit is put back. Unknown restore paths are rejected. The manifest directory is fsynced, and the single-writer rule is documented.
• One deadline, no stray children: the 25 s budget covers the registry read, classification, probes and checks. Config inputs must be regular files (no-follow, non-blocking, bounded). A new withProcessDeadline (AsyncLocalStorage) caps exec and the Git probes, so every child a check starts ends with that check. Previously unbounded Git calls in shared helpers (readGitPath, the generated-files ls-files, three ignore/tracking probes) now have 10 s limits, which helps doctor too.
• Tests: 32 upgrade tests, including late-replacement races, store-only overlays, key audits, a FIFO config, hanging Git with child-death checks, and quoting through a real shell split. A 64-file related slice has only the failures that also occur on a clean next checkout on this host (adopted-project doctor tests, registry lock timing).

Limits and follow-ups

• The daemon finding reports the owner and registration. Handover is the next unit.
• hack upgrade snapshot does not cover the daemon's unit or plist or Docker state; the guide says so.
• Native preflight is the in-process part only.
• The check is not timed on a real 80-entry machine; the fixture measurement is above.
• Env-key remedies are relative to the project root, so the plan step is hack doctor --path <root> and the remedy is in the finding text.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hack-docs	Ready	Preview	Nov 14, 2026 12:32am UTC

[linear-code]

HACK-2189

[roodboi]

Snapshot and rollback API, for HACK-2191 (env migration) and a later hack upgrade apply. It's in src/lib/upgrade-snapshot.ts at 9ffb447, tested in tests/upgrade-snapshot.test.ts. The shape below is what I intend to keep. I'll post here before any change to it.

import {
  createUpgradeSnapshot,      // before the step: snapshot every file it may touch (all or nothing)
  recordUpgradeSnapshotAfter, // after the step (or after each write): record what it wrote
  restoreUpgradeSnapshot,     // put everything back
  readUpgradeSnapshot, listUpgradeSnapshots, defaultUpgradeSnapshotRoot,
} from "../lib/upgrade-snapshot.ts";

// 1. Before changing anything. List every path the step may write, create or remove:
//    a path that does not exist yet is recorded as absent.
const created = await createUpgradeSnapshot({
  purpose: "env-migration app-a",          // no values
  targets: [
    { path: "/abs/repo/.hack/hack.env.json", label: "project app-a: hack.env.json" },
    { path: "/abs/repo/.hack/.env",          label: "project app-a: .hack/.env" },
    { path: "/abs/repo/.hack/hack.env.yaml", label: "project app-a: hack.env.yaml" }, // absent now
  ],
  // root?: string   default ~/.hack/upgrade/snapshots (private, outside any Git working tree)
});
if (created.status !== "created") {
  // { status: "refused", reason: "targets", targets: [{ path, label, reason }] }
  //   reason: not-absolute | duplicate | symlink | not-a-file | too-large | unreadable | inside-snapshot-root
  // { status: "refused", reason: "root", root, rootReason }
  //   rootReason: inside-working-tree | not-private | not-owned | symlink | not-a-directory | unwritable
  // Nothing was written. Do not run the step.
}
const { manifestPath } = created.snapshot; // .../<id>/manifest.json

// 2. Run the step, then record what it wrote (all targets, or `paths`).
await recordUpgradeSnapshotAfter({ manifestPath /*, paths?: string[] */ });
// -> { status: "recorded" } | { status: "invalid-manifest", message } | { status: "refused", paths: [{ path, reason }] }

// 3. Roll back.
const result = await restoreUpgradeSnapshot({ manifestPath /*, overwrite?: boolean, paths?: string[] */ });
// -> { status: "invalid-manifest", message }
//  | { status: "restored" | "incomplete", results: [{ path, label, status, keptAs?, message? }] }

Per-target restore statuses

• restored: the snapshot's exact bytes and mode are back.
• moved-aside: the target was absent at snapshot time; the file the step created is moved into the snapshot directory.
• already-restored: the target already matches the snapshot. This makes restore idempotent.
• conflict: the target changed since the step recorded it, or nothing was recorded for it. It is left unchanged; overwrite: true restores it anyway.
• not-a-file: a link, directory or other entry is at the target. It is left unchanged, even with overwrite.
• backup-damaged: the snapshot's copy is missing or fails its digest check.
• error: the restore failed at this path.

Guarantees you can rely on

• No values in metadata. The manifest holds only path, label, kind (file | absent), size, mode and SHA-256 per target, before and after. Bytes live only in blobs/<sha256>. Results and messages carry paths, labels, statuses and closed strings. Keep labels and purpose value-free.
• Private storage. Directories are 0700 and files 0600, created with no-follow exclusive opens. Every read checks the owner and that the file is private. Manifest writes are atomic: temporary file, fsync, rename.
• "Changed since" is measured against the recorded after state. Call recordUpgradeSnapshotAfter right after the step writes, or after each write for multi-file steps. A target with no after state restores only with overwrite, which covers an interrupted step.
• Restore never deletes data. Anything it replaces or removes is first kept as a blob in the snapshot directory, and the result names it in keptAs. Each target is re-checked immediately before it is replaced.
• Not transactional. Restore is not atomic across targets or against a concurrent editor, and it reports per target. It creates a missing parent directory (0700) when it puts a file back.
• Size limit. 64 MiB per file; larger targets refuse the snapshot.

Commands on top of this (hack upgrade snapshot / --rollback-manifest-style restore) come in the next commits of this PR.

[roodboi]

@codex review

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-13T22:16:21.658527Z	1d2803e	Manual request
🔒 Security Review	✅ Completed 2026-11-13T22:19:54.667860Z	1d2803e	Manual request

Security findings

Advisory findings (1)

• 🟡 Refuse environment-selected Git worktrees before snapshotting · Medium

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[roodboi]

HACK-2191 is binding to the posted snapshot API behind a small adapter. One additional contract would help keep cleanup inside the snapshot owner: can you export a read-only coverage verifier that accepts a manifest and selected paths and validates each original blob as well as the manifest? readUpgradeSnapshot currently validates metadata only, while finish must prove the files it removes remain recoverable. I can compare the returned original path/kind/size/mode/SHA-256 with the migration journal. I will call recordUpgradeSnapshotAfter after each known publication and after cleanup, and keep rollback guarded against journal-recorded current checksums. The new env preview is names/paths/counts/checksums only; raw payloads remain private outside working trees.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b011e0c944

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f77d7b0c80

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ab1e18769a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: ab1e18769a

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3118605844

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 3118605844

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

@codex review

[roodboi]

HACK-2191 integration note: env rollback now deliberately retains project keys (including a newly created git-common-dir key), because another checkout may already use one for its ciphertext. It also retains the corresponding root ignore entry when needed. Its snapshot adapter filters these targets and restores only journal-guarded selected paths. Please keep this invariant in the generic rollback entry point too: a manifest with purpose env-migration should route users to hack env migrate --rollback-manifest <path>, rather than restoring all absent targets and moving away a live shared key.

The env adapter also supports an explicit --preserve-changes recovery option: it admits the freshly observed changed bytes only on that request, records that revision, and relies on the provider to retain replaced bytes privately. Default rollback still refuses later edits. No values go into output or metadata.

The small adapter is ready to bind statically once this library lands on next; production-provider and compiled-CLI integration remain gates on HACK-2191. The earlier request for a provider-owned original-blob coverage verifier still applies.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0733d15c45

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 049249eb01

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0614bc4b23

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64fa4716d1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[roodboi]

@codex review

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Here are some automated security review suggestions for this pull request.

Reviewed commit: b97c9f0538

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

@codex review

[roodboi]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 1d2803e5fd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 1d2803e5fd

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

Snapshot and rollback library: current public interface (at c0f7d1e). This replaces the earlier API comment and is the version HACK-2191, HACK-2213/2216 and HACK-2214 should code against. Module: src/lib/upgrade-snapshot.ts. Everything is read-only except create, recordAfter and restore.

import {
  createUpgradeSnapshot,      // before a step: snapshot every path it may write, create or remove
  recordUpgradeSnapshotAfter, // after the step (or after each write): record what it wrote
  restoreUpgradeSnapshot,     // roll back
  readUpgradeSnapshot,        // validate and read one manifest
  listUpgradeSnapshots,       // newest first
  defaultUpgradeSnapshotRoot, // <hack home>/upgrade/snapshots
  MAX_SNAPSHOT_FILE_BYTES,    // 64 MiB per file
} from "../lib/upgrade-snapshot.ts";

createUpgradeSnapshot({
  purpose: string,                                   // e.g. "env-migration app-a" (no values)
  targets: readonly { path: string; label: string }[], // absolute paths; labels hold no values
  root?: string,                                     // default defaultUpgradeSnapshotRoot()
  now?: Date, id?: string,                           // test seams
}) → { status: "created", snapshot: { id, dir, manifestPath, manifest } }
   | { status: "refused", reason: "targets", targets: [{ path, label, reason }] }
     //   reason: not-absolute | duplicate | symlink | not-a-file | too-large | unreadable | inside-snapshot-root
   | { status: "refused", reason: "root", root, rootReason }
     //   rootReason: inside-working-tree | not-private | not-owned | symlink | not-a-directory | unwritable

recordUpgradeSnapshotAfter({ manifestPath, paths?: string[], now? })
  → { status: "recorded", snapshot } | { status: "invalid-manifest", message }
  | { status: "refused", paths: [{ path, reason }] }   // throws on a path that is not a target

restoreUpgradeSnapshot({ manifestPath, overwrite?: boolean, paths?: string[] })
  → { status: "invalid-manifest", message }
  | { status: "restored" | "incomplete", results: [{ path, label, status, keptAs?, message? }] }
  //   throws on a path that is not a target

What a snapshot holds: a private directory <root>/<id>/ (0700, outside any Git working tree) containing:

• manifest.json (0600, atomic writes). Per target it holds the path, label, and before/after states. Each state is either { kind: "file", size, mode, sha256 } or { kind: "absent" }. It never holds file content.
• blobs/<sha256> (0600): the bytes of each before file.
• staging/ and displaced/: used by restore.

All snapshot creation is all or nothing: a refused target refuses the whole snapshot and nothing is written. A path that doesn't exist yet is recorded as absent, so restore can move away what a step creates there.

How rollback is called and behaves:

• When to record after: call recordUpgradeSnapshotAfter right after the step writes. A target is put back only if it still holds what the step wrote, or already matches the snapshot. Otherwise the result is conflict, unless overwrite: true. A target with no recorded after state also needs overwrite; that covers an interrupted step.
• Never deletes.
  • What restore replaces or removes is moved, as the same file, into displaced/ (one atomic rename) and named in keptAs.
  • Publication is a hard link from staging/, which refuses an occupied name.
  • A late edit is linked back into place and reported as conflict.
  • No temporary or displaced file is ever written beside a target in your checkout.
• Per-target statuses:
  • restored;
  • moved-aside (the target was absent in the snapshot);
  • already-restored (idempotent);
  • conflict;
  • not-a-file (kept in displaced/);
  • backup-damaged;
  • error, with closed messages: target on another filesystem than the snapshot, no hard links, GIT_DIR/GIT_WORK_TREE set, or publication failed (the file is put back, or named in keptAs).
• Same filesystem required: a target must be on the snapshot's filesystem, or it is refused untouched. A caller can pass root to keep a snapshot beside the files it covers.
• One writer per snapshot: two concurrent recordUpgradeSnapshotAfter calls on one snapshot can lose each other's updates.

The CLI on top:

• hack upgrade snapshot [--json] is built on collectUpgradeSnapshotTargets() in src/lib/upgrade-snapshot-targets.ts. It returns { targets, skipped, gaps }.
• hack upgrade rollback --rollback-manifest <path> [--overwrite].
• hack upgrade check puts hack upgrade snapshot first in its plan.

Not covered yet (for HACK-2213/2216 to add through this interface): the snapshot does not cover:

• the daemon's login service unit files: the launchd plist ~/Library/LaunchAgents/dance.hack.hackd.plist and the systemd user unit ${XDG_CONFIG_HOME:-~/.config}/systemd/user/hackd.service;
• daemon state under ~/.hack/daemon/ (pid, socket, log);
• the Git index, services and containers.

To include the unit files, pass them as targets, absent ones included, before rewriting a unit. A file-level rollback restores the unit's bytes only: reloading or restarting the service manager after a restore is the caller's step. Daemon runtime state such as pid and socket is not meaningful to restore; a caller should stop or restart the daemon instead.

[roodboi]

Ready for lead: head c0f7d1e (HACK-2189). This includes next b1e123b via normal merges.

• Persistent second-family reviewer: CLEAN at c0f7d1e (and at every head since b97c9f0). Its remaining follow-ups belong to the apply unit:
  • persist snapshot coverage and gaps in the apply journal;
  • keep timing claims qualified for disk I/O already in progress, which cannot be cancelled.
• Codex review and Codex security review: both clean at 1d2803e. After that, only conflict-free merges of next.
• Bot threads: computer pr review-status gives CLEAR at c0f7d1e. Every bot finding was fixed and answered; one thread I resolved early by mistake was answered afterwards.
• CI at c0f7d1e: every job passed except test shard 2/8 (macos-15). All Linux test shards, all four docker-e2e shards, the config compiler and candidate core on every OS, runtime-images, linux-process-lifetime, models, docs and secret-scan are green.
• The macOS failure: tests/python-free-download.test.ts ("five-file official sequence shares a monotonic total and bounded cleanup: cleanup"). It tests download and installer code that came from next; this PR does not touch it. It passes 3 out of 3 times locally. The aggregate test job is red only because of that shard.
• Snapshot library interface for HACK-2191, HACK-2213/2216 and HACK-2214: feat(upgrade): read-only upgrade check and snapshot/rollback library (HACK-2189) #790 (comment). It does not yet cover the login service units or daemon state, and the comment says how to add them.

Not merged.