roodboi · Nov 14, 2026 · Nov 14, 2026 · Nov 14, 2026 · Nov 14, 2026 · Nov 14, 2026
diff --git a/docs/always-on-projects.md b/docs/always-on-projects.md
diff --git a/docs/cli.md b/docs/cli.md
@@ -7,6 +7,7 @@ terminal).
 
 ## Core commands
 
+- `hack autostart add|remove|list|pause|resume` — choose [always-on projects](always-on-projects.md) for this machine; `hack up -d --always` marks and starts one. `down` pauses its next login start; `up` resumes it.
 - `hack init` — generate `.hack/` (compose + config); `--with claude|codex` also hands off to
   agent-assisted onboarding
 - `hack up` / `hack down` / `hack restart` — start, stop and restart the project

diff --git a/docs/diagrams/autostart-login.mmd b/docs/diagrams/autostart-login.mmd
@@ -0,0 +1,44 @@
+---
+title: Autostart at login
+---
+sequenceDiagram
+  autonumber
+  participant Login
+  participant Daemon
+  participant Engine
+  participant Registry
+  participant CLI
+  participant User
+  Login->>Daemon: Start user service
+  Daemon->>Registry: Read machine markers
+  alt Globally paused
+    Daemon->>Daemon: Skip automatic starts
+  else Automatic starts enabled
+    Daemon->>Registry: Begin login progress
+    Daemon->>Engine: Backoff wait, ten-minute bound
+    alt Engine unavailable
+      Daemon->>Registry: Waiting, no boot claims
+      Engine-->>Daemon: Later healthy observation
+    end
+    opt Routing already installed
+      Daemon->>CLI: global up, no interaction
+    end
+    loop Unpaused projects in stable order
+      Daemon->>Registry: Claim once per boot
+      Daemon->>Engine: Inspect required services
+      alt Confirmed stopped
+        Daemon->>CLI: up -d in independent Linux scope
+        CLI->>Registry: Lock instance, recheck intent
+        CLI->>Registry: Recheck before containers start
+        CLI-->>Daemon: Result without prompts
+      else Running or unknown
+        Daemon->>Daemon: Adopt or skip
+      end
+      Daemon->>Registry: Save result and progress
+    end
+    Daemon->>Registry: Finish login progress
+  end
+  User->>Registry: down publishes pause
+  User->>CLI: Wait for instance lock
+  CLI-->>User: Earlier startup settles
+  User->>Engine: Stop project under lock
diff --git a/docs/diagrams/autostart-login.svg b/docs/diagrams/autostart-login.svg
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -8,6 +8,180 @@ Run `hack help <command>` for the same content in the terminal. Global options:
 
 ## Project
 
+## `hack autostart`
+
+Manage always-on projects on this machine
+
+### Usage
+
+```bash
+hack autostart <subcommand> [options]
+```
+
+### Subcommands
+
+| Command | Summary |
+| --- | --- |
+| `hack autostart add [project]` | Start this registered project at login on this machine |
+| `hack autostart remove [project]` | Remove this project's machine autostart marker |
+| `hack autostart list` | List this machine's always-on projects |
+| `hack autostart pause [project]` | Pause one marked project, or all marked projects |
+| `hack autostart resume [project]` | Resume one marked project, or all marked projects |
+| `hack autostart run` | Intentionally run one non-interactive autostart pass |
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart add [project]`
+
+Start this registered project at login on this machine
+
+### Usage
+
+```bash
+hack autostart add [project] [options]
+```
+
+### Arguments
+
+| Arg | Description |
+| --- | --- |
+| `project` |  |
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
+| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart remove [project]`
+
+Remove this project's machine autostart marker
+
+### Usage
+
+```bash
+hack autostart remove [project] [options]
+```
+
+### Arguments
+
+| Arg | Description |
+| --- | --- |
+| `project` |  |
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart list`
+
+List this machine's always-on projects
+
+### Usage
+
+```bash
+hack autostart list [options]
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart pause [project]`
+
+Pause one marked project, or all marked projects
+
+### Usage
+
+```bash
+hack autostart pause [project] [options]
+```
+
+### Arguments
+
+| Arg | Description |
+| --- | --- |
+| `project` |  |
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart resume [project]`
+
+Resume one marked project, or all marked projects
+
+### Usage
+
+```bash
+hack autostart resume [project] [options]
+```
+
+### Arguments
+
+| Arg | Description |
+| --- | --- |
+| `project` |  |
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack autostart run`
+
+Intentionally run one non-interactive autostart pass
+
+### Usage
+
+```bash
+hack autostart run [options]
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--json` | Output JSON (machine-readable) |
+| `--engine-wait-ms <ms>` | Engine readiness wait bound (1-3600000 ms; default 600000) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+
 ## `hack project`
 
 Inspect or manage project metadata
@@ -188,6 +362,7 @@ hack up [services...] [options]
 | `--target <auto|local|remote>` | Execution target routing (auto routes to remote when project execution mode requires it) |
 | `--json` | Output JSON (machine-readable) |
 | `--progress` | With --json: stream ndjson progress lines before the result envelope (Compose backend) |
+| `--always` | Mark this project for machine-local autostart and start it |
 | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
 | `--help, -h` | Show help |
 | `--version, -v` | Show version |

diff --git a/docs/reference/machine-readable-output.md b/docs/reference/machine-readable-output.md
@@ -52,6 +52,12 @@ success behavior stays covered by command-specific suites.
 | Canonical command / variant | Success shape |
 |---|---|
 | `hack activity --json` | Envelope; versioned `data.schema`: `hack.activity.v1` |
+| `hack autostart add --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
+| `hack autostart list --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
+| `hack autostart pause --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
+| `hack autostart remove --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
+| `hack autostart resume --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
+| `hack autostart run --json` | Envelope; versioned `data.schema`: `hack.autostart.v1` |
 | `hack commands cancel --json` | Envelope (`ok`, `data` / `error`); legacy payload has no required schema |
 | `hack commands read --json` | NDJSON events / terminal event, not a single envelope |
 | `hack commands show --json` | Envelope (`ok`, `data` / `error`); legacy payload has no required schema |

diff --git a/docs/reference/v5-model-coverage.md b/docs/reference/v5-model-coverage.md
@@ -36,6 +36,7 @@ must be attached to the eventual exact integration revision.
 
 | Property and critical states | Model coverage | Implementation/regression boundary | Remaining qualification |
 | --- | --- | --- | --- |
+| Machine autostart intent, pause, per-boot claim and startup replay | [Start/stop lock model](../../tests/models/tla/autostart-start-stop/COVERAGE.md): a completed down prevents a prior login child from starting; negative control releases the lock early | `projects-registry.ts` persists claims before dispatch; login CLI holds the instance lock and rechecks trusted intent under it and before container publication; `down` pauses before waiting and stops under that lock. `autostart-lifecycle-intent.test.ts` holds a fake start across real source `down`; `autostart-project-lock.test.ts` covers target/pause guards and scope serialization. Daemon regressions cover delayed engine readiness without consumed claims, stable order, stagger, cap and service-only dispatch | One start child and one down, 41 distinct model states; at most two dispatched starts, configurable ten-minute engine wait, one claim per project/boot. Model assumes an effect-capable child retains its lock through settlement; it does not prove OS orphan cleanup, Docker's asynchronous engine work or filesystem durability. Real isolated Linux user-manager helper survival across service restart passed; real macOS login, cold engine and keychain behavior remain external qualification. |
 | Standalone lifecycle supervisor: durable pre-launch identity, retained guard lock, project-supervisor loss, separately lost guard, verified stop and unknown stop | [lifecycle-supervisor](../../tests/models/tla/lifecycle-supervisor/COVERAGE.md) | `packages/lifecycle-supervisor` and its fake-caller contract tests; no CLI integration or default change in this slice | One command name, at most two starts, matching/foreign/unknown/reused-SID identities, arbitrary process exit and supervisor/guard loss; 426 states. Negative control removes the live-session retry fence and violates `NoDuplicate`. Native PID identity, filesystem synchronization, descriptors, output and macOS effects require implementation tests. |
 | Opt-in lifecycle controller: pending ownership before launch, stable native owner across adoption, cleanup epochs, publication after a lost reply and serialized add/stop | [lifecycle-controller](../../tests/models/tla/lifecycle-controller/COVERAGE.md) | `project-lifecycle-supervisor.ts`, `lifecycle-supervisor.ts`, common lifecycle state publication and controller/incremental regressions | One instance, one creator plus one adopter, one initial launch plus one incremental add; 21 states. Negative controls remove the cleanup epoch fence (`NoAdoptedStop`) and pending publication fence (`DurableBeforeLaunch`). Atomic lock regions and trustworthy native readback are assumptions; process identity, sockets, cancellation latency and OS effects remain implementation tests. |
 | Env migration publication, crash/resume and later cleanup | [env-migration](../../tests/models/tla/env-migration/COVERAGE.md): 74 states, two steps per phase, deferred Compose repair, separate publication and receipt, safe pre-removal cleanup refusal; unsafe controls fail `NoSameRunCleanup` and `FreshRunProof` | `env-migration.ts` binds immutable payloads and source checksums to a private snapshot, adopts interrupted renames, records completion, admits later explicit Compose repair without republishing env layers, and requires a new successful project run plus fresh snapshot/delivery/live-input proofs for cleanup. Real-file tests check preview parity, sentinels, backup damage, consent, tighter modes, refused cleanup retry and rollback; owned child processes receive SIGKILL at initial and later journal/publication boundaries | The model assumes atomic per-file publication/journal writes and cooperative locks; it does not qualify fsync durability, real snapshot provider behavior, partial cleanup/rollback, unsynchronized writers, actual runtime environment or macOS. Implementation and dependency integration gates remain separate. |

diff --git a/docs/versions/v5/getting-started.md b/docs/versions/v5/getting-started.md
@@ -69,6 +69,24 @@ hack ps
 hack open
 ```
 
+To start this project at future logins, use `hack up -d --always` and install
+the per-user daemon with `hack daemon install`. `hack down` pauses its marker;
+`hack up` resumes it. See [Always-on projects](https://github.com/hack-dance/hack/blob/next/docs/always-on-projects.md) for
+the startup bounds, no-prompt behavior and JSON contract. Automatic startup requires
+trusted, non-writable-by-others tool and project paths; `hack doctor` reports
+permission refusals, including app-bundle and Homebrew paths on macOS.
+Formerly writable files require reviewed replacement on fresh private files;
+changing modes or ACLs in place cannot revoke an older open writer.
+This slice starts only eligible Compose projects with images already available
+locally. Hooks, host helpers, command providers and image builds require manual
+`hack up`; doctor explains those manual-start requirements.
+Retained projects created by `hack config adopt` also require manual starts.
+Host-file/source-code bind mounts also require manual starts. Verified default
+engine volumes and Hack's authenticated read-only TLS mounts remain supported.
+Interrupting `hack autostart run` cancels the pass and waits for startup cleanup.
+After upgrades that change global templates, run `hack global install` manually
+before relying on login routing.
+
 Expect the declared services in `ps` and the app's local URL from `open`.
 If a project has several URLs, choose the app's route. A worker-only project may
 have no URL. Sign in or load a page that reads data to check the app itself.
@@ -118,6 +136,28 @@ routing services. See [Run and inspect](guides/run-project.md) for service selec
 log history and restarts. When this Compose run works, try native only on a
 [disposable project](native/start.md).
 
+Always-on login restores Caddy/CoreDNS routing only. Logging (Grafana, Loki and
+Alloy) starts through manual `hack global up`; login leaves existing logging
+containers running. Change default Grafana credentials before network exposure.
+
+Login requires a non-SSH Docker transport and already-prepared DNS. It skips
+macOS dnsmasq startup and passwordless DNS recovery; use manual `hack global up`
+when DNS needs starting or recovery.
+The daemon service PATH is unchanged; only automatic-start children use the
+separately audited Docker user-bin path.
+Dotenv template and backup copies do not block always-on admission; active dotenv
+overlays still need migration, and Compose `env_file` inputs require manual starts.
+TCP Docker contexts require manual starts too; login accepts local Unix socket
+transports, without claiming TCP peer authentication.
+On Linux/macOS, login also requires a Unix socket under trusted parents; shared
+or sticky socket directories are refused before engine access.
+Writable sticky Docker plugin directories also refuse login startup, including
+empty directories where a plugin could be planted after an audit.
+Direnv files such as `.envrc` are not dotenv overlays and do not block admission.
+Prepare Caddy/CoreDNS images with manual `hack global up`: login routing never
+pulls or builds images and refuses missing local images.
+Machine-wide autostart progress is exposed locally, not through the unsupported gateway.
+
 Lifecycle host processes can opt into `lifecycle.runner: "supervisor"` when the
 Rust supervisor executable is installed alongside the CLI. The default stays
 `"mux"`. This mode has no terminal: use noninteractive commands and

diff --git a/docs/versions/v5/index.md b/docs/versions/v5/index.md
@@ -34,6 +34,7 @@ v5 prerelease bundles are Apple Silicon macOS only; see
 
 ## Do a task
 
+- [Start projects at login](https://github.com/hack-dance/hack/blob/next/docs/always-on-projects.md)
 - [Set up a Linux host](../guides/linux-setup.md): local DNS, trust and the daemon.
 - [Configure Linux certificate trust](../guides/linux-certificate-trust.md): distribution and browser trust stores.
 - [Upgrade a v4 machine to v5](guides/upgrade-from-v4.md): preparation, rollback and checks awaiting the dogfood run.

diff --git a/scripts/lib/tla-runtime-models.ts b/scripts/lib/tla-runtime-models.ts
@@ -141,6 +141,21 @@ const restartPolicyStaleUses = [
   { engine: "exited", bound: 3 },
 ] as const;
 const contracts: readonly ModelContract[] = [
+  {
+    name: "autostart-start-stop",
+    module: "StartStop",
+    states: 41,
+    invariant: "NoStartAfterSuccessfulDown",
+    action: "ChildStart",
+    fields: [
+      'holder = "none"',
+      "paused = TRUE",
+      'child = "started"',
+      "running = TRUE",
+      'down = "done"',
+      "lateStart = TRUE",
+    ],
+  },
   {
     name: "lifecycle-controller",
     module: "LifecycleController",