docs: audit next.17 release notes and upgrade guidance

docs/guides/native-candidate.md

@@ -4112,9 +4112,11 @@ command exit code, and never falls back to Compose. With piped input/output or
 `HACK_NO_INTERACTIVE=1`, it uses finite exec with a 30-second observation budget;
 a timeout may leave the command running and is not
 retried. `--env` and `--profile` changes are refused. A command name such as `bun`
-uses the selected container's PATH; no host PATH or implicit shell is used. Normal
-`hack exec` resolves the saved startup overlay and AWS profile again, and delivers
-fresh selected-service values through private stdin.
+uses the selected container's PATH; no host PATH or implicit shell is used. For
+adopted Compose services, `hack exec` resolves the saved startup overlay and AWS profile again, and delivers
+fresh selected-service managed, allowed caller-shell and env-file values through
+private stdin. These values can differ from startup; use `hack restart` when
+the running service must receive changed inputs too.
 Each request binds the reviewed plan, current container and generation, and has
 its own short ingress lifetime. Startup leases and files are not renewed or rewritten.
 The allocation is selected from the current container's exact read-only mounts and
@@ -4123,7 +4125,7 @@ by earlier restores do not compete with this selection; pending, mismatched or
 ambiguous mounted allocations are refused.
 Legacy mappings without explicit selectors and services with older launcher mounts
 refuse before execution; restart with the matching candidate to adopt this path.
-Services without managed values use ordinary exec. The native live qualification
+Services with no private values to deliver use ordinary exec. The native live qualification
 of this fresh-delivery path remains separate from its unit and transport tests.
 
 With terminal stdin and stdout in the foreground, `hack exec SERVICE -- /bin/sh` selects interactive

docs/native/limits.md

@@ -4,6 +4,9 @@ The native backend supports part of what Compose supports. When a project needs
 something outside that part, Hack refuses and tells you. It does not guess, and it
 does not fall back to Docker without telling you.
 
+The changes labelled next.17 below describe candidate source `5002cf87bb`.
+An installed next.16 bundle keeps its older behavior.
+
 ## Platform
 
 | Platform | Native backend |
@@ -22,7 +25,7 @@ does not fall back to Docker without telling you.
 | Stop the project | `hack down`, and `hack down --recover` after a crash |
 | See what is running | `hack ps` |
 | Read recent logs | `hack logs <service> --no-follow`, a bounded snapshot |
-| Run a command in a running service | `hack exec`, without an interactive terminal |
+| Run a command in a running service | Next.17: foreground terminal `hack exec SERVICE -- /bin/sh` is interactive; redirected input/output and `HACK_NO_INTERACTIVE=1` use finite exec |
 | Run a one-off command | `hack run`, for services without source, data or private env mounts |
 | Preview without starting | `hack config validate`, `hack config plan`, `hack config import --dry-run`, `hack config adopt --dry-run` |
 
@@ -49,7 +52,10 @@ The exact rules for each command are in
 - Proving a complete tail without transport EOF. A stopped service whose stream
   stays open for five idle seconds ends with `native_log_stopped_idle` and exit 1,
   not a clean EOF. The final tail may be incomplete.
-- Interactive `exec` sessions.
+- Interactive exec on an older next.16 bundle. Next.17 supports sized terminals,
+  resize and control bytes; old managed-env launchers require a matching restart
+  or finite exec. Inspect uncertain outcomes with `hack exec-sessions`; see
+  [exec recovery](../guides/native-candidate.md#normal-native-exec).
 - Changing the env overlay, profiles or target of a project that is already
   running. Stop it and start it again.
 - Starting or restarting single services. Native starts and restarts the whole
@@ -64,9 +70,9 @@ refuses with `E_NATIVE_PROJECT_UNSUPPORTED`, names the feature, and starts nothi
 
 | Compose feature | Why it stays on Compose |
 | --- | --- |
-| External networks | Native only uses networks it creates and owns |
+| Foreign external networks | Exact `hack-dev` and `hack-logging` identities map to project-owned bridges in next.17; they do not join Docker's shared networks or provide cross-project DNS |
 | External volumes | Native only uses volumes it creates and owns |
-| Labels Hack or Compose reserve | These labels prove which tool owns a resource |
+| Unsupported routing labels | Generated Hack/Compose metadata is inert in next.17; authored labels never grant resource ownership |
 | Builds beyond a basic `context`, `dockerfile` and `target` | Build arguments, secrets, SSH and cache options are not supported |
 | Platforms other than Linux arm64 | The virtual machine runs Linux arm64. `linux/amd64` works only for services you opt in to emulation. |
 
@@ -82,9 +88,12 @@ Details and the exact checks:
   mount a named volume at that path, for example `redis-data:/data`. Without one
   the project refuses with `graph_image_volume_uncovered`. A bind mount or a
   read-only mount there does not count.
-- **Stopping with Ctrl-C.** In this prerelease, Ctrl-C may not stop a foreground
-  project cleanly when it publishes ports. Use `hack down` from another terminal,
-  and `hack down --recover` if it reports that the owner is gone.
+- **Stopping with Ctrl-C.** The native publisher-shutdown fix (HACK-2087, #719)
+  already shipped in next.16. Next.17 adds lifecycle-command retirement fixes
+  (HACK-2184): transient reads retry, cleanup waits for proved command retirement,
+  and a second Ctrl-C can request the forced command-group stop. Unknown cleanup
+  still retains evidence. Use `hack down` from another terminal, then
+  `hack down --recover` if it reports the owner is gone; do not delete state.
 - **Images.** Images need a Linux arm64 variant. Local registries need an explicit
   opt-in. Registries signed by a private certificate authority are not supported.
 - **Data.** Data does not move between backends, or between prerelease versions.

docs/native/try-it.md

@@ -143,10 +143,12 @@ Native `up` runs in the foreground and holds the project until you stop it. Add
 "$HOME/.hack-next/bin/hack-next" down --path /absolute/project
 ```
 
-Stop the project with `hack down` from another terminal, as above. In this
-prerelease, Ctrl-C may not stop a foreground project cleanly when it publishes
-ports. If you already pressed Ctrl-C, run `hack down`, and `hack down --recover` if
-it reports that the owner is gone. A fix is in progress.
+Stop the project with `hack down` from another terminal, as above. The native
+publisher-shutdown fix (HACK-2087, #719) already shipped in next.16. Next.17 adds
+lifecycle-command retirement fixes (HACK-2184): transient reads retry and a second
+Ctrl-C can request the forced command-group stop. If cleanup is uncertain, run
+`hack down`, then `hack down --recover` if it reports that the owner is gone.
+Keep the receipts and follow the printed recovery procedure.
 
 Then check the application itself: sign in, load a page that reads data, restart,
 and confirm the data is still there. A green status alone does not prove the

docs/versions/v5/guides/upgrade-from-v4.md

@@ -12,6 +12,10 @@ project, the v4.2.1 path, env migration, data recovery or rollback. Those remain
 steps are **to be confirmed in the dogfood run**. Native setup and log following
 remain **under verification**.
 
+The next.17 additions below were checked against candidate source `5002cf87bb`.
+They do not change the next.16 trial record. The assistant now handles checks and
+selected file repairs; env migration and the runtime trial remain separate.
+
 ```mermaid
 ---
 title: Choose an upgrade path
@@ -64,6 +68,24 @@ Sources: [candidate channel contract](https://github.com/hack-dance/hack/blob/26
 
 ## 2. Before you start
 
+### Breaking change: zellij workspaces removed
+
+Next.17 requires tmux for interactive workspaces. Project/global
+`sessions.mux=zellij` and `HACK_SESSIONS_MUX=zellij` fail with migration guidance.
+Install tmux, then remove the setting and override or set the mode to `tmux`;
+`auto` detects tmux only. Existing zellij sessions are not stopped or migrated.
+
+After backing up, **before switching a project that used zellij lifecycle
+processes**, keep zellij installed and use the retained v4 CLI to run `hack down`
+for that project. Confirm its lifecycle processes stopped. If already upgraded,
+use the retained v4 CLI for that stop first. Then take a fresh private backup
+using the procedure below, keeping the earlier copy. Use the stopped-state copy
+for rollback so it does not restore live zellij state. Saved zellij lifecycle state blocks
+v5 start, restart and down: v5 cannot verify or stop it. Changing the setting
+alone does not clear saved state. Do not delete or edit managed state files.
+A leftover zellij setting also makes `hack global install` fail; fix it before
+retrying. A stale-state migration path remains separate lifecycle work.
+
 ### Check first
 
 v5 builds that include the upgrade assistant can check the machine before you
@@ -487,7 +509,7 @@ not prove the key survived. Implicit migration cleanup removes only migrated
 dotenv files, not the store's `keyPath`, but it still writes project state: keep
 the backup before env-consuming commands that can migrate automatically too.
 The section 2 template already saves the key privately as
-`$BACKUP/project-.hack.secret.key`, outside the working tree. A published fix
+`$BACKUP/project-.hack.secret.key`, outside the working tree. A fix
 for explicit Doctor cleanup is merged in
 [#769](https://github.com/hack-dance/hack/pull/769), intended for next.17.
 In a build containing that fix, project/shared env keys and current config/YAML
@@ -979,11 +1001,3 @@ Keep the printed resume and rollback commands for a custom `--snapshot-root`:
 ordinary snapshot listings scan only the default root. Resume preserves completed
 outcomes across interruption and refuses a damaged original blob even when its
 agent file has already been removed.
-
-## Breaking change: zellij workspaces removed
-
-v5 supports tmux for interactive workspaces. `sessions.mux=zellij` and `HACK_SESSIONS_MUX=zellij` now fail with migration guidance. Install tmux, then remove the setting or set it to `tmux`; `auto` detects tmux only. Existing zellij sessions are not stopped or migrated by Hack.
-
-**Before upgrading a project that used zellij for lifecycle processes:** with zellij installed, use the v4 CLI to run `hack down` for that project and confirm its lifecycle processes have stopped. Then switch to v5 and change the mux setting. Saved zellij lifecycle state blocks v5 start, restart and down because v5 cannot verify or stop that session. If already upgraded, use the retained v4 CLI to stop the affected project first; do not delete or edit managed state files. Removing a workspace setting alone does not clear saved lifecycle state. A stale-state migration path remains part of the lifecycle supervisor work.
-
-A leftover zellij setting also makes `hack global install` fail with the same migration guidance. Fix the setting before retrying.

docs/versions/v5/native/overview.md

@@ -8,6 +8,10 @@ Native setup and live log following are available in next.16 **under verificatio
 Real-VM acceptance remains pending; start with disposable projects and synthetic data.
 See [Prepare the runtime](setup.md) and [Follow service logs](log-follow.md).
 
+Next.17 source adds interactive exec, guarded Compose env-file reads and
+retirement fixes. These do not change an installed next.16 bundle; see
+[what changed and what to do](https://github.com/hack-dance/hack/blob/5002cf87bb50686b17ceae8a4c835f524ee1b3a5/docs/guides/v5-release-notes.md#next17-what-changed-and-what-to-do).
+
 ## What it is
 
 Hack needs something to run your services in. Today that is Docker Compose, which
@@ -99,7 +103,10 @@ What you give up today:
 - Following logs live as a verified native capability. `hack logs --follow` is
   available for testing; real-VM acceptance for authored and adopted projects
   is still pending.
-- Interactive shells in a container.
+- Interactive shells on next.16. Next.17 supports foreground terminal
+  `hack exec SERVICE -- /bin/sh`; redirects and `HACK_NO_INTERACTIVE=1` keep
+  finite exec. Use the matching runtime and follow its retained-session
+  recovery instructions after an uncertain outcome.
 - UDP ports.
 - Automatic restart for services that publish a port.
 

docs/versions/v5/native/start.md

@@ -88,6 +88,14 @@ If writable source sharing asks for consent, review the exact source roots and
 [sharing limits](full-reference.md#explicit-writable-development-source) before
 opting in. Check the app and saved data yourself; a running VM is not acceptance.
 
+In a build containing next.17's interactive exec, use
+`"$CANDIDATE" exec api -- /bin/sh` from a foreground terminal for a live shell.
+Terminal stdin and stdout are required; redirects or `HACK_NO_INTERACTIVE=1`
+select finite exec. Use the matching runtime, and restart old managed-env
+launchers if requested. After an uncertain outcome, inspect
+`"$CANDIDATE" exec-sessions` and follow the
+[next.17 source recovery instructions](https://github.com/hack-dance/hack/blob/5002cf87bb50686b17ceae8a4c835f524ee1b3a5/docs/guides/native-candidate.md#normal-native-exec).
+
 Stop with the **same version and native home**:
 
 ```sh

docs/versions/v5/upgrade.md

@@ -4,8 +4,9 @@ Start here: [1. Install](install.md) · [2. First project](getting-started.md) 
 **3. Upgrade** · [4. Try native](native/start.md).
 
 This is today's manual path. **To be replaced by the upgrade assistant**
-(HACK-2189 and HACK-2191, in progress). Until it lands, keep stable v4 installed
-and try v5 on one Compose project at a time. Native is a separate trial.
+(HACK-2189 and HACK-2191). Next.17 source already checks and repairs selected
+files; env migration and the runtime trial remain manual. Keep stable v4
+installed and try one Compose project at a time. Native is a separate trial.
 The published v5 candidate bundle requires an Apple Silicon Mac.
 
 ```mermaid
@@ -40,7 +41,15 @@ offered as Run. Host changes and decisions still need review.
    and confirm you can read the original key. If stable routing needs starting,
    run stable `command hack global up` before the backup procedure stops its daemon
    and copies the files.
-2. **Confirm stable's daemon stays stopped.** In a terminal where
+2. **Stop saved zellij lifecycle sessions before switching to v5.** Keep zellij
+   installed and use retained v4 `command hack down` for each affected project.
+   Confirm the lifecycle processes stopped, then take a **fresh backup** with the
+   step 1 procedure. Keep the earlier copy too; use the stopped-state backup for
+   rollback so it does not restore live zellij state. Next.17 requires tmux; remove
+   `sessions.mux=zellij` and `HACK_SESSIONS_MUX=zellij`, or select `tmux`.
+   Changing the setting alone does not clear saved state. See the
+   [stop procedure](guides/upgrade-from-v4.md#breaking-change-zellij-workspaces-removed).
+3. **Confirm stable's daemon stays stopped.** In a terminal where
    `hack` is the stable executable, run:
 
    ```sh
@@ -52,7 +61,7 @@ offered as Run. Host changes and decisions still need review.
    The last command must print nothing before you continue. On macOS uninstall
    removes the launchd service so it cannot restart the daemon during the trial.
    Run no stable commands while the candidate uses the shared home.
-3. **Install v5 beside stable**, following [Install](install.md). Use a fresh
+4. **Install v5 beside stable**, following [Install](install.md). Use a fresh
    terminal for the trial, select Compose, and check the chosen version:
 
    ```sh
@@ -63,15 +72,15 @@ offered as Run. Host changes and decisions still need review.
    hack doctor
    ```
 
-4. **Review env migration before accepting it.** `up` can offer migration;
+5. **Review env migration before accepting it.** `up` can offer migration;
    sessions and some env commands can migrate without a prompt. Keep backups
    before any of them. If explicit migration is needed, use
    `hack doctor --migrate-env-config` only after reading the
    [migration and consent details](guides/upgrade-from-v4.md#4-what-changes-for-a-project).
    On next.16 or earlier, cleanup can remove a project key a legacy store names:
    never run that repair without the private readable key copy. The merged fix
    intended for next.17 cannot recover an already deleted key.
-5. **Run the project and check it**, using `hack up --detach`, `hack open`,
+6. **Run the project and check it**, using `hack up --detach`, `hack open`,
    `hack logs --no-follow --tail 50` and `hack down`. Check sign-in, saved data,
    hooks and a restart. Keep the backup until rollback and data recovery have
    been checked. See [known problems](guides/upgrade-from-v4.md#known-problems-and-the-dogfood-record).