@kici-dev/compiler 0.1.21 → 0.1.22

package/dist/llm-context/llms-full.txt

@@ -576,7 +576,7 @@ export default workflow('ci', {
 });
 ```
 
-The `test` and `typecheck` jobs both depend on `lint`, so they run in parallel after lint succeeds. KiCI validates the dependency graph at compile time -- cycles and missing references are caught before you commit. At runtime, jobs are gated on upstream completion: a job only dispatches after every entry in its `needs` array reaches a terminal state. If an upstream fails, downstream jobs skip by default (override per-edge with `ifFailed: 'run'`). See [Job dependencies (`needs`)](../sdk/core.md#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, ifFailed }`, `dynamicGroup()`) and [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the dispatch semantics.
+The `test` and `typecheck` jobs both depend on `lint`, so they run in parallel after lint succeeds. KiCI validates the dependency graph at compile time -- cycles and missing references are caught before you commit. At runtime, jobs are gated on upstream completion: a job only dispatches after every entry in its `needs` array reaches a terminal status that satisfies the edge. If an upstream fails, downstream jobs skip by default (override per-edge with `when: 'always'`). See [Job dependencies (`needs`)](../sdk/core.md#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, when }`, `dynamicGroup()`) and [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the dispatch semantics.
 
 **Single-step jobs don't need a `steps` array.** When a job only does one thing, pass `run` to `job()` instead of wrapping it in `steps: [step(...)]`:
 
@@ -1109,6 +1109,116 @@ This workflow:
 
 ---
 
+## Host restart & wait-for-alive
+
+Source: https://docs.kici.dev/user/patterns/host-restart/
+
+When a KiCI agent runs on a host you are provisioning, a workflow can reboot
+that host and resume work once it comes back — the Ansible `reboot` +
+`wait_for_connection` pattern, expressed as two jobs pinned to the same host.
+
+## The two-job pattern
+
+Host restart is a **job-boundary** capability: the reboot is the last step of a
+"restart" job, and the post-restart work lives in a **separate job** pinned to
+the same host that `needs` the restart job. The orchestrator holds the
+post-restart job until the host completes a reboot cycle, then dispatches it.
+
+```typescript
+import { workflow, job, step, restartHost, waitForHostAlive } from '@kici-dev/sdk';
+
+export default workflow('patch-and-verify', {
+  on: [
+    /* ... */
+  ],
+  jobs: [
+    // Restart job: apply updates, then reboot. restartHost() MUST be the last step.
+    job('patch', {
+      runsOn: 'kici:host:box-01',
+      steps: [
+        step('upgrade', async (ctx) => {
+          await ctx.$`apt-get upgrade -y`;
+        }),
+        restartHost(),
+      ],
+    }),
+    // Post-restart job: pinned to the SAME host, needs the restart job.
+    job('verify', {
+      runsOn: 'kici:host:box-01',
+      needs: ['patch'],
+      steps: [
+        waitForHostAlive(() => fetch('http://localhost:8080/health')),
+        step('check-service', async (ctx) => {
+          await ctx.$`systemctl is-active myservice`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+## `restartHost()`
+
+`restartHost(opts?)` reboots the host the job runs on. It signals the
+orchestrator that a reboot is pending (which holds the post-restart job and
+treats the agent's imminent disconnect as expected, not a failure), reports the
+step success, and the agent issues the OS reboot once the step completes.
+
+- **Must be the last step** of its job — the job completes before the box goes
+  down.
+- `deadlineMs` (optional) overrides how long the orchestrator waits for the host
+  to return after the reboot. The default is the orchestrator's
+  `KICI_HOST_REBOOT_DEADLINE_MS` (15 minutes). If the host does not reconnect by
+  the deadline, the held post-restart job fails with a clear "host did not
+  return after reboot" reason.
+- The reboot command is chosen per operating system (Linux `systemctl reboot`,
+  macOS `shutdown -r now`, Windows `shutdown /r /t 0`).
+
+## `waitForHostAlive(probe, opts?)`
+
+`waitForHostAlive()` is the optional first step of the post-restart job. The
+baseline "the host is back" guarantee comes for free — the post-restart job only
+dispatches after the agent reconnects. `waitForHostAlive(probe)` adds a
+**service-readiness** gate on top: it polls `probe` until it resolves, for hosts
+where "agent connected" does not yet mean "services ready".
+
+- The probe can return anything (an HTTP response, an open port check, a marker
+  file). Any non-null resolution means "ready"; a throw or rejection keeps
+  polling.
+- `intervalMs` (default 3000) and `timeoutMs` (default 300000) tune the poll. If
+  the probe never succeeds within `timeoutMs`, the step fails with "services did
+  not come up".
+
+## Same-host pinning
+
+The "same host" relationship is the pin: both jobs target the same host via
+`runsOn` (a `kici:host:<id>` label or another label the host carries), and the
+post-restart job `needs` the restart job. Durable provisioning hosts MUST set a
+stable agent id (`KICI_AGENT_ID`) so the host re-registers under the same
+identity after the reboot — that stable identity is what lets the orchestrator
+recognise the down-then-up cycle and release the held job.
+
+## Failure behavior
+
+- **Host never returns by the deadline** → the held post-restart job fails.
+- **Reboot privilege denied** → the restart step fails with a clear privilege
+  error (see the operator note below), and the orchestrator clears the
+  reboot-pending hold.
+- **`waitForHostAlive` probe never succeeds** → that step fails.
+
+The orchestrator refuses to reboot the host it runs on, so a co-located agent
+cannot take down the orchestrator's own box.
+
+## Operator prerequisite: reboot privilege
+
+Rebooting needs host privilege. An agent used for host provisioning must be able
+to run the OS reboot primitive — run the agent service with reboot privilege, or
+grant a narrow `shutdown` / `systemctl reboot` permission. Agents used for
+provisioning generally need broad, near-root host privileges; see the operator
+agent documentation for the full posture.
+
+---
+
 ## Integration patterns
 
 Source: https://docs.kici.dev/user/patterns/integrations/
@@ -2489,9 +2599,9 @@ const test = job('test', { needs: [lint], ... });
 // 2. Reference by string name
 const test = job('test', { needs: ['lint'], ... });
 
-// 3. Object form with per-edge failure policy
+// 3. Object form with a per-edge run condition (`when`)
 const cleanup = job('cleanup', {
-  needs: [{ name: 'build', ifFailed: 'run' }],
+  needs: [{ name: 'build', when: 'always' }],
   ...
 });
 
@@ -2502,16 +2612,36 @@ const deploy = job('deploy', {
 });
 ```
 
-**Failure policy (`ifFailed`):** controls what happens to a downstream job when an upstream reaches a non-success terminal state (`failed`, `cancelled`, `drift_dropped`).
+**Run condition (`when`):** controls when a downstream edge is satisfied, based on the upstream's terminal status. `when` is keyword sugar (or a raw status-set) that resolves at compile time to the set of upstream terminal statuses that satisfy the edge. The downstream edge is satisfied when the upstream's terminal status is a member of that set.
 
-| Value  | Behavior                                                                                    |
-| ------ | ------------------------------------------------------------------------------------------- |
-| `skip` | (Default) Downstream transitions directly to `skipped`. Failures cascade through the DAG.   |
-| `run`  | Downstream dispatches anyway. Use for cleanup, notification, or "always-run" teardown jobs. |
+| Keyword                  | Satisfied when the upstream is… | Use for                                     |
+| ------------------------ | ------------------------------- | ------------------------------------------- |
+| `'on-success'` (default) | `success`                       | normal dependencies                         |
+| `'always'`               | any terminal status             | cleanup / notification / teardown jobs      |
+| `'on-skip'`              | `success` or `skipped`          | continue when an upstream was narrowed out  |
+| `'on-failure'`           | `failed` or `timed_out_stale`   | error-handler jobs that run only on failure |
 
-String and `Job`-reference entries default to `ifFailed: 'skip'`. To override, use the object form (`{ name, ifFailed }` for static upstreams, `{ group, ifFailed }` for dynamic groups -- `dynamicGroup(name, { ifFailed: 'run' })` produces the latter).
+For full control, pass a raw status-set instead of a keyword: `when: ['skipped', 'failed', 'timed_out_stale']`. The valid members are the terminal job statuses: `success`, `failed`, `cancelled`, `skipped`, `timed_out_stale`, `drift_dropped`.
 
-**Dispatch gate:** `needs` is a hard dispatch gate. A job only dispatches after every upstream in its `needs` array reaches a terminal state (success, or failure with `ifFailed: 'run'`). Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+String and `Job`-reference entries default to `when: 'on-success'`. To override, use the object form (`{ name, when }` for static upstreams, `{ group, when }` for dynamic groups -- `dynamicGroup(name, { when: 'always' })` produces the latter).
+
+When an upstream's terminal status is **not** in the edge's set, the downstream transitions directly to `skipped`. Because a skipped job is itself terminal, this propagates transitively: each downstream's `when` set governs whether the skip cascades further.
+
+**Dispatch gate:** `needs` is a hard dispatch gate. A job dispatches only after every upstream in its `needs` array reaches a terminal status that satisfies that edge's `when` set. Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+
+**Reading an upstream's status in a step:** inside a running job, `ctx.needs.<job>.status` exposes each upstream's terminal status (`success`, `failed`, `skipped`, …) and `ctx.needs.<job>.result` its outputs. A group / matrix / `runsOnAll` fan-out upstream is an ordered array of `{ name, result, status }`, one per child. Use this to branch in TypeScript:
+
+```typescript
+job('report', {
+  needs: [{ name: 'probe', when: 'always' }],
+  run: async (ctx) => {
+    if (ctx.needs.probe.status === 'failed') await fileIncident(ctx.needs.probe.result);
+    else await publish(ctx.needs.probe.result);
+  },
+});
+```
+
+For an arbitrary outcome-based gate that prevents a job from dispatching at all, use a result-aware `dynamicJob` that returns `[]` or `[job]` based on `ctx.needs.<job>.status` — see [Dynamic jobs](../../architecture/execution/dynamic-jobs.md).
 
 **DAG validation:** three-layer cycle detection.
 
@@ -2524,7 +2654,10 @@ String and `Job`-reference entries default to `ifFailed: 'skip'`. To override, u
 Create a reference to a dynamic job group, for use inside a static job's `needs` array.
 
 ```typescript
-function dynamicGroup(name: string, options?: { ifFailed?: 'skip' | 'run' }): DynamicGroupRef;
+function dynamicGroup(
+  name: string,
+  options?: { when?: 'on-success' | 'always' | 'on-skip' | 'on-failure' | string[] },
+): DynamicGroupRef;
 ```
 
 Use when a static downstream must wait for every generated job tagged with a given group name to complete. If the dynamic group produces zero jobs, the downstream dispatches immediately (empty group satisfies all upstreams).
@@ -3445,10 +3578,10 @@ export default workflow('discovery-fan-out', { jobs: [discover, reports] });
 
 `ctx.needs` shape:
 
-| Need form                                               | `ctx.needs[...]` value                                                                                                                                    |
-| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `'jobName'` / `{ name, ifFailed }`                      | `{ result }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`) |
-| `dynamicGroup('g')` / `dynamicGroup('g', { ifFailed })` | ordered array of `{ name, result }`, one per group member                                                                                                 |
+| Need form                                           | `ctx.needs[...]` value                                                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'jobName'` / `{ name, when }`                      | `{ result, status }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`); `status` is the upstream's terminal status |
+| `dynamicGroup('g')` / `dynamicGroup('g', { when })` | ordered array of `{ name, result, status }`, one per group member                                                                                                                                             |
 
 `ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first eval and replayed unchanged on re-eval, like `ctx.event`. Use result-aware generation for same-run fan-out from a prior job's result; use [`jobComplete()`](./triggers.md) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](../../architecture/execution/dynamic-jobs.md#result-aware-generation).
 
@@ -3685,6 +3818,32 @@ A held host occupies a wave slot indefinitely while it waits to reconnect, stall
 roll behind an absent box. `skip` (run only reachable hosts) or `fail` (refuse the roll
 if any expected host is down) keep the window moving.
 
+### Narrowing the roster at run time with `--target`
+
+A `runsOnAll` predicate is authored once in the workflow, but you can narrow it for a
+single run with `kici run --target <selector>` — an Ansible-`--limit`-style runtime
+filter. The effective host set becomes `runsOnAll ∩ target`: the selector can only
+_remove_ hosts from the matched roster, never add them. The narrowing is **run-global**
+(it applies to every `runsOnAll` job) and **`runsOnAll`-only** (single `runsOn`-pinned
+jobs are untouched). Repeated `--target` values AND-combine — a host must satisfy every
+selector to survive.
+
+```bash
+# Patch only the role:web subset of whatever role:* hosts the job would match
+kici run remote deploy --target role:web
+
+# Intersect two selectors: hosts must be BOTH role:web AND dc:eu
+kici run remote deploy --target role:web --target dc:eu
+```
+
+When `--target` narrows a `runsOnAll` job to zero hosts, the run **fails** by default
+(a mistyped selector should be loud, not silently no-op). Pass `--target-allow-empty`
+to **skip** the zeroed job instead — it records a `skipped` status, and downstream jobs
+gated with `when: 'on-skip'` (or `when: 'always'`) still run, exactly as for an
+`onUnreachable: 'skip'` zero-host fan-out. See the [CLI reference](/user/cli-reference/#host-narrowing-with---target)
+for the full flag behavior and the [`needs` gating model](./core.md#job-dependencies-needs)
+for how a skipped upstream propagates.
+
 ### Limits (v0)
 
 - Per-host secret scoping is not yet available — all hosts receive the job's resolved
@@ -5649,6 +5808,8 @@ kici run remote [fixture] [options]
 | `--history`                 | `false` | Show table of recent test runs                                                                    |
 | `--context <ctx.key=value>` | none    | Inject a namespaced context secret, uploaded encrypted (repeatable)                               |
 | `--env <KEY=VALUE>`         | none    | Provide a per-run secret, uploaded encrypted (repeatable) — see [testing guide](testing-guide.md) |
+| `--target <selector>`       | none    | Narrow `runsOnAll` jobs to hosts matching this label selector (repeatable, AND-combined)          |
+| `--target-allow-empty`      | `false` | A `--target` that narrows a `runsOnAll` job to zero hosts skips it instead of failing             |
 | `--debug`                   | `false` | Verbose internals                                                                                 |
 | `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                           |
 
@@ -5687,8 +5848,44 @@ kici run remote push-main --no-wait
 
 # View recent test run history
 kici run remote --history
+
+# Narrow runsOnAll jobs to a subset of the host roster
+kici run remote deploy --target role:web
+
+# AND-combine repeated --target values (hosts must match every selector)
+kici run remote deploy --target role:web --target dc:eu
+
+# Skip a runsOnAll job instead of failing it when the target matches no host
+kici run remote deploy --target role:gpu --target-allow-empty
 ```
 
+#### Host narrowing with `--target`
+
+`--target <selector>` is a runtime narrowing for `runsOnAll` jobs, analogous to
+Ansible's `--limit`. A `runsOnAll` job normally fans out to **every** roster host
+matching its predicate, one pinned execution per host. `--target` intersects that
+matched roster with a label selector, so the effective host set is
+`runsOnAll ∩ target`:
+
+- **Narrow-only.** `--target` can only _remove_ hosts from the matched set, never
+  add them. The widening dimension (OR across host groups) lives in the workflow's
+  `runsOnAll`; `--target` only subtracts.
+- **Run-global, `runsOnAll`-only.** A single `--target` applies to every
+  `runsOnAll` job in the run. Jobs pinned to a single host with `runsOn` are
+  untouched.
+- **Repeatable and AND-combined.** Each `--target` value is its own selector; a
+  host must satisfy **all** of them to survive the narrowing. Use a single value
+  for an OR-style match within one selector and repeated values for AND.
+- **Selector syntax** matches `runsOn`: an exact label (`role:web`), a glob
+  (`role:*`), or a regex (`/^box-0[1-3]$/`).
+
+When `--target` narrows a `runsOnAll` job to zero hosts, the default is to **fail**
+the run (fail-loud — a typo in the selector shouldn't silently skip work). Pass
+`--target-allow-empty` to **skip** the zeroed job instead; the job records a
+`skipped` status, and any downstream job that needs it with `when: 'on-skip'` (or
+`when: 'always'`) still runs. See [Job dependencies](./sdk/core.md#job-dependencies-needs)
+for the `when` gating model.
+
 **Exit codes:**
 
 | Code | Meaning                      |
@@ -5829,18 +6026,21 @@ By default, `kici login` opens your browser for OIDC authentication using PKCE.
 
 After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT) stored in the config directory (`~/.kici/config` by default, overridable with `KICI_CONFIG_DIR`).
 
+`kici login` targets the hosted KiCI Platform by default. To authenticate against another environment (a self-hosted Platform, for example), pass `--platform-endpoint` / `--oidc-issuer` or set `KICI_PLATFORM_URL` / `KICI_OIDC_ISSUER`. Login persists the platform endpoint and OIDC issuer it authenticated against alongside the PAT, so a saved PAT always matches its endpoint. Because the config describes one environment at a time, **switching the endpoint resets the active organization and default clusters** — re-run `kici org use <name>` after switching environments.
+
 ```bash
 kici login [options]
 ```
 
 **Options:**
 
-| Option                      | Default | Description                                    |
-| --------------------------- | ------- | ---------------------------------------------- |
-| `--token <key>`             | none    | API key for direct authentication (legacy)     |
-| `--device`                  | false   | Force device authorization flow (headless/SSH) |
-| `--platform-endpoint <url>` | none    | Platform relay URL                             |
-| `--routing-key <key>`       | none    | Routing key for webhook source identification  |
+| Option                      | Default | Description                                         |
+| --------------------------- | ------- | --------------------------------------------------- |
+| `--token <key>`             | none    | API key for direct authentication (legacy)          |
+| `--device`                  | false   | Force device authorization flow (headless/SSH)      |
+| `--platform-endpoint <url>` | none    | Platform relay URL                                  |
+| `--oidc-issuer <url>`       | none    | OIDC issuer URL (selects a non-default environment) |
+| `--routing-key <key>`       | none    | Routing key for webhook source identification       |
 
 **Environment variables:**
 
@@ -5866,7 +6066,8 @@ kici login --device
 kici login --token kici_sk_abc123...
 
 # Log in against a self-hosted Platform
-kici login --platform-endpoint https://platform.example.com
+kici login --platform-endpoint https://platform.example.com \
+  --oidc-issuer https://auth.example.com/realms/kici-internal
 
 # Suppress browser opening (print authorize URL to stdout)
 KICI_BROWSER_CMD=none kici login
@@ -7520,12 +7721,14 @@ Source: https://docs.kici.dev/user/approvals/
 
 An **approval gate** pauses execution until an authorized person approves it. Execution resumes from exactly where it paused; a rejection (or an expired hold) fails the run.
 
-You declare a gate in your workflow with `requireApproval`. It is available at three levels of granularity:
+You declare a gate in your workflow with `approval`. It is available at three levels of granularity:
 
 - **Step** — pause mid-job, before a specific step runs. The agent holds the live workspace (with all prior-step state intact) for the duration of the wait.
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](#drift-gates-whendrift) below.
+
 Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](../operator/approvals.md) for how operators define teams, the approval queue, and expiry; see [the architecture overview](../architecture/approvals.md) for how a hold is evaluated and resumed.
 
 ## Quick start
@@ -7540,7 +7743,7 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-production', {
       runsOn: 'default',
-      requireApproval: [{ team: 'leads' }],
+      approval: [{ team: 'leads' }],
       steps: [step('deploy', async (ctx) => ctx.$`deploy --prod`)],
     }),
   ],
@@ -7549,28 +7752,28 @@ export default workflow('deploy', {
 
 When the run reaches this job, it is held instead of dispatched. The held run appears in the dashboard approval queue and can be released from there or with the [`kici approve`](#approving-from-the-cli) command. Once a member of `leads` approves, the job dispatches normally.
 
-## The `requireApproval` field
+## The `approval` field
 
-`requireApproval` accepts three forms.
+`approval` accepts three forms.
 
 ### Shorthand: `true`
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  requireApproval: true,
+  approval: true,
   steps: [
     /* ... */
   ],
 });
 ```
 
-`requireApproval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
 
 ### Approver list (AND)
 
 ```typescript
-requireApproval: [{ team: 'leads' }, { user: 'cto' }],
+approval: [{ team: 'leads' }, { user: 'cto' }],
 ```
 
 A list of approver clauses is an **AND** list: every clause must be satisfied before the element is released.
@@ -7582,27 +7785,29 @@ A single approver may satisfy more than one clause. If `cto` is also a member of
 
 There is no OR or nested logic — clauses are always a flat AND list.
 
-### Object form: reason and timeout
+### Object form: when, reason, and timeout
 
 ```typescript
-requireApproval: {
+approval: {
+  when: 'always',
   approvers: [{ team: 'security' }, { team: 'leads' }],
   reason: 'Production deploy requires security + leads sign-off',
   timeout: 7200, // seconds
 },
 ```
 
-| Field       | Type               | Description                                                                                         |
-| ----------- | ------------------ | --------------------------------------------------------------------------------------------------- |
-| `approvers` | `ApproverClause[]` | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member". |
-| `reason`    | `string`           | A human-readable label shown in the dashboard queue and the held-for-approval status check.         |
-| `timeout`   | `number`           | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.      |
+| Field       | Type                  | Description                                                                                                                                                                 |
+| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](#drift-gates-whendrift). |
+| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                         |
+| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                 |
+| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.                                                                              |
 
 When `timeout` is omitted, the gate uses the org's default approval expiry (set by the operator). On expiry, the held element is rejected and the run fails — see [expiry](../operator/approvals.md#expiry).
 
 ## Granularity
 
-The same `requireApproval` field is accepted on a workflow, a job, and a step.
+The same `approval` field is accepted on a workflow, a job, and a step.
 
 ### Workflow-level
 
@@ -7611,7 +7816,7 @@ A workflow-level gate holds the entire run before any job is dispatched:
 ```typescript
 export default workflow('release', {
   on: [push({ branches: ['main'] })],
-  requireApproval: [{ team: 'release-managers' }],
+  approval: [{ team: 'release-managers' }],
   jobs: [buildJob, publishJob],
 });
 ```
@@ -7623,7 +7828,7 @@ A job-level gate holds just that job; other jobs in the run proceed normally:
 ```typescript
 job('publish', {
   runsOn: 'default',
-  requireApproval: [{ team: 'leads' }],
+  approval: [{ team: 'leads' }],
   steps: [
     /* ... */
   ],
@@ -7640,7 +7845,7 @@ job('migrate-and-deploy', {
   steps: [
     step('build-plan', async (ctx) => ctx.$`./gen-migration-plan.sh`),
     step('apply-migration', {
-      requireApproval: [{ team: 'dba' }],
+      approval: [{ team: 'dba' }],
       run: async (ctx) => ctx.$`./apply-migration.sh`,
     }),
     step('deploy', async (ctx) => ctx.$`deploy --prod`),
@@ -7652,9 +7857,39 @@ Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `
 
 Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](../operator/approvals.md#agent-occupancy-during-step-level-holds).
 
+## Drift gates (`when: 'drift'`)
+
+A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](idempotent-steps.md). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
+
+When the gate fires, the held run carries the **computed drift** as a payload: the rendering your `summarize(drift)` produced (the per-file diff, the commands that would run), plus the structured drift. The dashboard approval queue and the [CLI](#approving-from-the-cli) show the actual diff the operator is approving — not a static reason string.
+
+```typescript
+job('patch-prod', {
+  runsOn: 'default',
+  steps: [
+    step('apply-nginx-config', {
+      check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED_CONF }),
+      summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+      run: async (ctx, drift) => {
+        await writeConfig(drift.want);
+      },
+      approval: { when: 'drift', approvers: [{ team: 'ops' }], reason: 'prod patch' },
+    }),
+  ],
+});
+```
+
+Behavior:
+
+- The gate fires **only in apply mode**. In `--check` mode nothing applies, so nothing gates — drift is just reported.
+- **Approve** → the step's `run(ctx, drift)` applies the change.
+- **Reject** → fail-stop: the step fails, the job fails, and the `needs:` skip-cascade aborts everything downstream.
+
+A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow scope, is a compile error.
+
 ## Mandatory vs. explicit gates
 
-`requireApproval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -7676,10 +7911,23 @@ kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 
 You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](cli-reference.md#kici-approve) for the full command reference.
 
+### Inline approval and `--approve-all` in `kici run remote`
+
+When you trigger a run with `kici run remote` and it pauses on a gate, the CLI prints the gate (and, for a drift gate, the computed drift) and — in an interactive terminal — prompts you to approve or reject right there, without leaving the watch. In a non-interactive shell it prints how to approve out of band and keeps watching.
+
+To auto-approve **every gate of the run you just dispatched**, pass `--approve-all` (alias `--yes`):
+
+```bash
+kici run remote deploy-prod --approve-all
+```
+
+`--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
+
 You can also approve from the dashboard approval queue. See [Dashboard](dashboard/environments-and-secrets.md#approval-queue).
 
 ## See also
 
+- [Idempotent steps](idempotent-steps.md) — the check/apply step facet that drift gates build on.
 - [Environments](environments.md) — operator-required reviewers on protected environments.
 - [Approval gates (operator guide)](../operator/approvals.md) — teams, the approval queue, expiry, and self-approval.
 - [Approval gates (architecture)](../architecture/approvals.md) — the unified hold model and the step-level round-trip.
@@ -8312,7 +8560,7 @@ Required reviewers: alice, bob
 
 When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](cli-reference.md#kici-approve) command, or the API. Held runs expire after a configurable timeout.
 
-This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `requireApproval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
 
 ### Wait timer
 
@@ -8987,7 +9235,7 @@ const configureNginx = step('configure-nginx', {
 `summarize` is **required** whenever `check` is declared. `run` and `whenInSync`
 both produce the same output type — one output shape per step, whichever path
 runs. Every other step facet (`cache`, `rules`, `continueOnError`, `timeout`,
-`requireApproval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+`approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
 
 A plain `step()` without `check` keeps its exact current behavior — the check
 facet is fully optional.
@@ -9886,11 +10134,12 @@ GitHub App "my-org" is live.
 
 **Flags:**
 
-| Flag                  | Effect                                                                                                                                                                                                              |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--name <name>`       | The App name on GitHub (required).                                                                                                                                                                                  |
-| `--github-org <slug>` | Create the App under a GitHub organization instead of your personal account.                                                                                                                                        |
-| `--no-browser`        | Headless mode: the CLI prints a `kici.dev` URL to open, then reads the setup code you paste back. The page is pure client-side — it only displays the short-lived code, which is useless once the CLI exchanges it. |
+| Flag                  | Effect                                                                                                                                                                                                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`       | The App name you _request_ on GitHub (required). GitHub assigns the final name + slug; the stored, displayed name always comes from GitHub (see [Display name and slug](#display-name-and-slug)).                                                                                     |
+| `--github-org <slug>` | Create the App under a GitHub organization instead of your personal account.                                                                                                                                                                                                          |
+| `--webhook-url <url>` | **Advanced / self-hosted.** Bake this `https://` URL into the App's webhook verbatim and skip the platform-mode webhook-URL resolution (so it works even where the auto-resolved KiCI Platform URL is unavailable). See [Self-hosted webhook URL](#self-hosted-webhook-url-override). |
+| `--no-browser`        | Headless mode: the CLI prints a `kici.dev` URL to open, then reads the setup code you paste back. The page is pure client-side — it only displays the short-lived code, which is useless once the CLI exchanges it.                                                                   |
 
 The manifest flow always creates a **new** App on GitHub. If a source for
 that App id already exists on the orchestrator, the command refuses — use
@@ -10054,6 +10303,53 @@ its own source record and the orchestrator looks up the right one by
 combining the URL's `<orgId>` with the App ID from the
 `X-GitHub-Hook-Installation-Target-ID` header.
 
+## Display name and slug
+
+For a GitHub App source, **GitHub is the source of truth for the displayed
+name**. `--name` is only the name you _request_ when the App is created;
+GitHub assigns the final display name and a URL-safe **slug**
+(`my-org` → `my-org-1` if the name was taken). KiCI captures both at creation
+and shows them in the dashboard **Sources** tab — the display name prominently,
+with the slug as dimmed secondary text.
+
+If you later rename the App in GitHub's UI, KiCI keeps the displayed name in
+sync two ways:
+
+- **Automatically**, on a daily schedule. The orchestrator re-reads each GitHub
+  source's name + slug from GitHub and updates the dashboard if they changed.
+  The interval is configurable via `KICI_GITHUB_APP_NAME_REFRESH_INTERVAL_MS`
+  (default 24h).
+- **On demand**, with `source refresh`:
+
+  ```bash
+  kici-admin source refresh github:<appId>   # one source
+  kici-admin source refresh --all            # every GitHub source
+  ```
+
+  It prints `old → new` for any name or slug that changed, and is a no-op when
+  GitHub already matches what KiCI has stored. Non-GitHub routing keys are
+  rejected — name/slug sync applies only to GitHub App sources.
+
+## Self-hosted webhook URL override
+
+By default the manifest flow bakes the KiCI Platform webhook endpoint
+(`https://<platform-host>/webhook/<orgId>/github`) into the App. If you run
+your own ingress and want GitHub to deliver events to it instead, pass
+`--webhook-url` when creating the App:
+
+```bash
+kici-admin source add github --manifest --name my-org \
+  --webhook-url https://hooks.my-infra.example/github
+```
+
+The supplied URL must be an absolute `https://` URL; it is written into the
+App's webhook configuration **verbatim**. This is the operator asserting "I own
+webhook delivery": KiCI adds **no** ingress at this URL and does **not** receive
+events there — your own infrastructure is responsible for accepting GitHub's
+deliveries and routing them onward. Supplying the flag also decouples App
+creation from platform-mode URL resolution, so it works even in a configuration
+where the auto-resolved KiCI Platform URL is unavailable.
+
 ## Global workflows
 
 A GitHub App source opts in to org-wide global workflows using the

package/dist/llm-context/llms.txt

@@ -14,6 +14,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 - [Basic workflow patterns](https://docs.kici.dev/user/patterns/basic/): Basic CI, PR-only / push-only filters, multiple triggers, manual-only workflows
 - [Conditionals & matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/): Conditional execution with rules, matrix builds (static + dynamic), dynamic job generation
+- [Host restart & wait-for-alive](https://docs.kici.dev/user/patterns/host-restart/): Reboot the host a workflow runs on and continue after it comes back
 - [Integration patterns](https://docs.kici.dev/user/patterns/integrations/): Workflow chaining, generic webhooks, Stripe, self-hosted git forges, plain GitHub repos
 - [Pattern reference](https://docs.kici.dev/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
 - [Scheduling & event patterns](https://docs.kici.dev/user/patterns/scheduling-and-events/): Nightly cron, workflow-complete-triggered deploys, custom event chaining
@@ -44,7 +45,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 ## Workflow features
 
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
-- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with requireApproval
+- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/)