clud 2.7.9__tar.gz → 2.8.2__tar.gz

{clud-2.7.9 → clud-2.8.2}/Cargo.lock

@@ -574,7 +574,7 @@ dependencies = [
 
 [[package]]
 name = "clud"
-version = "2.7.9"
+version = "2.8.2"
 dependencies = [
  "arboard",
  "base64",
@@ -584,6 +584,7 @@ dependencies = [
  "crossterm",
  "ctrlc",
  "dirs 5.0.1",
+ "filetime",
  "fs4",
  "getrandom 0.4.2",
  "gix-hash",
@@ -866,7 +867,7 @@ dependencies = [
 
 [[package]]
 name = "daemon-stub"
-version = "2.7.9"
+version = "2.8.2"
 dependencies = [
  "libc",
  "running-process",
@@ -2335,7 +2336,7 @@ dependencies = [
 
 [[package]]
 name = "mock-agent"
-version = "2.7.9"
+version = "2.8.2"
 dependencies = [
  "libc",
  "serde_json",
@@ -2953,11 +2954,11 @@ dependencies = [
 
 [[package]]
 name = "probe-dll"
-version = "2.7.9"
+version = "2.8.2"
 
 [[package]]
 name = "probe-target"
-version = "2.7.9"
+version = "2.8.2"
 
 [[package]]
 name = "proc-macro-crate"
@@ -3805,6 +3806,14 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
 
+[[package]]
+name = "tap-gate"
+version = "2.8.2"
+dependencies = [
+ "running-process",
+ "tempfile",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.27.0"

{clud-2.7.9 → clud-2.8.2}/Cargo.toml

@@ -13,7 +13,7 @@ exclude = [
 libraries = [{ path = "dylints/*" }]
 
 [workspace.package]
-version = "2.7.9"
+version = "2.8.2"
 edition = "2021"
 rust-version = "1.85"
 license-file = "LICENSE"

clud-2.7.9/README.md → clud-2.8.2/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: clud
+Version: 2.8.2
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Dist: mcp>=2.1 ; extra == 'mcp'
+Provides-Extra: mcp
+License-File: LICENSE
+Summary: Fast Rust CLI for running Claude Code and Codex in YOLO mode
+Keywords: claude,codex,cli,ai,agent
+Home-Page: https://github.com/zackees/clud
+Author: Zach Vorhies
+License: Clud Proprietary License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/zackees/clud
+Project-URL: Issues, https://github.com/zackees/clud/issues
+Project-URL: Repository, https://github.com/zackees/clud
+
 # clud
 
 ![hero-clud](https://github.com/user-attachments/assets/4009dfee-e703-446d-b073-80d826708a10)
@@ -21,6 +46,13 @@ The name `clud` is simply a shorter, easier-to-type version of `claude`.
 
 `clud grind`
 
+`grind` opens one normal interactive PTY session and seeds its
+prompt with the harness-native `/loop` instruction. The harness owns all
+repetition; clud must not relaunch the agent, impose an iteration ceiling, or
+use DONE/BLOCKED marker files for `grind`. See the
+[grind contract](docs/architecture/grind.md). It requires the Claude harness;
+for another model provider, use `--harness claude`.
+
 [![CI](https://github.com/zackees/clud/actions/workflows/ci.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/ci.yml)
 [![Auto Release](https://github.com/zackees/clud/actions/workflows/auto-release.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/auto-release.yml)
 
@@ -59,6 +91,7 @@ clud                              # Launch Claude in YOLO mode via subprocess
 clud --codex                      # Use Codex as the backend
 clud --claude                     # Use Claude as the backend (default)
 clud --deepseek                   # Use DeepSeek through the Claude harness
+clud --deepseek sk-...            # Same, storing that API key in the native credential vault first
 clud --kimi                       # Use Kimi through the Claude harness
 clud --openrouter                 # Use Claude through OpenRouter
 clud --pty                        # Force PTY launch mode
@@ -504,6 +537,35 @@ which looks like it does this but does not: that flag exits 0 with empty output
 outside a submodule, so the `||` fallback never runs and `cd ""` silently does
 nothing.
 
+### Stop a subagent from spawning more agents
+
+One request can become hundreds of agents when a subagent delegates again: a
+deep-research run created 101 agents before it was stopped, and an upstream
+`/code-review` created 877 descendants *despite* a five-level nesting ceiling.
+A depth ceiling does not help, because fan-out at every level is what makes the
+total exponential.
+
+`clud-cmd-scan` can refuse the second level outright. With the guard on, the
+primary session may still create subagents, but a subagent's own `Agent` or
+`Workflow` call is denied before the descendant is allocated:
+
+```bash
+export CLUD_BLOCK_RECURSIVE_AGENTS=1
+```
+
+The denial is tagged `clud_agent_depth_exceeded` and tells the agent to do the
+work itself or hand it back to the session that started it. The guard is off by
+default — refusing agent creation changes what an agent may do, and a wrong
+default would break legitimate orchestration silently.
+
+Two things to know:
+
+- The hook must be registered with `"matcher": "*"` (the config above), not
+  `"Bash"`. A `Bash`-only matcher never sees an `Agent` call.
+- Only tool-visible creation is covered. The `agent()` calls a workflow script
+  makes internally emit no blocking hook event, so they remain uncontrolled
+  (anthropics/claude-code#79953 tracks the upstream gap).
+
 ### Let clud run your project's hooks
 
 Project hooks are usually written as repo-relative script paths, which is why a
@@ -795,3 +857,4 @@ organizations under 6 people, with lifetime grandfathering for organizations
 that qualified before growing beyond that size. Larger organizations need a
 commercial license unless they have a grandfathered or contributor-granted free
 license. See [LICENSE](LICENSE) for the full terms.
+

clud-2.7.9/PKG-INFO → clud-2.8.2/README.md

@@ -1,26 +1,3 @@
-Metadata-Version: 2.4
-Name: clud
-Version: 2.7.9
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Build Tools
-License-File: LICENSE
-Summary: Fast Rust CLI for running Claude Code and Codex in YOLO mode
-Keywords: claude,codex,cli,ai,agent
-Home-Page: https://github.com/zackees/clud
-Author: Zach Vorhies
-License: Clud Proprietary License
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Homepage, https://github.com/zackees/clud
-Project-URL: Issues, https://github.com/zackees/clud/issues
-Project-URL: Repository, https://github.com/zackees/clud
-
 # clud
 
 ![hero-clud](https://github.com/user-attachments/assets/4009dfee-e703-446d-b073-80d826708a10)
@@ -44,6 +21,13 @@ The name `clud` is simply a shorter, easier-to-type version of `claude`.
 
 `clud grind`
 
+`grind` opens one normal interactive PTY session and seeds its
+prompt with the harness-native `/loop` instruction. The harness owns all
+repetition; clud must not relaunch the agent, impose an iteration ceiling, or
+use DONE/BLOCKED marker files for `grind`. See the
+[grind contract](docs/architecture/grind.md). It requires the Claude harness;
+for another model provider, use `--harness claude`.
+
 [![CI](https://github.com/zackees/clud/actions/workflows/ci.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/ci.yml)
 [![Auto Release](https://github.com/zackees/clud/actions/workflows/auto-release.yml/badge.svg)](https://github.com/zackees/clud/actions/workflows/auto-release.yml)
 
@@ -82,6 +66,7 @@ clud                              # Launch Claude in YOLO mode via subprocess
 clud --codex                      # Use Codex as the backend
 clud --claude                     # Use Claude as the backend (default)
 clud --deepseek                   # Use DeepSeek through the Claude harness
+clud --deepseek sk-...            # Same, storing that API key in the native credential vault first
 clud --kimi                       # Use Kimi through the Claude harness
 clud --openrouter                 # Use Claude through OpenRouter
 clud --pty                        # Force PTY launch mode
@@ -527,6 +512,35 @@ which looks like it does this but does not: that flag exits 0 with empty output
 outside a submodule, so the `||` fallback never runs and `cd ""` silently does
 nothing.
 
+### Stop a subagent from spawning more agents
+
+One request can become hundreds of agents when a subagent delegates again: a
+deep-research run created 101 agents before it was stopped, and an upstream
+`/code-review` created 877 descendants *despite* a five-level nesting ceiling.
+A depth ceiling does not help, because fan-out at every level is what makes the
+total exponential.
+
+`clud-cmd-scan` can refuse the second level outright. With the guard on, the
+primary session may still create subagents, but a subagent's own `Agent` or
+`Workflow` call is denied before the descendant is allocated:
+
+```bash
+export CLUD_BLOCK_RECURSIVE_AGENTS=1
+```
+
+The denial is tagged `clud_agent_depth_exceeded` and tells the agent to do the
+work itself or hand it back to the session that started it. The guard is off by
+default — refusing agent creation changes what an agent may do, and a wrong
+default would break legitimate orchestration silently.
+
+Two things to know:
+
+- The hook must be registered with `"matcher": "*"` (the config above), not
+  `"Bash"`. A `Bash`-only matcher never sees an `Agent` call.
+- Only tool-visible creation is covered. The `agent()` calls a workflow script
+  makes internally emit no blocking hook event, so they remain uncontrolled
+  (anthropics/claude-code#79953 tracks the upstream gap).
+
 ### Let clud run your project's hooks
 
 Project hooks are usually written as repo-relative script paths, which is why a
@@ -818,4 +832,3 @@ organizations under 6 people, with lifetime grandfathering for organizations
 that qualified before growing beyond that size. Larger organizations need a
 commercial license unless they have a grandfathered or contributor-granted free
 license. See [LICENSE](LICENSE) for the full terms.
-

{clud-2.7.9 → clud-2.8.2}/crates/clud-bin/Cargo.toml

@@ -118,6 +118,14 @@ tempfile = "3"
 
 [dev-dependencies]
 serde_yaml = "0.9"
+# #1148: the nested-sweep tests need a *mixed-age* tree — a stale session
+# directory beneath a fresh parent — which is the exact shape the bug lives
+# in. The existing idiom in `gc::session_tmp` shifts the test's notion of
+# "now" into the future, which ages every entry uniformly and so cannot
+# express that shape. Setting mtimes directly can; `std::fs::File` cannot
+# open a directory on Windows, so this does it portably. Already in the
+# lockfile via `notify`/`gix-index`, so it is not new to the build.
+filetime = "0.2"
 # #436: the `RUNNING_PROCESS_FAKE_BACKEND` seam that
 # `fake_backend_seam_overrides_cached_endpoint` exercises lives behind
 # running-process's off-by-default `test-seams` feature (upstream #433 R4).

clud-2.8.2/crates/clud-bin/assets/skills/clud-bosn/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: clud-bosn
+description: Run repeated local Docker builds under bosn so the loop stops filling the disk.
+triggers:
+  - When iterating locally on a Dockerfile or compose stack in this repo
+  - When repeated docker builds are filling the disk or a prune is being considered
+  - When the user mentions bosn
+---
+<!-- managed-by: clud -->
+
+# clud-bosn
+
+[bosn](https://github.com/zackees/bosn) owns the containers, volumes, and images a
+local build loop creates: every resource is labeled with who made it and what it was
+built from, and whether anything still needs it is a lease in bosn's registry rather
+than a guess. Storage is bounded by ceilings with eviction, so the loop stops growing
+without anyone running a prune.
+
+Use it for **the agent's own build loop**. The problem it solves is running the same
+containerized build hundreds of times, where Docker keeps every image and volume it
+was told to make and has no notion of "this one is finished". The reflex it replaces
+is `docker system prune`, which also destroys the warm cache you wanted to keep.
+
+## Code Change Rule
+
+If the work this loop is iterating on is a bug fix or feature implementation, use
+RED -> GREEN: write or identify the focused failing test first, run it under the
+containerized loop to see it fail, implement the scoped change, and rerun it to pass.
+A faster build loop is only worth having if it is still answering a real question.
+
+## Do not use this when
+
+- Editing a `Dockerfile` or compose file that **ships** — production images, or a file
+  written for someone else to run. The subject being Docker is not the trigger; local
+  iteration is.
+- Debugging a registry push, or anything about images leaving this machine.
+- The user asked a Docker question and is not building anything.
+
+A skill that fires on every mention of Docker becomes noise, and noise gets ignored.
+
+## Before committing the agent to this path
+
+1. `command -v bosn` — if absent, say so and stop. Install is
+   `uv tool install git+https://github.com/zackees/bosn` (Python 3.11+; puts `bosn`
+   and `bosn-docker` on PATH). Do not install it without being asked.
+2. `docker info` must succeed — bosn manages a real engine, it does not replace one.
+3. **WSL is refused outright**: `bosn` exits non-zero inside WSL, because its Windows
+   loopback daemon is unreachable from there. Use a native Windows shell, macOS, or
+   Linux. (`bosn-docker` does not yet refuse it, so a WSL failure can surface later
+   and less clearly.)
+4. bosn is manifest-driven: it needs a `bosn.toml` at the repo root declaring stacks,
+   volumes, and tasks. Without one there is nothing for it to converge, and writing
+   one is a change to the repo — propose it, do not add it silently.
+
+## The loop
+
+```bash
+bosn ensure          # converge and register without running anything (pre-warm)
+bosn unit            # run the task named in bosn.toml
+bosn status --json   # bounded daemon/registry state
+bosn gc --dry-run --json   # what retention would remove, before it removes it
+```
+
+Existing unmanaged volumes can be imported rather than recreated:
+`bosn adopt --legacy clud` plans and reports, `--yes` applies.
+
+## What it does not cover
+
+Read this before promising a drop-in replacement:
+
+- The Docker front door is **partial** — `bosn init` and
+  `bosn-docker compose {up,down,logs,ps}` over a small compose subset only.
+  `bosn-docker compose up -d` is rejected outright, not ignored.
+- **No `docker` / `docker-compose` shims and no podman.** Arbitrary docker commands
+  are not routed through bosn; only what is listed above is.
+- **BuildKit's own layer cache is outside the label contract.** bosn manages
+  containers, volumes, and images and never prunes the builder, so builder growth is
+  still yours to watch.
+- `docker compose up` maps to `bosn-docker compose up`, which labels and tracks the
+  service *containers*; volumes created that way are not tracked.
+
+When the work needs something in that list, say so and use Docker directly rather
+than bending the task to fit the tool.

{clud-2.7.9 → clud-2.8.2}/crates/clud-bin/assets/skills/clud-extern-repos/SKILL.md

@@ -33,6 +33,24 @@ You do not need to add an ignore entry for it, and you should not: it is outside
 
 Checkouts still under the older `<repo>/.extern-repos/` location keep working and are still tracked, but put new ones beside the repo.
 
+A dependent checkout is a **complete project**, so parent-repo tooling that
+discovers projects by walking up from `$PWD` will find it and bind to it. That
+is not hypothetical: in #972 a Stop hook installed in the parent repo resolved
+its root that way, landed in the dependent checkout, and ran *that* project's
+hook through `uv run` — turning a "quick lint" into a full native build of a
+Rust-backed dependency. Two fires cost ~600s and ~400s, and the second died
+with a build-backend error that named no hook at all.
+
+Two rules follow, and they apply wherever the checkout lives:
+
+- **Anchor hooks to the session project root**, not `$PWD`. Claude Code passes
+  it in the hook payload (`cwd`), and the settings live in that repo anyway. A
+  hook installed in repo A should never execute repo B's hook.
+- **Never let a hook trigger a project sync**: use `uv run --no-project` (or
+  `--frozen`). A hook may lint; it may not compile a dependency from source.
+  clud's `uv_run_hook_guard` warns about the bare form, and since #972 it looks
+  at `Stop` hooks and at dependent checkouts in both locations.
+
 Create feature branches in the dependent repo using the `feat/<short-name>` convention.
 
 ## Coordination

clud-2.8.2/crates/clud-bin/assets/skills/clud-os-debug/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: clud-os-debug
+description: Diagnose a live crash, hang, or CPU burn on Windows, macOS, or Linux with the OS's own debugger and sampling profiler.
+triggers:
+  - When a process is hung, spinning, or crashing and the cause is not in a log
+  - When the user asks why something is using CPU, or asks for a stack dump or profile
+  - When a crash report exists but the question is what the process is doing *now*
+---
+<!-- managed-by: clud -->
+
+# clud-os-debug
+
+`clud symbols` and the crash reporter answer "what did it do before it died". This
+skill answers "what is it doing right now" — a live stack, an attached debugger, or a
+sampled CPU profile, using the tools the OS already ships.
+
+## Code Change Rule
+
+A diagnosis is not a fix. When this investigation turns into a bug fix, switch to
+RED -> GREEN: turn what you observed into a focused failing test first — the stack
+you captured names the function, the profile names the hot path — run it to see it
+fail, make the scoped change, and rerun it to pass. A profile that leads straight to
+an edit leaves nothing behind to stop the same regression returning.
+
+## Pick the right instrument first
+
+These three get confused constantly, and reaching for the wrong one wastes the
+reproduction you may not get again:
+
+| You want to know | Use | Cost |
+|---|---|---|
+| Where is it stuck *right now* | **Live stack dump** — one sample of every thread | Milliseconds; process pauses briefly |
+| Why does this state happen | **Debugger attach** — breakpoints, memory, stepping | Process stops until you detach |
+| What is eating the CPU | **Sampled profile** — periodic stacks over a window | Seconds to minutes; process keeps running |
+
+A hang wants a stack dump. A crash wants the debugger (or the existing crash report).
+CPU burn wants a profile — a single stack of a busy process tells you almost nothing,
+because you sampled one arbitrary instant.
+
+## Before you attach to anything
+
+1. **Get the PID and confirm it is the right one.** `pgrep -af <name>` /
+   `Get-Process <name>`. Attaching to the wrong PID of a multi-process app (browsers,
+   Electron, anything with a helper tree) is the most common wasted attempt.
+2. **A stopped process is a stopped service.** Attaching a debugger *suspends the
+   target*. On anything shared or user-facing, prefer a stack dump or a sampled
+   profile, which do not.
+3. **Elevation is the user's call, not yours.** Where a step needs sudo, UAC, or a
+   `ptrace_scope` change, say which step needs it and why, run the OS's normal consent
+   mechanism, and stop if the user declines. Never weaken a system policy to make a
+   diagnosis convenient — `ptrace_scope`, SIP, and UAC exist to stop exactly what you
+   are about to do, and turning them off outlives your investigation.
+
+## Linux
+
+**Live stack of a running process** — no install, no elevation on your own processes:
+
+```bash
+gdb -p <pid> -batch -ex "thread apply all bt"     # every thread
+eu-stack -p <pid>                                  # elfutils, lighter
+cat /proc/<pid>/stack                              # kernel-side only
+```
+
+**Sampled CPU profile:**
+
+```bash
+perf record -F 99 -g -p <pid> -- sleep 20
+perf report --stdio           # or: perf script | stackcollapse-perf.pl | flamegraph.pl
+```
+
+**What blocks it, and the exact prerequisite:**
+
+- `ptrace: Operation not permitted` attaching to *your own* process →
+  `/proc/sys/kernel/yama/ptrace_scope` is `1`. The scoped fix is to run the debugger
+  under `sudo`, **not** to set the sysctl to `0` machine-wide.
+- `perf` returning no samples → `/proc/sys/kernel/perf_event_paranoid`. Report the
+  value and what it permits; changing it is a system-policy decision.
+- Missing symbols → install the distro's `-dbg`/`-debuginfo` package for that binary.
+
+**Syscall-level**: `strace -f -p <pid>` for a hang that is blocked in the kernel;
+`ltrace` for library calls. Both slow the target materially — bound the window.
+
+## macOS
+
+```bash
+sample <pid> 10 -f /tmp/sample.txt   # sampled profile, no elevation for your own procs
+spindump <pid> 10                    # system-wide, needs sudo, best for beachballs
+lldb -p <pid>                        # attach
+xcrun xctrace record --template 'Time Profiler' --attach <pid>
+```
+
+- `sample` is the first thing to run for a spinning process. It is non-invasive and
+  usually enough.
+- Attaching to a process you do not own, or one that is SIP-protected, will fail;
+  that is the boundary working. Report it rather than looking for a way around.
+- Hardened-runtime apps reject debuggers unless built with
+  `com.apple.security.get-task-allow`. For a third-party app, this is a dead end —
+  say so.
+
+## Windows
+
+```powershell
+Get-Process <name> | Select Id,ProcessName,CPU
+```
+
+**Live stack / crash dump** — inbox, no install:
+
+```powershell
+# Full user-mode dump; open in WinDbg or Visual Studio
+Get-Process <name> | ForEach-Object {
+  & "$env:SystemRoot\System32\rundll32.exe" `
+    "$env:SystemRoot\System32\comsvcs.dll",MiniDump $_.Id C:\temp\dump.dmp full
+}
+```
+
+`procdump -ma <pid> C:\temp\dump.dmp` (Sysinternals) is friendlier if present.
+
+**Sampled CPU profile** — WPR is inbox on Windows 10/11:
+
+```powershell
+wpr -start CPU -filemode
+# ... reproduce for a bounded window ...
+wpr -stop C:\temp\trace.etl
+```
+
+- `wpr` requires an elevated shell. Ask once, through UAC, and explain that the trace
+  is machine-wide for the capture window.
+- **If WPA (the analysis GUI) is missing**, that is the Windows Performance Toolkit,
+  an ADK component. Installing it is a privileged, machine-wide change: propose it,
+  let the user run the installer, and do not launch an installer unattended. The
+  `.etl` is still captured and analysable elsewhere without it.
+- Keep the capture bounded. A `CPU` profile writes hundreds of MB per minute.
+
+## Reporting
+
+Whatever you capture, report: the **artifact path**, the **exact command**, the
+**PIDs** it covers, and the **window** it spans. A profile with no window and a stack
+with no PID are both unfalsifiable later.
+
+State plainly which of the three instruments you used. "I profiled it" when you took
+one stack dump is the error this skill exists to prevent.
+
+## What this skill does not do
+
+- **It installs nothing.** Every command above is either inbox or a package the user
+  already has. Where a tool is missing, name the tool and let the user install it.
+- **It does not elevate on its own**, change `ptrace_scope`, disable SIP, or work
+  around a hardened runtime. Each of those is the OS refusing on purpose.
+- **It is not a substitute for the crash report.** For a process that already died,
+  `clud symbols` and `~/.clud/state/crashes/` are the right starting point.
+- **Automated, checksum-verified tool acquisition** (#563's second half) is not here;
+  bundled skills ship as documentation only.

clud-2.8.2/crates/clud-bin/assets/skills/clud-preloop/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: clud-preloop
+description: Run a GitHub Actions workflow locally with preloop before pushing a branch to find out whether CI passes.
+triggers:
+  - When about to push a branch mainly to see whether CI passes
+  - When the user asks to run a GitHub Actions workflow locally
+  - When a workflow failed remotely and the fix needs more than one attempt
+  - When the user mentions preloop
+---
+<!-- managed-by: clud -->
+
+# clud-preloop
+
+[preloop](https://github.com/preloopdev/preloop) runs `.github/workflows` locally on
+hardware-isolated microVMs, speaking the official `actions/runner` protocol rather
+than approximating it. `${{ }}` expressions, matrix builds, reusable workflows and
+concurrency groups work as they do on GitHub, and it can run against **uncommitted
+changes** — including untracked and gitignored files.
+
+The valuable trigger is the one nobody says out loud: *"I'll push and see if CI goes
+green."* That is a decision to spend a full remote matrix on a question a local run
+answers. Cross-platform failures — a path literal that is absolute on one OS and not
+another — are the class this catches cheapest.
+
+## Code Change Rule
+
+If the workflow is being changed to fix a bug or add behavior, use RED -> GREEN:
+run it locally first and see it fail for the reason you believe, make the scoped
+change, and rerun it to pass. Running a workflow locally makes that cycle cheap
+enough to actually do, which is the point.
+
+## Do not use this when
+
+- The task is about the workflow **file** rather than its behavior: renaming a job,
+  editing a matrix entry, fixing YAML indentation.
+- Reading an existing remote run's logs. That run already happened; `gh run view` is
+  the tool.
+- The failing thing is not the workflow. A test that fails locally will fail here too,
+  and going through a VM to learn that is slower than running the test.
+
+## Before committing the agent to this path
+
+1. `command -v preloop` — if absent, say so and stop.
+2. **Install by verified download, not by piping a script into a shell.** preloop's
+   README documents `curl -fsSL … | sh`; clud's own rule-writing guide uses that exact
+   shape as its canonical example of a pipeline worth blocking, so a clud skill must
+   not tell an agent to run it. Each release publishes per-platform tarballs with a
+   matching `.sha256` (`preloop-cli-<arch>-<os>.tar.gz` plus `.sha256`, and a
+   `sha256.sum`). Download the asset for the platform, verify it against its published
+   checksum, and put the binary on PATH — the same material the install script uses.
+3. **First run downloads a base image and builds a golden VM: 1–5 minutes.** After
+   that each job forks in ~200–300 ms. If the task cannot afford the first-run cost,
+   say so rather than starting it and stranding the work.
+
+## The loop
+
+```bash
+preloop serve                                    # engine on 127.0.0.1:9090; -d to detach
+preloop run -f .github/workflows/ci.yml --event pull_request
+preloop dap <run-id>                             # hold the job at entry and inspect it
+```
+
+`preloop dap` pauses a job before it runs and exposes the live `github`, `env`,
+`runner`, `job`, `steps` and `secrets` scopes. Reach for it when the YAML looks right
+and the runtime context is what is actually wrong — a matrix value or event payload
+that is not what the workflow assumed.
+
+## Where local and remote differ
+
+A green local run is strong evidence, not a guarantee. Say which one you ran.
+
+- The base image is **curated, not GitHub's** — the official image is ~90 GB, and
+  preloop deliberately omits dependencies that actions usually install themselves. A
+  step that relies on something preinstalled on a GitHub runner can pass there and
+  fail here, or the reverse. Custom and OCI-based goldens are supported.
+- On Apple Silicon, x86_64 goldens run under Rosetta 2 translation, and **Docker
+  actions are not supported on that path** — amd64 images inside the VM's Docker fail
+  with a `rosetta-wrapper` error. Prefer arm64 goldens there.
+- Some events need a payload supplied before they can be simulated.
+
+## Relationship to clud-bosn
+
+They do not overlap. bosn manages Docker resources on the **host**; a workflow run by
+preloop uses the Docker engine **inside its own microVM**, which the host's bosn
+neither sees nor tracks. Use bosn for the local build loop, preloop for the workflow.

{clud-2.7.9 → clud-2.8.2}/crates/clud-bin/assets/tools/docker/docker_recover.py

@@ -1702,7 +1702,27 @@ def _launch_windows_docker_desktop_guard() -> tuple[bool, str]:
             cwd=os.path.dirname(script),
             originator="clud-docker-recover-guard",
         )
-    except OSError as exc:
+    except Exception as exc:  # noqa: BLE001 - see below; a guard failure must not abort recovery
+        # Deliberately broader than `OSError` (#1058). running-process signals
+        # launch failures through its own `RuntimeError`/`Exception` subclasses
+        # -- `ProcessAbnormalExit`, `ProbeUnavailableError`,
+        # `DaemonOutputNotAvailableError` -- none of which derive from
+        # `OSError`. The reported failure was exactly that shape:
+        #
+        #     RuntimeError: daemon I/O error: The system cannot find the file
+        #     specified. (os error 2)
+        #
+        # so the narrow catch let it propagate out of `_execute_restart`, and a
+        # `restart --yes --force` aborted *before touching Docker at all* while
+        # `doctor` still reported healthy. The caller already has a complete
+        # fallback below this call -- direct executable launch, then the CLI
+        # path -- and it was simply never reached.
+        #
+        # Failing to start an optional guard process is never a reason to
+        # abandon a recovery the user explicitly asked for. The return value
+        # keeps this distinguishable from a failed restart: this message says
+        # the *guard* did not start, and the fallback appends its own outcome
+        # after it.
         return False, f"Docker Desktop daemon guard launch failed: {exc}"
     return (
         True,