loadout-ai 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.9.4 - 2026-09-07
+
+### Changed
+
+- Updated the Stable first-run flow to show detailed safety findings before
+  applying and require explicit acknowledgement of the currently reported
+  instruction-like files.
+
+### Fixed
+
+- Serialized coordination lock recovery within a process so competing
+  recoverers cannot enter the same critical section simultaneously.
+
 ## 0.9.3 - 2026-09-07
 
 ### Changed

package/README.md

@@ -29,21 +29,23 @@ You need Node.js 20 or newer and Git.
 
 ```bash
 npm install --global loadout-ai
-loadout setup --mode stable
+loadout setup --mode stable --details
 ```
 
 The second command detects your coding agents and previews the 30-skill Stable
 loadout. It does not change agent files. Review the plan, then apply it:
 
 ```bash
-loadout setup --mode stable --yes
+loadout setup --mode stable --yes --approve-risk
 loadout status
 ```
 
 Loadout saves a rollback snapshot before applying changes. Run
 `loadout rollback` to restore the previous managed state.
 
-> `Preview complete; nothing was changed. Re-run with --yes to install this exact screened plan.`
+`--approve-risk` acknowledges the instruction-like files reported by the current
+Stable preview. Use it only after reading those findings; it does not replace the
+preview or the pinned-source checks.
 
 A later `--yes` invocation recomputes the plan from pinned sources and current agent and filesystem state; it does not persist or prove identity with the earlier preview.
 
@@ -123,9 +125,9 @@ and coordination without making you relay every command.
 For a reproducible install, pin the current release:
 
 ```bash
-npm install --global loadout-ai@0.9.3
-loadout setup --mode stable
-loadout setup --mode stable --yes
+npm install --global loadout-ai@0.9.4
+loadout setup --mode stable --details
+loadout setup --mode stable --yes --approve-risk
 loadout status
 ```
 
@@ -269,25 +271,25 @@ Configured CI platforms describe a manually triggered workflow, not evidence tha
 
 ## Command reference
 
-| Goal                               | Command                                                    |
-| ---------------------------------- | ---------------------------------------------------------- |
-| Guided first run                   | `loadout guide`                                            |
-| Preview or apply Stable            | `loadout setup --mode stable` · add `--yes` to apply       |
-| Inspect managed skills             | `loadout status` · `loadout library`                       |
-| Recommend for this repository      | `loadout recommend --project .`                            |
-| Activate a project-specific set    | `loadout optimize --project . --limit 30`                  |
-| Scan or update                     | `loadout scan` · `loadout update`                          |
-| Send a task                        | `loadout handoff codex "write tests"`                      |
-| Use a handoff template             | `loadout handoff codex src/auth.ts --template write-tests` |
-| Preview two-agent ownership        | `loadout coord start --agents claude-code,codex`           |
-| Inspect coordination state         | `loadout coord snapshot codex`                             |
-| Detect shared contract candidates  | `loadout coord detect`                                     |
-| Turn a decision into tasks         | `loadout coord discuss implement <thread-id>`              |
-| Start the coordination MCP server  | `loadout serve`                                            |
-| Health check                       | `loadout doctor`                                           |
-| Restore the previous managed state | `loadout rollback`                                         |
-| Preview complete removal           | `loadout uninstall`                                        |
-| Full CLI reference                 | `loadout --help` · `loadout advanced`                      |
+| Goal                               | Command                                                                            |
+| ---------------------------------- | ---------------------------------------------------------------------------------- |
+| Guided first run                   | `loadout guide`                                                                    |
+| Preview or apply Stable            | `loadout setup --mode stable --details` · then `--yes --approve-risk` after review |
+| Inspect managed skills             | `loadout status` · `loadout library`                                               |
+| Recommend for this repository      | `loadout recommend --project .`                                                    |
+| Activate a project-specific set    | `loadout optimize --project . --limit 30`                                          |
+| Scan or update                     | `loadout scan` · `loadout update`                                                  |
+| Send a task                        | `loadout handoff codex "write tests"`                                              |
+| Use a handoff template             | `loadout handoff codex src/auth.ts --template write-tests`                         |
+| Preview two-agent ownership        | `loadout coord start --agents claude-code,codex`                                   |
+| Inspect coordination state         | `loadout coord snapshot codex`                                                     |
+| Detect shared contract candidates  | `loadout coord detect`                                                             |
+| Turn a decision into tasks         | `loadout coord discuss implement <thread-id>`                                      |
+| Start the coordination MCP server  | `loadout serve`                                                                    |
+| Health check                       | `loadout doctor`                                                                   |
+| Restore the previous managed state | `loadout rollback`                                                                 |
+| Preview complete removal           | `loadout uninstall`                                                                |
+| Full CLI reference                 | `loadout --help` · `loadout advanced`                                              |
 
 Most mutating commands are previews first. Add `--yes` only after reviewing the plan.
 

package/dist/src/core/coordination/lock.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 const LOCK_FILE = "coordination.lock";
 const DEFAULT_TIMEOUT_MS = 10_000;
 const MALFORMED_LOCK_STALE_MS = 30_000;
+const localLockTails = new Map();
 export class CoordinationLockTimeoutError extends Error {
     constructor(timeoutMs) {
         super(`Timed out waiting ${timeoutMs}ms for the coordination lock`);
@@ -64,9 +65,25 @@ async function releaseOwnedLock(path, token) {
 function wait(delayMs) {
     return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
-/** Serialize coordination mutations across Node processes sharing a project. */
-export async function withCoordinationLock(coordinationDir, operation, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    const path = join(coordinationDir, LOCK_FILE);
+async function withLocalLock(path, operation) {
+    const previous = localLockTails.get(path) ?? Promise.resolve();
+    let release = () => undefined;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.then(() => current);
+    localLockTails.set(path, tail);
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+        if (localLockTails.get(path) === tail)
+            localLockTails.delete(path);
+    }
+}
+async function withFileLock(path, operation, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     const token = randomUUID();
     const owner = {
@@ -138,3 +155,8 @@ export async function withCoordinationLock(coordinationDir, operation, timeoutMs
         await releaseOwnedLock(path, token);
     }
 }
+/** Serialize coordination mutations within this process and across processes. */
+export async function withCoordinationLock(coordinationDir, operation, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const path = join(coordinationDir, LOCK_FILE);
+    return withLocalLock(path, () => withFileLock(path, operation, timeoutMs));
+}

package/dist/src/core/reporting/cli-guide.js

@@ -5,8 +5,10 @@ Loadout — manage the skills, tools, and MCP servers your AI agents use.
 FIRST TIME
 
   loadout doctor                    which agents you have, and whether they are healthy
-  loadout setup --mode stable       preview 30 reviewed skills (nothing changes)
-  loadout setup --mode stable --yes install them
+  loadout setup --mode stable --details
+                                      preview 30 reviewed skills and findings
+  loadout setup --mode stable --yes --approve-risk
+                                      install only after reviewing those findings
 
 IN A PROJECT
 

package/docs/REFERENCE.md

@@ -42,10 +42,14 @@ pinned public sources**, installed into each agent you choose.
 | [Agent Skills Marketplace](https://github.com/wshobson/agents)         | Architecture, review, error handling, JavaScript, Python      | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                 |
 
 ```bash
-loadout setup --mode stable
-loadout setup --mode stable --yes
+loadout setup --mode stable --details
+loadout setup --mode stable --yes --approve-risk
 ```
 
+The current Stable selection reports instruction-like files in reviewed skill
+sources. Read the detailed preview before acknowledging those findings with
+`--approve-risk`.
+
 ### Power: a larger cross-project toolkit
 
 Power draws a skill-level allowlist from eight major collections.

package/docs/USER_TEST_GUIDE.md

@@ -107,11 +107,12 @@ explicit.
 For unattended use only after reviewing a preview, the equivalent is:
 
 ```bash
-loadout setup --mode stable --agents codex,claude-code --yes
+loadout setup --mode stable --agents codex,claude-code --yes --approve-risk
 ```
 
-Do not add `--approve-risk` unless the displayed preview identifies a specific
-reviewed finding and you understand it.
+The current Stable preview identifies instruction-like files in reviewed skill
+sources, so unattended apply requires `--approve-risk`. Add it only after reading
+and accepting the displayed findings.
 
 ## 5. Test a change and recover
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "private": false,
   "license": "MIT",
   "description": "The package manager for AI coding agent extensions",