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

package/dist/heart/daemon/boot-sync-probe.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Boot sync probe — Layer 2 orchestrator for `ouro up`.
+ *
+ * For each sync-enabled bundle, runs `preTurnPullAsync` wrapped in
+ * `runWithTimeouts`, classifies failures via `classifySyncFailure`, and
+ * returns aggregated findings. Findings surface in the boot stdout
+ * summary written by `cli-exec.ts` after the probe phase.
+ *
+ * Layer 2 is intentionally a **boot-time preflight surface only** — it
+ * does NOT feed into the running daemon's rollup state. `computeDaemonRollup`
+ * is unaware of these findings; nothing is persisted to daemon health for
+ * the running daemon to consume. Layer 3 RepairGuide is the planned consumer
+ * (it reads the in-memory `BootSyncProbeFinding[]` at boot time and
+ * dispatches the right diagnostic skill).
+ *
+ * The probe NEVER:
+ *   - Writes to `state/` (verified by Unit 7's grep gate).
+ *   - Throws — every failure becomes a finding.
+ *   - Hangs — `AbortSignal` from `runWithTimeouts` cuts hung remotes
+ *     within `hardMs`.
+ *
+ * Advisory vs blocking classifications (consumed by layer 3, not by the
+ * layer 1 rollup — see comment above):
+ *
+ *   | classification         | advisory? | rationale                                   |
+ *   | ---------------------- | --------- | ------------------------------------------- |
+ *   | auth-failed            | no        | agent can't sync; needs human intervention  |
+ *   | not-found-404          | no        | remote is gone; needs human intervention    |
+ *   | network-down           | no        | agent can't reach the remote at all         |
+ *   | timeout-hard           | no        | abort cut the op; remote is hung            |
+ *   | dirty-working-tree     | yes       | local edits prevent merge; agent still runs |
+ *   | non-fast-forward       | yes       | local commits ahead; agent still runs       |
+ *   | merge-conflict         | yes       | rebase failed; needs cleanup                |
+ *   | timeout-soft           | yes       | warning surfaced, op completed              |
+ *   | unknown                | yes       | unrecognised; surface for diagnosis         |
+ *
+ * `advisory: true` is a hint for layer 3 ("warn-and-continue, agent likely
+ * still works") vs `advisory: false` ("blocking, agent can't sync until
+ * fixed"). Layer 3 will route the right diagnostic skill on this signal.
+ */
+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.runBootSyncProbe = runBootSyncProbe;
+const path = __importStar(require("path"));
+const sync_1 = require("../sync");
+const sync_classification_1 = require("../sync-classification");
+const timeouts_1 = require("../timeouts");
+const runtime_1 = require("../../nerves/runtime");
+/** Default soft / hard timeout windows for the boot git op. Matches Layer 2 O1 lock. */
+const DEFAULT_SOFT_MS = 8000;
+const DEFAULT_HARD_MS = 15000;
+const BLOCKING_CLASSIFICATIONS = new Set([
+    "auth-failed",
+    "not-found-404",
+    "network-down",
+    "timeout-hard",
+]);
+function isAdvisory(classification) {
+    return !BLOCKING_CLASSIFICATIONS.has(classification);
+}
+/**
+ * Probe sync state for every enabled, git-initialised bundle. Returns
+ * findings for every non-clean result. Probes run sequentially (not in
+ * parallel) so the boot path's progress reporter has a stable per-agent
+ * narrative; the per-probe hard cap means worst-case total wait is
+ * `bundles.length * hardMs`, which is acceptable for typical 1-3 agent
+ * deployments.
+ */
+async function runBootSyncProbe(bundles, options) {
+    const startedAt = Date.now();
+    const softMs = options.softMs ?? DEFAULT_SOFT_MS;
+    const hardMs = options.hardMs ?? DEFAULT_HARD_MS;
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.boot_sync_probe_start",
+        message: "boot sync probe starting",
+        meta: { bundleCount: bundles.length, softMs, hardMs },
+    });
+    const findings = [];
+    for (const bundle of bundles) {
+        if (!bundle.enabled)
+            continue;
+        const agentRoot = path.join(options.bundlesRoot, `${bundle.agent}.ouro`);
+        // gitInitialized=false: bundle is enabled for sync but never had `git init`.
+        // Surface as advisory finding without invoking git.
+        if (bundle.gitInitialized === false) {
+            findings.push({
+                agent: bundle.agent,
+                classification: "unknown",
+                error: `bundle is not a git repo; run \`git init\` inside ${agentRoot} to enable sync (or disable sync in agent.json)`,
+                conflictFiles: [],
+                warnings: [],
+                advisory: true,
+            });
+            continue;
+        }
+        const syncConfig = { enabled: bundle.enabled, remote: bundle.remote };
+        const outcome = await (0, timeouts_1.runWithTimeouts)((signal) => (0, sync_1.preTurnPullAsync)(agentRoot, syncConfig, { signal }), { softMs, hardMs, label: `boot-sync-probe ${bundle.agent}`, envKey: "GIT" });
+        // Hard timeout — the probe was aborted. Synthesise a finding from the
+        // outcome's classification (the underlying `preTurnPullAsync` may also
+        // have rejected with an AbortError, but the wrapper already swallowed
+        // it).
+        if (outcome.classification === "timeout-hard") {
+            findings.push({
+                agent: bundle.agent,
+                classification: "timeout-hard",
+                error: `boot sync probe for ${bundle.agent} aborted after ${hardMs}ms hard timeout`,
+                conflictFiles: [],
+                warnings: outcome.warnings,
+                advisory: isAdvisory("timeout-hard"),
+            });
+            continue;
+        }
+        const result = outcome.result;
+        /* v8 ignore start -- defensive: exclusive state from runWithTimeouts contract — either result or classification, never both undefined @preserve */
+        if (!result) {
+            findings.push({
+                agent: bundle.agent,
+                classification: "unknown",
+                error: "boot sync probe returned without result or classification",
+                conflictFiles: [],
+                warnings: outcome.warnings,
+                advisory: true,
+            });
+            continue;
+        }
+        /* v8 ignore stop */
+        if (!result.ok) {
+            const classification = (0, sync_classification_1.classifySyncFailure)(new Error(result.error ?? "unknown sync error"), { agentRoot });
+            findings.push({
+                agent: bundle.agent,
+                classification: classification.classification,
+                error: classification.error,
+                conflictFiles: classification.conflictFiles,
+                warnings: outcome.warnings,
+                advisory: isAdvisory(classification.classification),
+            });
+            continue;
+        }
+        // Probe succeeded. If the soft warning fired, surface it as an advisory
+        // finding so the operator sees the slow-pull warning even on success.
+        if (outcome.warnings.length > 0) {
+            findings.push({
+                agent: bundle.agent,
+                classification: "timeout-soft",
+                error: outcome.warnings.join("; "),
+                conflictFiles: [],
+                warnings: outcome.warnings,
+                advisory: true,
+            });
+        }
+    }
+    // Stable order — sort by agent name so renderers and tests see the same
+    // sequence.
+    findings.sort((a, b) => a.agent.localeCompare(b.agent));
+    const durationMs = Date.now() - startedAt;
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.boot_sync_probe_end",
+        message: "boot sync probe complete",
+        meta: { findingCount: findings.length, durationMs },
+    });
+    return { findings, durationMs };
+}

package/dist/heart/daemon/cli-defaults.js

@@ -432,7 +432,10 @@ async function defaultRunSerpentGuide() {
         const { createLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves")));
         setRuntimeLogger(createLogger({ level: "error" }));
         // Configure runtime: set agent identity + config override so runAgent
-        // doesn't try to read from ~/AgentBundles/SerpentGuide.ouro/
+        // doesn't try to read from ~/AgentBundles/SerpentGuide.ouro/. (As of
+        // Layer 3, SerpentGuide identities live in-repo only — the
+        // `~/AgentBundles/SerpentGuide.ouro/psyche/identities` override path
+        // was removed. The override path is no longer read or honored.)
         setAgentName("SerpentGuide");
         // Build specialist system prompt
         const soulText = (0, specialist_orchestrator_1.loadSoulText)(bundleSourceDir);

package/dist/heart/daemon/cli-exec.js

@@ -42,6 +42,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.summarizeDaemonStartupFailure = summarizeDaemonStartupFailure;
 exports.writeDriftAdvisorySummary = writeDriftAdvisorySummary;
 exports.collectAgentDriftAdvisories = collectAgentDriftAdvisories;
+exports.writeSyncProbeSummary = writeSyncProbeSummary;
+exports.summarizeSyncProbeFindings = summarizeSyncProbeFindings;
 exports.mergeStartupStability = mergeStartupStability;
 exports.ensureDaemonRunning = ensureDaemonRunning;
 exports.listGithubCopilotModels = listGithubCopilotModels;
@@ -110,6 +112,7 @@ const up_progress_1 = require("./up-progress");
 const provider_ping_progress_1 = require("./provider-ping-progress");
 const provider_ping_1 = require("../provider-ping");
 const agent_discovery_1 = require("./agent-discovery");
+const boot_sync_probe_1 = require("./boot-sync-probe");
 const connect_bay_1 = require("./connect-bay");
 const runtime_capability_check_1 = require("../runtime-capability-check");
 const vault_items_1 = require("./vault-items");
@@ -471,10 +474,44 @@ function providerRepairCountSummary(count) {
         return "selected providers answered live checks";
     return `${count} ${count === 1 ? "needs" : "need"} attention`;
 }
+/**
+ * Layer 2: human-readable summary of boot-sync-probe findings, written to
+ * stdout when any non-clean finding surfaces. The order reads "blockers
+ * first, then advisories" so the operator's eye lands on the actionable
+ * items before the warnings.
+ */
+function writeSyncProbeSummary(deps, findings) {
+    const lines = ["sync probe findings:"];
+    const sortKey = (f) => (f.advisory ? 1 : 0);
+    const sorted = [...findings].sort((a, b) => sortKey(a) - sortKey(b) || a.agent.localeCompare(b.agent));
+    for (const finding of sorted) {
+        const severity = finding.advisory ? "warn" : "block";
+        lines.push(`  [${severity}] ${finding.agent}: ${finding.classification} — ${finding.error.split("\n")[0]}`);
+    }
+    deps.writeStdout(lines.join("\n"));
+}
 function bootPhasePlan(daemonAlive) {
     return daemonAlive
-        ? ["update check", "system setup", "starting daemon", "provider checks", "final daemon check"]
-        : ["update check", "system setup", "provider checks", "starting daemon", "final daemon check"];
+        ? ["update check", "system setup", "sync probe", "starting daemon", "provider checks", "final daemon check"]
+        : ["update check", "system setup", "sync probe", "provider checks", "starting daemon", "final daemon check"];
+}
+/**
+ * Layer 2: brief, scannable summary of a boot-sync-probe finding for the
+ * progress reporter. Renderer-style hints (full repair guidance) live in
+ * `inner-status.ts` / `startup-tui.ts` consumers; this helper is just for
+ * the progress phase blurb.
+ */
+function summarizeSyncProbeFindings(findings) {
+    if (findings.length === 0)
+        return "all sync-enabled bundles healthy";
+    const blocking = findings.filter((f) => !f.advisory).length;
+    const advisory = findings.filter((f) => f.advisory).length;
+    const parts = [];
+    if (blocking > 0)
+        parts.push(`${blocking} blocking`);
+    if (advisory > 0)
+        parts.push(`${advisory} advisory`);
+    return `${findings.length} finding${findings.length === 1 ? "" : "s"} (${parts.join(", ")})`;
 }
 function createHumanCommandProgress(deps, commandName) {
     return new up_progress_1.CommandProgress({
@@ -5707,6 +5744,45 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             bundlesRoot: deps.bundlesRoot ?? bundlesRoot,
             promptInput: deps.promptInput,
         });
+        // ── Layer 2 sync probe: pre-flight `git pull` for every sync-enabled bundle ──
+        // Runs BEFORE provider checks so that any agent.json changes pulled from
+        // the remote are visible to the live-check that follows. The probe has a
+        // hard 15s per-agent timeout via `runWithTimeouts`, so a hung remote
+        // can't stall the boot. `--no-repair` doesn't change probe behavior — it
+        // gates layer 3's RepairGuide invocation, which lands in a separate PR.
+        //
+        // Errors in the probe path itself are caught and logged — they must not
+        // break the boot, since the probe is best-effort visibility, not a gate.
+        // Layer 3: hoist sync-probe findings to outer scope so the
+        // RepairGuide diagnostic call later in this function can include
+        // them in its prompt. Default to [] when the probe was skipped or
+        // threw — the runAgenticRepair callsite then sees "no sync
+        // findings to report" rather than missing data.
+        let bootSyncFindings = [];
+        progress.startPhase("sync probe");
+        try {
+            const syncProbeImpl = deps.runBootSyncProbeImpl ?? boot_sync_probe_1.runBootSyncProbe;
+            const syncRows = (0, agent_discovery_1.listBundleSyncRows)({ bundlesRoot: deps.bundlesRoot ?? bundlesRoot });
+            const syncProbeResult = await syncProbeImpl(syncRows, {
+                bundlesRoot: deps.bundlesRoot ?? bundlesRoot,
+            });
+            bootSyncFindings = syncProbeResult.findings;
+            progress.completePhase("sync probe", summarizeSyncProbeFindings(syncProbeResult.findings));
+            if (syncProbeResult.findings.length > 0) {
+                writeSyncProbeSummary(deps, syncProbeResult.findings);
+            }
+        }
+        catch (probeError) {
+            const message = probeError instanceof Error ? probeError.message : String(probeError);
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.boot_sync_probe_failed",
+                message: "boot sync probe failed; continuing boot",
+                meta: { error: message },
+            });
+            progress.completePhase("sync probe", "skipped (probe error)");
+        }
         const daemonAliveBeforeStart = await deps.checkSocketAlive(deps.socketPath);
         progress.setPhasePlan?.(bootPhasePlan(daemonAliveBeforeStart));
         let providerChecksAlreadyRun = false;
@@ -5808,8 +5884,35 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                         typedDegraded.forEach((entry) => repairedAgents.add(entry.agent));
                     }
                 }
-                if (untypedDegraded.length > 0) {
-                    const repairResult = await (0, agentic_repair_1.runAgenticRepair)(untypedDegraded, {
+                // Layer 3: extended activation contract — fires when there are
+                // untyped degraded entries OR when typed entries stack to ≥3 (compound
+                // situations that warrant a RepairGuide-driven proposal pass). The
+                // `--no-repair` flag short-circuits the entire decision via
+                // `shouldFireRepairGuide`. The set passed into `runAgenticRepair` is
+                // the union of typed + untyped so the diagnostic prompt has the full
+                // picture. When the gate fires solely on typed-stacking,
+                // `runAgenticRepair` is told via `forceDiagnosis: true` to bypass the
+                // early-return that normally defers typed-only sets to the
+                // deterministic typed repair flow that already ran above.
+                const repairGuideShouldFire = (0, agentic_repair_1.shouldFireRepairGuide)({
+                    untypedDegraded,
+                    typedDegraded,
+                    noRepair: Boolean(command.noRepair),
+                });
+                if (repairGuideShouldFire) {
+                    const repairInput = [...untypedDegraded, ...typedDegraded];
+                    const forceDiagnosis = untypedDegraded.length === 0 && typedDegraded.length >= 3;
+                    // Layer 3: collect drift findings here so the RepairGuide
+                    // prompt receives them as a structured JSON block. Drift is
+                    // already collected for the no-repair path above; we collect
+                    // again here because the repair path is a separate branch.
+                    // Filter to agents in repairInput so the diagnostic prompt
+                    // doesn't carry drift from healthy peers — narrows the
+                    // signal to the set being diagnosed.
+                    const repairAgentNames = new Set(repairInput.map((entry) => entry.agent));
+                    const repairDriftFindings = (await collectAgentDriftAdvisories(deps))
+                        .filter((finding) => repairAgentNames.has(finding.agent));
+                    const repairResult = await (0, agentic_repair_1.runAgenticRepair)(repairInput, {
                         /* v8 ignore start -- production provider discovery wiring @preserve */
                         discoverWorkingProvider: async (agentName) => {
                             const { discoverWorkingProvider: discover } = await Promise.resolve().then(() => __importStar(require("./provider-discovery")));
@@ -5853,6 +5956,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                         skipQueueSummary: true,
                         isTTY: deps.isTTY ?? process.stdout.isTTY === true,
                         stdoutColumns: deps.stdoutColumns ?? process.stdout.columns,
+                        forceDiagnosis,
+                        driftFindings: repairDriftFindings,
+                        syncFindings: bootSyncFindings,
                     });
                     if (repairResult.repairsAttempted) {
                         repairsAttempted = true;

package/dist/heart/hatch/hatch-specialist.js

@@ -38,15 +38,13 @@ exports.getRepoSpecialistIdentitiesDir = getRepoSpecialistIdentitiesDir;
 exports.syncSpecialistIdentities = syncSpecialistIdentities;
 exports.pickRandomSpecialistIdentity = pickRandomSpecialistIdentity;
 const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
 function getSpecialistIdentitySourceDir() {
-    // Prefer ~/AgentBundles/ if it exists (user may have customized identities)
-    const userSource = path.join(os.homedir(), "AgentBundles", "SerpentGuide.ouro", "psyche", "identities");
-    if (fs.existsSync(userSource))
-        return userSource;
-    // Fall back to the bundled copy shipped with the npm package
+    // Layer 3: in-repo is the only source. The previous `~/AgentBundles/`
+    // override branch was removed because there's no scenario where an
+    // operator should be editing identities outside the repo — they should
+    // edit the in-repo copy and let the daemon read from there.
     return path.join(__dirname, "..", "..", "..", "SerpentGuide.ouro", "psyche", "identities");
 }
 function getRepoSpecialistIdentitiesDir() {

package/dist/heart/sync-classification.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Sync failure taxonomy classifier — Layer 2 of the harness-hardening sequence.
+ *
+ * Pure pattern-matcher over (error, context) that turns common git failure
+ * shapes into the locked taxonomy variants. Used by `runBootSyncProbe` (the
+ * `ouro up` pre-flight pull orchestrator) and by `postTurnPush`'s legacy
+ * push-rejected/conflict path so both producers share one vocabulary.
+ *
+ * Pattern priority — most actionable / specific wins:
+ *   1. Abort signal (timeout-soft / timeout-hard) — caller explicitly aborted.
+ *   2. not-found-404 — 404 / "Repository not found": remote endpoint gone.
+ *   3. auth-failed — 401 / 403 / "Authentication failed".
+ *   4. network-down — ENOTFOUND / ECONNREFUSED / "Could not resolve host".
+ *   5. dirty-working-tree — "would be overwritten" / "stash them".
+ *   6. merge-conflict — CONFLICT marker in stderr (also collects file list).
+ *   7. non-fast-forward — "non-fast-forward" / "fetch first".
+ *   8. unknown — fallthrough.
+ *
+ * The classifier never throws and never writes to disk. It calls
+ * `git status --porcelain=v1` only when it has already classified the error
+ * as a merge conflict, to enumerate unmerged paths for the consumer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySyncFailure = classifySyncFailure;
+const child_process_1 = require("child_process");
+/**
+ * Enumerate unmerged paths via `git status --porcelain=v1`. Pulled out as a
+ * pure helper so the classifier can be tested without a live git repo (the
+ * caller mocks `child_process.execFileSync`).
+ *
+ * Mirrors `sync.ts:collectRebaseConflictFiles` — kept as a separate copy here
+ * so this module has zero internal dep on `sync.ts`. The caller of
+ * `classifySyncFailure` doesn't see the duplication; the runtime cost is one
+ * git invocation per merge-conflict classification, same as before.
+ */
+function collectConflictFiles(agentRoot) {
+    try {
+        const output = (0, child_process_1.execFileSync)("git", ["status", "--porcelain=v1"], {
+            cwd: agentRoot,
+            stdio: "pipe",
+            timeout: 5000,
+        }).toString();
+        const files = [];
+        for (const line of output.split("\n")) {
+            // Unmerged paths in porcelain v1 are prefixed with UU/AA/DD/AU/UA/DU/UD.
+            if (/^(UU|AA|DD|AU|UA|DU|UD) /.test(line)) {
+                files.push(line.slice(3).trim());
+            }
+        }
+        return files;
+    }
+    catch {
+        /* v8 ignore next -- defensive: git status failure inside a git repo would require a corrupt repo @preserve */
+        return [];
+    }
+}
+function isAbortError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const candidate = error;
+    if (candidate.name === "AbortError")
+        return true;
+    if (candidate.code === "ABORT_ERR")
+        return true;
+    return false;
+}
+function readMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    if (error === null || error === undefined)
+        return String(error);
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        /* v8 ignore next -- defensive: JSON.stringify only fails on circular/BigInt; real-world git errors don't trigger it @preserve */
+        return String(error);
+    }
+}
+function readErrorCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Classify a sync failure into one of the locked taxonomy variants.
+ *
+ * Pure: never throws, never writes. Calls `git status` only when the error
+ * was already classified as a merge conflict, to enumerate unmerged files.
+ */
+function classifySyncFailure(error, context) {
+    const message = readMessage(error);
+    const errorCode = readErrorCode(error);
+    // 1. Abort signal — highest priority. Caller's signal trumps content match.
+    if (isAbortError(error)) {
+        const reason = context.abortReason ?? "hard";
+        return {
+            classification: reason === "soft" ? "timeout-soft" : "timeout-hard",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // Lowercased copy for case-insensitive substring matching.
+    const lower = message.toLowerCase();
+    // 2. Not-found-404 — most actionable diagnosis when both 404 and other
+    // signals are present. "404" and "Repository not found" are the canonical
+    // shapes.
+    if (lower.includes("404") || lower.includes("repository not found")) {
+        return {
+            classification: "not-found-404",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // 3. Auth failed — 401 / 403 / "Authentication failed" / "Permission denied".
+    if (lower.includes("401")
+        || lower.includes("403")
+        || lower.includes("authentication failed")
+        || lower.includes("permission denied")) {
+        return {
+            classification: "auth-failed",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // 4. Network down — DNS / connection errors.
+    if (errorCode === "ENOTFOUND"
+        || errorCode === "ECONNREFUSED"
+        || lower.includes("enotfound")
+        || lower.includes("econnrefused")
+        || lower.includes("could not resolve host")
+        || lower.includes("connection refused")) {
+        return {
+            classification: "network-down",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // 5. Dirty working tree — pull / merge would clobber uncommitted changes.
+    if (lower.includes("would be overwritten")
+        || lower.includes("commit your changes or stash them")) {
+        return {
+            classification: "dirty-working-tree",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // 6. Merge conflict — CONFLICT marker in stderr. Collect unmerged files.
+    if (lower.includes("conflict")) {
+        return {
+            classification: "merge-conflict",
+            error: message,
+            conflictFiles: collectConflictFiles(context.agentRoot),
+        };
+    }
+    // 7. Non-fast-forward — push rejected because remote moved.
+    if (lower.includes("non-fast-forward")
+        || lower.includes("fetch first")
+        || lower.includes("rejected")) {
+        return {
+            classification: "non-fast-forward",
+            error: message,
+            conflictFiles: [],
+        };
+    }
+    // 8. Fallthrough.
+    return {
+        classification: "unknown",
+        error: message,
+        conflictFiles: [],
+    };
+}