@ouro.bot/cli 0.1.0-alpha.517 → 0.1.0-alpha.519

package/SerpentGuide.ouro/agent.json

@@ -1,6 +1,7 @@
 {
   "version": 2,
   "enabled": false,
+  "kind": "library",
   "humanFacing": { "provider": "anthropic", "model": "claude-opus-4-6" },
   "agentFacing": { "provider": "anthropic", "model": "claude-opus-4-6" },
   "context": {

package/changelog.json

@@ -1,6 +1,29 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.519",
+      "changes": [
+        "Layer 3 (final) of the harness-hardening sequence (1→4→2→3 from `docs/planning/2026-04-28-1900-planning-harness-hardening-and-repairguide.md`). Ships the `RepairGuide.ouro/` library bundle alongside `SerpentGuide.ouro/` containing five diagnostic skills (`diagnose-bootstrap-drift`, `diagnose-broken-remote`, `diagnose-sync-blocked`, `diagnose-vault-expired`, `diagnose-stacked-typed-issues`) plus `psyche/SOUL.md` + `psyche/IDENTITY.md`. Loaded by the existing `agentic-repair.ts` pipeline as a content source — not a runtime agent (no senses, no vault, no `ouro status` presence).",
+        "Introduces `kind: \"library\"` field on bundle `agent.json`. `agent-discovery.ts` filters bundles where `kind === \"library\"` so they're never instantiated as runtime agents. `SerpentGuide.ouro/agent.json` tagged with `kind: \"library\"` to formalize what was previously an implicit `enabled: false` convention.",
+        "Activation gate `shouldFireRepairGuide` consumes the existing `untypedDegraded` / `typedDegraded` partitioning at `cli-exec.ts:6693-6694`. Fires when `untypedDegraded.length > 0` OR `typedDegraded.length >= 3`. The existing `--no-repair` flag remains the operator escape hatch — no new env toggle.",
+        "Drops the `~/AgentBundles/SerpentGuide.ouro/` override fallback in `getSpecialistIdentitySourceDir` — the in-repo bundle is now the only source. Reasoning per the planning doc: drift surface we don't currently need; cleaner ownership; no override path to maintain. Five referencing files updated (`hatch-flow.ts`, `cli-defaults.ts`, plus their tests). Same constraint extends to RepairGuide from day one — no override mechanism.",
+        "`parseRepairProposals` typed parser maps RepairGuide's structured-proposal output into the existing `RepairAction` catalog from `readiness-repair.ts` (`vault-unlock`, `provider-auth`, `provider-use`, etc.). Backfills lane variants and missing fields where unambiguous; rejects malformed proposals.",
+        "Structured Layer-2 + Layer-4 findings threaded into the diagnostic prompt (post-review fix). `AgenticRepairDeps` gains optional `driftFindings: DriftFinding[]` and `syncFindings: BootSyncProbeFinding[]`. `cli-exec.ts` collects both at boot and passes them through to `runAgenticRepair`; `buildUserMessage` appends each as a JSON block when non-empty so the `diagnose-bootstrap-drift` / `diagnose-broken-remote` / `diagnose-sync-blocked` skills can reason over real structured shapes (`lane`, `intentProvider`, `intentModel`, `observedProvider`, `observedModel`, `repairCommand` for drift; `classification`, `conflictFiles`, `advisory`, etc. for sync). Synthetic test (`repair-guide-skill-types.test.ts`) asserts skill markdown references current TS field names so the contract can't silently drift.",
+        "Slugger-style compound integration fixture as canonical acceptance test (per O6): bad bootstrap state + expired creds + broken remote + drift between agent.json and state/providers.json simultaneously. Validates the full layer 1→4→2→3 pipeline end-to-end.",
+        "All gates green: tsc clean, lint clean, code coverage 100%, nerves audit pass."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.518",
+      "changes": [
+        "Layer 2 of the harness-hardening sequence (1→4→2→3 from `docs/planning/2026-04-28-1900-planning-harness-hardening-and-repairguide.md`). Wires a pre-flight `git pull` over every sync-enabled bundle into `ouro up`, before per-agent provider live-checks, so the post-pull `agent.json` is what live-check reads. First PR in the sequence that mutates working trees; does NOT write to `state/` (verified by a meta-test).",
+        "New sync failure taxonomy in `src/heart/sync-classification.ts`: `auth-failed`, `not-found-404`, `network-down`, `dirty-working-tree`, `non-fast-forward`, `merge-conflict`, `timeout-soft`, `timeout-hard`, `unknown` — extends `PendingSyncRecord.classification` additively (legacy `push_rejected`/`pull_rebase_conflict` still work). Pure pattern-matcher: priority order is abort → 404 → auth → network → dirty → conflict → non-fast-forward → unknown.",
+        "End-to-end `AbortSignal` plumbing. New `runWithTimeouts<T>` wrapper in `src/heart/timeouts.ts` (soft 8s warns, hard 15s aborts via `AbortController`); new async sibling `preTurnPullAsync` in `src/heart/sync.ts` that uses `child_process.execFile(..., { signal })` so the kernel kills the git child when the hard timeout fires. Original sync `preTurnPull` preserved for the per-turn pipeline. Two env knobs for the boot-sync probe: `OURO_BOOT_TIMEOUT_GIT_SOFT` (8000ms) and `OURO_BOOT_TIMEOUT_GIT_HARD` (15000ms).",
+        "New `runBootSyncProbe` orchestrator in `src/heart/daemon/boot-sync-probe.ts` aggregates per-bundle findings (each tagged `advisory: true|false`). Wired into `daemon.up` as a new \"sync probe\" boot phase between manual-clone-detection and provider checks. Failures during the probe itself are caught and surfaced as a warning event without blocking the boot. Tests inject `runBootSyncProbeImpl` to keep CI off the developer's home bundles.",
+        "9903 tests pass (518 files; +19 new). Coverage gate clean (cli-exec.ts 99.33% → 100%). Slow-remote integration test proves boot doesn't hang on a hung remote (probe aborts within `hardMs`). Unit 7 meta-test enforces no-state-writes invariant on the three new files."
+      ]
+    },
     {
       "version": "0.1.0-alpha.517",
       "changes": [

package/dist/heart/daemon/agent-discovery.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLibraryKind = isLibraryKind;
 exports.listAllBundleAgents = listAllBundleAgents;
 exports.listEnabledBundleAgents = listEnabledBundleAgents;
 exports.listBundleSyncRows = listBundleSyncRows;
@@ -41,10 +42,18 @@ const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
+/**
+ * True when the value is the string `"library"`. Library bundles are
+ * content-only resources — never run as agents, never appear in sync surfaces.
+ */
+function isLibraryKind(kind) {
+    return kind === "library";
+}
 /**
  * Walk the bundles root and return one row per `<name>.ouro` directory whose
  * `agent.json` is readable and parseable. Includes both enabled and disabled
- * agents — the caller decides what to do with the `enabled` flag.
+ * agents AND library-kind bundles — callers that need only real agents should
+ * use `listEnabledBundleAgents` (which filters both `enabled` and `kind`).
  *
  * Bundles whose `agent.json` is missing, malformed, or unreadable are skipped
  * silently (they aren't real agents from the harness's perspective).
@@ -76,22 +85,36 @@ function listAllBundleAgents(options = {}) {
         const agentName = entry.name.slice(0, -5);
         const configPath = path.join(bundlesRoot, entry.name, "agent.json");
         let enabled = true;
+        let kind;
         try {
             const raw = readFileSync(configPath, "utf-8");
             const parsed = JSON.parse(raw);
             if (typeof parsed.enabled === "boolean") {
                 enabled = parsed.enabled;
             }
+            if (typeof parsed.kind === "string") {
+                kind = parsed.kind;
+            }
         }
         catch {
             continue;
         }
-        discovered.push({ name: agentName, enabled });
+        const row = { name: agentName, enabled };
+        if (kind !== undefined)
+            row.kind = kind;
+        discovered.push(row);
     }
     return discovered.sort((left, right) => left.name.localeCompare(right.name));
 }
+/**
+ * Real agents only — excludes both disabled bundles and library-kind bundles.
+ * Library bundles (SerpentGuide, RepairGuide, …) are content-only and must
+ * never appear in spawn lists, status rollups, or sync rows.
+ */
 function listEnabledBundleAgents(options = {}) {
-    return listAllBundleAgents(options).filter((row) => row.enabled).map((row) => row.name);
+    return listAllBundleAgents(options)
+        .filter((row) => row.enabled && !isLibraryKind(row.kind))
+        .map((row) => row.name);
 }
 /**
  * Read the per-agent sync block from each enabled bundle's agent.json.

package/dist/heart/daemon/agentic-repair.js

@@ -6,11 +6,50 @@
  * when no local repair was attempted and a working LLM provider is available.
  * This is a lightweight integration: one diagnostic LLM call, not a chat loop.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgenticDiagnosisProviderRuntime = createAgenticDiagnosisProviderRuntime;
 exports.runAgenticRepair = runAgenticRepair;
+exports.shouldFireRepairGuide = shouldFireRepairGuide;
+exports.loadRepairGuideContent = loadRepairGuideContent;
+exports.parseRepairProposals = parseRepairProposals;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
 const interactive_repair_1 = require("./interactive-repair");
+const identity_1 = require("../identity");
 const provider_ping_1 = require("../provider-ping");
 const readiness_repair_1 = require("./readiness-repair");
 function buildSystemPrompt(degraded) {
@@ -29,20 +68,34 @@ function buildSystemPrompt(degraded) {
         "and the simplest fix the user can apply.",
     ].join("\n");
 }
-function buildUserMessage(degraded, logsTail) {
+function buildUserMessage(degraded, logsTail, driftFindings = [], syncFindings = []) {
     const agentDetails = degraded
         .map((d) => `Agent: ${d.agent}\n  Error: ${d.errorReason}\n  Fix hint: ${d.fixHint}`)
         .join("\n\n");
-    return [
+    const sections = [
         "Here are the degraded agents and recent daemon logs:",
         "",
         agentDetails,
         "",
         "Recent daemon logs:",
         logsTail,
-        "",
-        "What is the most likely cause and how should I fix it?",
-    ].join("\n");
+    ];
+    // Layer 3: thread Layer 4's structured drift findings into the prompt as
+    // a JSON block. The `diagnose-bootstrap-drift` skill (loaded into the
+    // system prompt by `buildSystemPromptWithRepairGuide`) instructs the LLM
+    // how to read this shape and what `ouro use` repair to propose.
+    if (driftFindings.length > 0) {
+        sections.push("", "driftFindings (DriftFinding[]):", "```json", JSON.stringify(driftFindings, null, 2), "```");
+    }
+    // Layer 3: thread Layer 2's structured sync-probe findings into the
+    // prompt as a JSON block. `diagnose-broken-remote` (auth/404/network/
+    // timeout-hard) and `diagnose-sync-blocked` (dirty/non-fast-forward/
+    // merge-conflict/timeout-soft) consume this shape.
+    if (syncFindings.length > 0) {
+        sections.push("", "bootSyncFindings (BootSyncProbeFinding[]):", "```json", JSON.stringify(syncFindings, null, 2), "```");
+    }
+    sections.push("", "What is the most likely cause and how should I fix it?");
+    return sections.join("\n");
 }
 function makeInteractiveRepairDeps(deps) {
     return {
@@ -72,11 +125,40 @@ function createAgenticDiagnosisProviderRuntime(provider) {
         model: discoveredProviderModel(provider),
     });
 }
+/**
+ * Layer 3: build the system prompt for the diagnostic call. Prepends
+ * RepairGuide bundle content (`psyche/SOUL.md`, `psyche/IDENTITY.md`, all
+ * skills) when the bundle is present and readable; falls back to today's
+ * pre-RepairGuide prompt when the loader returns null.
+ */
+function buildSystemPromptWithRepairGuide(degraded, repairGuide) {
+    const basePrompt = buildSystemPrompt(degraded);
+    if (repairGuide === null)
+        return basePrompt;
+    const sections = [];
+    if (repairGuide.psyche.soul) {
+        sections.push("# RepairGuide SOUL\n\n" + repairGuide.psyche.soul);
+    }
+    if (repairGuide.psyche.identity) {
+        sections.push("# RepairGuide IDENTITY\n\n" + repairGuide.psyche.identity);
+    }
+    for (const [name, body] of Object.entries(repairGuide.skills)) {
+        sections.push(`# RepairGuide skill: ${name}\n\n${body}`);
+    }
+    if (sections.length === 0)
+        return basePrompt;
+    return [...sections, "---", basePrompt].join("\n\n");
+}
 async function tryAgenticDiagnosis(degraded, provider, deps) {
     const logsTail = deps.readDaemonLogsTail();
     const runtime = deps.createProviderRuntime(provider);
-    const systemPrompt = buildSystemPrompt(degraded);
-    const userMessage = buildUserMessage(degraded, logsTail);
+    // Layer 3: prepend RepairGuide bundle content when present. Loader
+    // returns null on missing bundle / I/O error — caller silently falls back
+    // to today's pre-RepairGuide prompt.
+    const repoRoot = deps.repoRootOverride ?? (0, identity_1.getRepoRoot)();
+    const repairGuide = loadRepairGuideContent(repoRoot);
+    const systemPrompt = buildSystemPromptWithRepairGuide(degraded, repairGuide);
+    const userMessage = buildUserMessage(degraded, logsTail, deps.driftFindings, deps.syncFindings);
     const messages = [
         { role: "system", content: systemPrompt },
         { role: "user", content: userMessage },
@@ -98,11 +180,40 @@ async function tryAgenticDiagnosis(degraded, provider, deps) {
         callbacks: noopCallbacks,
     });
     if (result.content) {
-        deps.writeStdout("");
-        deps.writeStdout("--- AI Diagnosis ---");
-        deps.writeStdout(result.content);
-        deps.writeStdout("--- End Diagnosis ---");
-        deps.writeStdout("");
+        // Layer 3: when RepairGuide content was prepended, parse the LLM output
+        // through the typed-action catalog. If actions are extracted, surface
+        // them as structured proposals; otherwise fall back to today's plain
+        // text-blob diagnosis. `parseRepairProposals` handles the unparseable
+        // case by returning `fallbackBlob` set to the raw output.
+        if (repairGuide !== null) {
+            const parsed = parseRepairProposals(result.content);
+            if (parsed.actions.length > 0) {
+                deps.writeStdout("");
+                deps.writeStdout("--- RepairGuide proposals ---");
+                for (const action of parsed.actions) {
+                    deps.writeStdout(`  • ${action.kind}: ${action.label}`);
+                }
+                for (const warning of parsed.warnings) {
+                    deps.writeStdout(`  (warning) ${warning}`);
+                }
+                deps.writeStdout("--- End RepairGuide proposals ---");
+                deps.writeStdout("");
+            }
+            else if (parsed.fallbackBlob !== undefined) {
+                deps.writeStdout("");
+                deps.writeStdout("--- AI Diagnosis ---");
+                deps.writeStdout(parsed.fallbackBlob);
+                deps.writeStdout("--- End Diagnosis ---");
+                deps.writeStdout("");
+            }
+        }
+        else {
+            deps.writeStdout("");
+            deps.writeStdout("--- AI Diagnosis ---");
+            deps.writeStdout(result.content);
+            deps.writeStdout("--- End Diagnosis ---");
+            deps.writeStdout("");
+        }
     }
     return true;
 }
@@ -119,16 +230,17 @@ async function runAgenticRepair(degraded, deps) {
     }
     const hasLocalRepair = degraded.some(interactive_repair_1.hasRunnableInteractiveRepair);
     const hasKnownTypedRepair = degraded.some((entry) => (0, readiness_repair_1.isKnownReadinessIssue)(entry.issue));
+    const forceDiagnosis = deps.forceDiagnosis === true;
     if (hasLocalRepair) {
         const interactiveResult = await runDeterministicRepair(degraded, deps);
         if (interactiveResult.repairsAttempted) {
             return { repairsAttempted: true, usedAgentic: false };
         }
-        if (hasKnownTypedRepair) {
+        if (hasKnownTypedRepair && !forceDiagnosis) {
             return { repairsAttempted: false, usedAgentic: false };
         }
     }
-    else if (hasKnownTypedRepair) {
+    else if (hasKnownTypedRepair && !forceDiagnosis) {
         return { repairsAttempted: false, usedAgentic: false };
     }
     // Try to discover a working provider for agentic diagnosis
@@ -214,3 +326,229 @@ async function runAgenticRepair(degraded, deps) {
     });
     return { repairsAttempted: interactiveResult.repairsAttempted, usedAgentic };
 }
+// ──────────────────────────────────────────────────────────────────────
+// Layer 3: RepairGuide activation contract
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Threshold for compound typed-degraded findings to activate RepairGuide.
+ * Set to 3 (not 2) so that common pairs — vault-locked + provider-auth-needed,
+ * for example — do NOT trigger the new path on every boot. Encoded once here;
+ * never duplicate at call sites.
+ */
+const REPAIR_GUIDE_TYPED_THRESHOLD = 3;
+/**
+ * Single decision function for whether to fire the RepairGuide-driven
+ * diagnostic flow.
+ *
+ * Contract (LOCKED, planning O4):
+ * - `noRepair: true` → false unconditionally (escape hatch).
+ * - `untypedDegraded.length > 0` → true (preserves today's gate at
+ *   `cli-exec.ts:6706`).
+ * - `typedDegraded.length >= REPAIR_GUIDE_TYPED_THRESHOLD` → true (compound
+ *   stack of typed issues; the new behavior this PR introduces).
+ * - Otherwise → false.
+ */
+function shouldFireRepairGuide(input) {
+    if (input.noRepair)
+        return false;
+    if (input.untypedDegraded.length > 0)
+        return true;
+    if (input.typedDegraded.length >= REPAIR_GUIDE_TYPED_THRESHOLD)
+        return true;
+    return false;
+}
+/**
+ * Read `RepairGuide.ouro/{psyche,skills}/*.md` from the given repo root and
+ * return a structured shape suitable for prepending to a diagnostic LLM call.
+ *
+ * Behavior:
+ * - Returns `null` if `RepairGuide.ouro/` does not exist at all (graceful: caller
+ *   should fall back to today's pre-RepairGuide pipeline).
+ * - Returns `null` on any I/O error (`readdirSync`/`readFileSync` throws).
+ * - Returns a populated `RepairGuideContent` when the bundle exists, even if
+ *   psyche or skills are partially populated.
+ * - Skips files that are not `.md`, are not regular files, or have empty
+ *   contents.
+ * - `skills` map is iterated in alphabetical order so callers can rely on
+ *   deterministic prompt assembly.
+ *
+ * The loader is intentionally inline in `agentic-repair.ts` per the planning
+ * O5 lock — splitting into its own module is allowed only if the validator
+ * grows large.
+ */
+function loadRepairGuideContent(repoRoot) {
+    const bundleRoot = path.join(repoRoot, "RepairGuide.ouro");
+    if (!fs.existsSync(bundleRoot))
+        return null;
+    try {
+        const psyche = {};
+        const skills = {};
+        const psycheDir = path.join(bundleRoot, "psyche");
+        if (fs.existsSync(psycheDir)) {
+            const psycheEntries = fs.readdirSync(psycheDir, { withFileTypes: true });
+            for (const entry of psycheEntries) {
+                if (!entry.isFile() || !entry.name.endsWith(".md"))
+                    continue;
+                const content = fs.readFileSync(path.join(psycheDir, entry.name), "utf-8");
+                if (entry.name === "SOUL.md")
+                    psyche.soul = content;
+                else if (entry.name === "IDENTITY.md")
+                    psyche.identity = content;
+            }
+        }
+        const skillsDir = path.join(bundleRoot, "skills");
+        if (fs.existsSync(skillsDir)) {
+            const skillEntries = fs.readdirSync(skillsDir, { withFileTypes: true });
+            const sorted = skillEntries
+                .filter((e) => e.isFile() && e.name.endsWith(".md"))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of sorted) {
+                const content = fs.readFileSync(path.join(skillsDir, entry.name), "utf-8");
+                if (content.length === 0)
+                    continue;
+                skills[entry.name] = content;
+            }
+        }
+        return { psyche, skills };
+    }
+    catch {
+        // Best-effort: any I/O error in the bundle leads to null and the caller
+        // falls back to today's pre-RepairGuide diagnostic prompt.
+        return null;
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// Layer 3: RepairGuide LLM output parser → typed `RepairAction[]`
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * The set of `RepairActionKind` literals the typed catalog recognizes.
+ * Encoded once here; the parser uses this for membership checks. Any other
+ * kind in the LLM output is dropped with a warning.
+ */
+const KNOWN_REPAIR_ACTION_KINDS = new Set([
+    "vault-create",
+    "vault-unlock",
+    "vault-replace",
+    "vault-recover",
+    "provider-auth",
+    "provider-retry",
+    "provider-use",
+]);
+function extractFirstJsonBlock(text) {
+    // Look for a triple-backtick fence labeled `json` and grab its body.
+    const fenceMatch = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+    if (fenceMatch)
+        return fenceMatch[1];
+    // Fallback: the LLM may have emitted a bare JSON object (no fence).
+    const objectMatch = text.match(/\{[\s\S]*\}/);
+    if (objectMatch)
+        return objectMatch[0];
+    return null;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a single LLM-emitted action object into a typed `RepairAction`. Returns
+ * `null` when the entry is shaped wrong — the caller logs a warning and drops
+ * it. The parser backfills `label`, `command`, and `actor` so the result plugs
+ * into the existing interactive-repair surface without further massaging.
+ */
+function buildRepairAction(entry) {
+    const kind = entry.kind;
+    if (typeof kind !== "string")
+        return null;
+    if (!KNOWN_REPAIR_ACTION_KINDS.has(kind))
+        return null;
+    const reason = typeof entry.reason === "string" ? entry.reason : "(no reason given)";
+    const agent = typeof entry.agent === "string" ? entry.agent : "(unknown agent)";
+    const label = `RepairGuide: ${kind} for ${agent}`;
+    const command = `# ${kind} (${agent}): ${reason}`;
+    switch (kind) {
+        case "provider-auth": {
+            const provider = typeof entry.provider === "string" ? entry.provider : "anthropic";
+            return {
+                kind: "provider-auth",
+                label,
+                command,
+                actor: "human-required",
+                provider: provider,
+            };
+        }
+        case "provider-use": {
+            // `provider-use` may carry an optional `lane` — pass it through when
+            // present and validly typed (`outward` or `inner`).
+            const lane = entry.lane === "outward" || entry.lane === "inner" ? entry.lane : undefined;
+            const action = {
+                kind: "provider-use",
+                label,
+                command,
+                actor: "human-choice",
+                ...(lane ? { lane } : {}),
+            };
+            return action;
+        }
+        case "vault-create":
+        case "vault-unlock":
+        case "vault-replace":
+        case "vault-recover":
+        case "provider-retry": {
+            return {
+                kind: kind,
+                label,
+                command,
+                actor: "human-required",
+            };
+        }
+        /* v8 ignore next 4 -- exhaustiveness guard: unreachable since membership
+         * was checked above; left in place to satisfy `never` on future
+         * RepairActionKind extensions. @preserve */
+        default: {
+            return null;
+        }
+    }
+}
+/**
+ * Parse RepairGuide LLM output. The persona content (`SOUL.md`) instructs the
+ * model to emit exactly one ```json fenced block containing
+ * `{ actions: RepairAction[], notes?: string[] }`. The parser extracts that
+ * block, walks `actions[]`, drops entries with unknown kinds (with warnings),
+ * and falls back to the raw output when no JSON can be extracted at all
+ * (preserving today's text-blob behavior).
+ */
+function parseRepairProposals(llmOutput) {
+    const block = extractFirstJsonBlock(llmOutput);
+    if (block === null) {
+        return { actions: [], warnings: [], fallbackBlob: llmOutput };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(block);
+    }
+    catch {
+        return { actions: [], warnings: [], fallbackBlob: llmOutput };
+    }
+    if (!isPlainObject(parsed)) {
+        return { actions: [], warnings: [] };
+    }
+    const rawActions = parsed.actions;
+    if (!Array.isArray(rawActions)) {
+        return { actions: [], warnings: [] };
+    }
+    const actions = [];
+    const warnings = [];
+    for (const entry of rawActions) {
+        if (!isPlainObject(entry)) {
+            warnings.push(`dropped non-object entry from actions[]: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        const built = buildRepairAction(entry);
+        if (built === null) {
+            const kindLabel = typeof entry.kind === "string" ? entry.kind : "(no kind)";
+            warnings.push(`dropped action with unknown or missing kind: ${kindLabel}`);
+            continue;
+        }
+        actions.push(built);
+    }
+    return { actions, warnings };
+}