feat(setup): stream versioned apply events

.github/skills/zi-install/SKILL.md

@@ -102,14 +102,15 @@ Drive the engine only from a local `src` tree or a same-revision companion bundl
 - **Directory artifacts:** Commands communicate through private directory artifacts with fixed relative paths containing raw bytes or restricted tokens (avoiding shell-level JSON escaping). Each destination must not exist, and its immediate parent must already exist and be writable:
   - `setup.sh describe --output DIR`: Publishes a `zi-setup-describe-v1` artifact containing `facts/` and `profiles/` (`loader` and `annex`; legacy `zunit` is marked `selectable=no` if detected). Exits 3 if all profiles are blocked.
   - `setup.sh plan --plan DIR`: Publishes a deterministic `zi-setup-plan-v1` artifact containing `plan.id`, `plan.meta`, `checkout/`, `targets/`, `operations/`, and `warnings/`.
-  - `setup.sh apply --plan DIR --phase checkout|files [--expect SHA256] [--result DIR]`: Applies the plan phase-by-phase.
+  - `setup.sh apply --plan DIR --phase checkout|files [--expect SHA256] [--result DIR] [--events DIR]`: Applies the plan phase-by-phase.
 - **Exact plan-id approval:** The plan hash covers all artifact files except `plan.id`. Clients must record the reviewed `plan.id` and pass it via `--expect` for both checkout and files phases. Changed artifact content produces `plan-changed`; changed live checkout or file preconditions produce `checkout-drift` or `target-drift`.
 - **Result artifacts:** Passing `--result DIR` to `apply` publishes a `zi-setup-result-v1` artifact containing `format`, `plan.id`, `phase`, `status` (`succeeded`, `failed`, `cancelled`), and `operations/`. Failures also contain `error/code` and `error/detail`, plus `error/operation` when attributable to one operation. A successful files phase contains `receipt/path`.
+- **Streaming event artifacts:** Passing optional `--events DIR` to `apply` publishes observational `zi-setup-event-v1` events as atomic numbered directories (`000001`, `000002`, ...) containing `format`, `phase`, `operation`, `status` (`started`, `succeeded`, `failed`), and `detail`. Each event is staged in a private hidden directory (`.tmp-event.*`) and renamed into place. Events provide operational progress, but process completion remains authoritative; do not parse stdout or stderr. Ordinary cancellation after an operation starts publishes a terminal `failed` event, though callers must observe the cancellation-publication limit: if a signal interrupts event publication itself, the terminal event may be omitted while cleanup and exit status 6 remain.
 - **Stable exit statuses and error codes:**
-  - Exit statuses: `0` (success), `2` (invocation or unsupported version), `3` (non-actionable discovery/plan), `4` (reviewed state or lock precondition changed, including plan, checkout, target drift, or lock contention), `5` (apply operation began but did not complete), `6` (cancelled).
+  - Exit statuses: `0` (success), `2` (invocation, unsupported version, or event directory initialization/path refusal), `3` (non-actionable discovery/plan), `4` (reviewed state or lock precondition changed, including plan, checkout, target drift, or lock contention), `5` (apply operation began but did not complete, or event publication failed after start), `6` (cancelled).
   - Error codes (`error/code`): stable ASCII identifiers including `unsupported-version`, `plan-changed`, `target-drift`, `checkout-drift`, `lock-held`, `network-failed`, `checkout-failed`, `write-failed`, and `cancelled`.
 - **Untrusted display text:** Operation summaries and warnings are display text. Clients must treat them as untrusted terminal content and strip or visibly escape control sequences. Decisions must rely solely on IDs and restricted tokens, never on display text.
-- **Do not parse human stdout/stderr:** Engine stdout and stderr are strictly for user presentation or diagnostics; their wording carries no compatibility promise. Never parse human stdout or stderr to make decisions; consume only documented directory artifacts and exit statuses.
+- **Do not parse human stdout/stderr; process completion is authoritative:** Engine stdout and stderr are strictly for user presentation or diagnostics; their wording carries no compatibility promise. Never parse human stdout or stderr to make decisions; consume only documented directory artifacts and exit statuses. Process completion remains authoritative.
 
 ## Verify
 

contracts/installer-contract-v1.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "contract_version": 2,
+  "contract_version": 3,
   "evidence_reviewed": "2026-09-20",
   "renames": [],
   "surfaces": [
@@ -45,7 +45,7 @@
       "path": "docs/getting_started/01_installation.mdx",
       "scope": "external",
       "evidence_status": "published",
-      "evidence": "https://github.com/z-shell/wiki/blob/293d23e6238b50bda15ac85b7f8fa9bdbc95be66/docs/getting_started/01_installation.mdx",
+      "evidence": "https://github.com/z-shell/wiki/blob/d4a2849d5e571bf20b170e04d356b065bb385e6f/docs/getting_started/01_installation.mdx",
       "surfaces": [
         "cli-profile-behavior",
         "output-status-messages",
@@ -59,7 +59,7 @@
       "path": ".github/skills/zi-install/SKILL.md",
       "scope": "external",
       "evidence_status": "published",
-      "evidence": "https://github.com/z-shell/.github/blob/ce74af22db3af827eed9558596275cdf3fb07505/.github/skills/zi-install/SKILL.md",
+      "evidence": "https://github.com/z-shell/.github/blob/04fabd632012e00c825b50df0fd8f621d17c9f82/.github/skills/zi-install/SKILL.md",
       "surfaces": [
         "cli-profile-behavior",
         "output-status-messages",
@@ -112,7 +112,7 @@
       "path": "README.md",
       "scope": "external",
       "evidence_status": "published",
-      "evidence": "https://github.com/z-shell/zi/blob/67fbb057fe05bc5664c0e558185a18b34a81defb/README.md",
+      "evidence": "https://github.com/z-shell/zi/blob/2fd78914149a94fe4fe12cf94c132a5736bd4506/README.md",
       "surfaces": ["cli-profile-behavior", "companion-asset-checksum"]
     }
   ]

docs/README.md

@@ -52,7 +52,13 @@ profile installs Zi without changing `.zshrc`.
 The source-adjacent [Zi Setup TUI contract](zi-setup-tui-contract.md) defines
 the machine interface and acceptance boundary for a future guided terminal
 client. The client offers `loader` and `annex`; `zunit` remains
-compatibility-only for existing installer output.
+compatibility-only for existing installer output. Callers can optionally pass
+`setup.sh apply --events DIR` to stream observational `zi-setup-event-v1`
+atomic numbered directories (`000001`, `000002`, ...). Process completion
+remains authoritative; do not parse stdout or stderr, and clients must account
+for the cancellation-publication limit where a signal interrupting event
+publication itself may omit the terminal event while cleanup and exit status 6
+remain.
 
 ## Repository layout
 
@@ -79,7 +85,7 @@ sh public/sh/generate-checksums.sh
 git diff --exit-code -- public/checksum.txt
 ```
 
-GitHub Actions exercises the installer and loader on Linux, macOS, and Cygwin.
+GitHub Actions exercises the installer and loader on Linux and macOS.
 Merges to `main` publish `public/` through GitHub Pages, and the loader-drift
 workflow verifies that the deployed loader matches its source and checksum.
 

docs/zi-setup-tui-contract.md

@@ -55,10 +55,10 @@ setup.sh describe --output DIR [--zi-home DIR] [--zi-bin-dir NAME]
                   [--skip-zshrc]
 setup.sh plan --plan DIR [existing options]
 setup.sh apply --plan DIR --phase checkout|files [--expect SHA256]
-               [--result DIR]
+               [--result DIR] [--events DIR]
 ```
 
-`describe` performs bounded read-only discovery. It does not source `.zshrc`, `init.zsh`, Zi, or plugins. It still publishes a describe artifact when all profiles are blocked, then exits with status 3. `plan` remains deterministic for the same filesystem inputs and selected options. `apply` continues to validate the complete plan and relevant preconditions before mutation. When `--result` is present, it publishes a result for validation failures, completed phases, operation failures, and cancellation. Omitting `--result` preserves the existing shell interface.
+`describe` performs bounded read-only discovery. It does not source `.zshrc`, `init.zsh`, Zi, or plugins. It still publishes a describe artifact when all profiles are blocked, then exits with status 3. `plan` remains deterministic for the same filesystem inputs and selected options. `apply` continues to validate the complete plan and relevant preconditions before mutation. When `--result` is present, it publishes a result for validation failures, completed phases, operation failures, and cancellation. When `--events` is present, it publishes machine-readable streaming events for active operations into a private directory. Omitting `--result` and `--events` preserves the existing shell interface.
 
 Human-readable stdout and stderr remain available for direct shell use. Their wording is not part of the interface contract.
 
@@ -144,15 +144,44 @@ receipt/path                       # present after successful files phase
 
 `operations/order` contains the phase operation when execution reached or completed that operation, and is empty for a global failure. `error/operation` is omitted when the failure is not attributable to an operation, including unsupported versions, changed plan content, and a lock already held before the operation begins.
 
-The first pilot may publish the result only when a phase exits. Streaming operation events are deferred until real UI testing shows they are needed. The TUI displays the planned operation name while a phase runs and shows sanitized subprocess logs in an optional details view.
+When `--events` is omitted, the engine publishes results only at phase completion or failure. When `--events DIR` is provided, the engine additionally publishes machine-readable streaming events for each active operation as described below.
+
+### Streaming event artifact
+
+`zi-setup-event-v1` defines the streaming event directory contract published under `setup.sh apply ... --events DIR`:
+
+```text
+format
+phase
+operation
+status
+detail
+```
+
+- `DIR` is created by the engine with mode `0700`. The path must be absolute, must not already exist, must not be a symlink, and must have a writable parent directory. Event initialization or invalid path failures are refused with exit status 2 before apply begins, whereas publication failures after an operation has started exit with status 5. No root-level files are written to `DIR`.
+- Each event is published atomically as a directory under `DIR` named with a six-digit sequence (`000001`, `000002`, ...). Each event is staged under a hidden temporary directory (`.tmp-event.*`) inside `DIR`, all fields are written, and the completed directory is renamed into place.
+- All event files are restricted single-line text ending in a newline:
+  - `format`: `zi-setup-event-v1`
+  - `phase`: `checkout` or `files`
+  - `operation`: the current stable plan operation ID (`checkout-sync` or `write-files`)
+  - `status`: `started`, `succeeded`, or `failed`
+  - `detail`: bounded static display text safe under artifact rules (no newlines, tabs, or control characters).
+- Lifecycle:
+  - `started` is published immediately before executing the selected operation.
+  - `succeeded` is published only after that operation completes.
+  - `failed` is published from the existing error path when an event operation is active.
+  - Ordinary cancellation after an operation has `started` publishes `failed`, removes staging directories, and exits 6. In the narrow limit where a signal interrupts event publication itself, the terminal event may be omitted while cleanup and exit 6 remain.
+  - Duplicate terminal events (`succeeded` or `failed`) are prevented.
+  - If a failure occurs before an operation begins (e.g. invalid arguments, unsupported version, plan hash mismatch, or a held lock), no event operation is active and no event directories are published.
+- Events are observational only: they do not change plan IDs, result contracts, exit codes, stdout, stderr, mutation order, or rollback behavior.
 
 ### Exit status contract
 
 - `0`: requested operation succeeded; its result artifact is complete when `--result` was requested.
-- `2`: invocation or unsupported interface version.
+- `2`: invocation, unsupported interface version, or event directory initialization/path refusal.
 - `3`: discovery or planning cannot produce an actionable artifact.
 - `4`: a plan, checkout, or file precondition changed.
-- `5`: an apply operation began but did not complete.
+- `5`: an apply operation began but did not complete, or event publication failed after start.
 - `6`: the user or supervising process cancelled the operation.
 
 The result artifact carries the specific reason. The exit status only selects the broad recovery path.

public/checksum.txt

@@ -1,6 +1,6 @@
 6de66efba021ebcf462e7672577d9f6876f13db55691f04e7009ff7e78d658b8 public/sh/install_zpmod.sh
 e322f6aea1c7878bdf6d12032fbb83528f7bbccb4738748335373d0c8380cbe5 public/sh/install.sh
-59307dc8e9aa43f35e137913cf41d8916acc6278a0e03ccb365a0ab01e003bae public/sh/setup.sh
+3fe433ed5b2fa9b3e12239b0bc4db75eea1bf4d8714220817c0575b3aa3875a2 public/sh/setup.sh
 08cc893ceb982fc99d17db1966c6c30790cc571e16e4f5392352d995f5252952 public/sh/sync-init.sh
 fff8d1c340fb1e87c76f80cac2224e28761ccc7e2b117839b7be6f5311a1ac11 public/setup/profiles.tsv
 c979e39748d1d86ace17a61ff2b1bf6e1224a43291c25bf7fad985d1e9e11af1 public/zsh/init.zsh

public/index.html

@@ -290,6 +290,25 @@ <h1>Z-Shell / src</h1>
               </button>
             </li>
           </ul>
+          <div style="margin-top: 20px">
+            <span class="prompt">❯</span>
+            <span class="command">setup.sh apply --events DIR</span>
+          </div>
+          <div
+            style="
+              margin-top: 8px;
+              color: var(--text-muted);
+              font-size: 12px;
+              line-height: 1.5;
+            "
+          >
+            Optional <code>setup.sh apply --events DIR</code> publishes
+            <code>zi-setup-event-v1</code> atomic numbered directories. Process
+            completion is authoritative; do not parse stdout or stderr. Callers
+            must account for the cancellation-publication limit where a signal
+            interrupting publication may omit the terminal event while cleanup
+            and exit status 6 remain.
+          </div>
           <div style="margin-top: 16px">
             <span class="prompt">❯</span> <span class="blink">_</span>
           </div>