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

package/changelog.json

@@ -1,6 +1,16 @@
 {
   "_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.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/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-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,38 @@ 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.
+        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,
+            });
+            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;

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: [],
+    };
+}

package/dist/heart/sync.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preTurnPull = preTurnPull;
 exports.postTurnPush = postTurnPush;
+exports.preTurnPullAsync = preTurnPullAsync;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -330,3 +331,119 @@ function postTurnPush(agentRoot, config) {
         return { ok: false, error };
     }
 }
+/**
+ * Layer 2 — async, signal-aware sibling of `preTurnPull`.
+ *
+ * Used by `runBootSyncProbe` (the `ouro up` boot orchestrator) to perform
+ * the pre-flight pull with end-to-end `AbortSignal` propagation. The
+ * underlying `child_process.execFile` accepts the signal and kills the git
+ * child process when it aborts, so a hung remote (DNS hole, slow server)
+ * can be cut by the boot timeout wrapper rather than hanging the whole
+ * boot.
+ *
+ * The legacy sync `preTurnPull` is preserved unchanged for the per-turn
+ * pipeline at `src/senses/pipeline.ts:522`. The two functions share the
+ * same `.git` and remote-availability gates — the only difference is the
+ * pull itself: `execFileSync` (no signal) vs `execFile` + `{ signal }`.
+ *
+ * Honour-the-signal contract:
+ *   - If `options.signal` is already aborted at call time, the pull is
+ *     skipped and the result is `{ ok: false, error: "aborted" }`.
+ *   - If `options.signal` aborts mid-fetch, the child receives `SIGTERM`
+ *     via Node's built-in AbortSignal handling, and the result is
+ *     `{ ok: false, error: <abort message> }`.
+ *   - With no signal supplied, behaviour matches the sync version (subject
+ *     to the small differences listed above — same git-repo / no-remote
+ *     gates and same nerves events).
+ */
+function preTurnPullAsync(agentRoot, config, options = {}) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_pull_start",
+        message: "pre-turn pull starting (async)",
+        meta: { agentRoot, remote: config.remote },
+    });
+    // Bail early when the caller has already aborted — saves a git invocation
+    // and signals failure consistently.
+    if (options.signal?.aborted) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_pull_aborted",
+            message: "pre-turn pull skipped: signal already aborted",
+            meta: { agentRoot },
+        });
+        return Promise.resolve({ ok: false, error: "aborted before pull started" });
+    }
+    // Same .git presence check as the sync version.
+    const repoCheck = ensureGitRepo(agentRoot);
+    if (!repoCheck.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_not_a_repo",
+            message: "pre-turn pull failed: bundle is not a git repo (async)",
+            meta: { agentRoot },
+        });
+        return Promise.resolve(repoCheck);
+    }
+    // Remote-presence check stays sync — it's a fast local op and doesn't
+    // need cancellation. The hangable op is the actual pull.
+    try {
+        const remoteOutput = (0, child_process_1.execFileSync)("git", ["remote"], {
+            cwd: agentRoot,
+            stdio: "pipe",
+            timeout: 5000,
+        }).toString().trim();
+        if (remoteOutput.length === 0) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "heart",
+                event: "heart.sync_pull_end",
+                message: "pre-turn pull skipped: no remote configured (async)",
+                meta: { agentRoot },
+            });
+            return Promise.resolve({ ok: true });
+        }
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.sync_pull_error",
+            message: "pre-turn pull failed: git remote check failed (async)",
+            meta: { agentRoot, error },
+        });
+        return Promise.resolve({ ok: false, error });
+    }
+    // The hangable op. `execFile` accepts `{ signal }` and kills the child
+    // when the signal aborts — that's the whole point of the async path.
+    const execOptions = {
+        cwd: agentRoot,
+        timeout: 30000,
+    };
+    if (options.signal) {
+        execOptions.signal = options.signal;
+    }
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)("git", ["pull", config.remote], execOptions, (err) => {
+            if (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "heart",
+                    event: "heart.sync_pull_error",
+                    message: "pre-turn pull failed (async)",
+                    meta: { agentRoot, error },
+                });
+                resolve({ ok: false, error });
+                return;
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "heart",
+                event: "heart.sync_pull_end",
+                message: "pre-turn pull complete (async)",
+                meta: { agentRoot },
+            });
+            resolve({ ok: true });
+        });
+    });
+}

package/dist/heart/timeouts.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Soft/hard timeout pattern for boot-path operations — Layer 2.
+ *
+ * Soft timeout = "log a warning, keep going". The op continues; the consumer
+ * records the warning and moves on.
+ * Hard timeout = "abort the op via AbortSignal". The underlying op is
+ * expected to honour the signal (Node child_process accepts `{ signal }`,
+ * fetch accepts `{ signal }`, etc.). When the signal aborts, the op should
+ * reject with an AbortError, and the wrapper returns
+ * `{ classification: "timeout-hard" }` rather than re-throwing.
+ *
+Two optional env overrides (currently only `GIT` is consumed):
+ *   - `OURO_BOOT_TIMEOUT_GIT_SOFT` / `OURO_BOOT_TIMEOUT_GIT_HARD` — boot
+ *     git operations (fetch / pull). Used when `envKey === "GIT"`.
+ *
+ * Env values are parsed as integer milliseconds. Non-numeric or non-positive
+ * values are ignored (the explicit `softMs` / `hardMs` defaults from the
+ * caller win in that case).
+ *
+ * Pattern guarantee: timers cleared on resolve / reject so the function
+ * holds no refs after settlement. Important because `ouro up` chains
+ * many of these and a leaking timer would block process exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithTimeouts = runWithTimeouts;
+function readEnvMs(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === null)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return parsed;
+}
+function resolveTimeouts(options) {
+    let softMs = options.softMs;
+    let hardMs = options.hardMs;
+    if (options.envKey === "GIT") {
+        const envSoft = readEnvMs("OURO_BOOT_TIMEOUT_GIT_SOFT");
+        if (envSoft !== null)
+            softMs = envSoft;
+        const envHard = readEnvMs("OURO_BOOT_TIMEOUT_GIT_HARD");
+        if (envHard !== null)
+            hardMs = envHard;
+    }
+    return { softMs, hardMs };
+}
+/**
+ * Run `fn` with soft and hard timeouts.
+ *
+ * - Returns `{ result }` on success.
+ * - Returns `{ classification: "timeout-hard", warnings }` when aborted.
+ * - Returns `{ result, warnings: [...] }` when soft tripped but op completed.
+ * - Rejects when `fn` throws a non-abort error (callers can wrap with
+ *   classifier).
+ */
+async function runWithTimeouts(fn, options) {
+    const { softMs, hardMs } = resolveTimeouts(options);
+    const controller = new AbortController();
+    const warnings = [];
+    let softTimer = setTimeout(() => {
+        softTimer = null;
+        warnings.push(`${options.label}: soft timeout exceeded (${softMs}ms) — warning, continuing until hard cut`);
+    }, softMs);
+    let hardTimer = setTimeout(() => {
+        hardTimer = null;
+        controller.abort();
+    }, hardMs);
+    const cleanup = () => {
+        if (softTimer !== null) {
+            clearTimeout(softTimer);
+            softTimer = null;
+        }
+        if (hardTimer !== null) {
+            clearTimeout(hardTimer);
+            hardTimer = null;
+        }
+    };
+    try {
+        const result = await fn(controller.signal);
+        cleanup();
+        // If the abort fired and the op resolved gracefully (e.g., the inner
+        // function caught the AbortError and returned a structured result), we
+        // still classify the outcome as timeout-hard — the op was aborted from
+        // the caller's perspective even if no exception propagated. The caller
+        // can ignore the classification and use `result` if both are present.
+        if (controller.signal.aborted) {
+            return { classification: "timeout-hard", warnings };
+        }
+        return { result, warnings };
+    }
+    catch (err) {
+        cleanup();
+        if (controller.signal.aborted) {
+            // Hard timeout fired — abort wins over whatever error the op threw.
+            return { classification: "timeout-hard", warnings };
+        }
+        throw err;
+    }
+}

package/dist/nerves/coverage/file-completeness.js

@@ -149,6 +149,15 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // Diagnostics-only utility; output is human-readable summary.
     "heart/session-stats-cli-main",
     "heart/session-stats",
+    // Layer 2 sync classifier: pure pattern-matcher mapping (error, context)
+    // to a SyncClassification. The orchestrator (boot-sync-probe.ts) owns
+    // observability via daemon.boot_sync_probe_start/end events; the
+    // post-turn push path (sync.ts) emits its own classification events.
+    "heart/sync-classification",
+    // Layer 2 timeout wrapper: pure soft/hard timeout abstraction over
+    // AbortController + setTimeout. Callers (boot-sync-probe.ts and any
+    // future consumer) own observability; the wrapper itself is mechanical.
+    "heart/timeouts",
 ];
 function isDispatchExempt(filePath) {
     return DISPATCH_EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.517",
+  "version": "0.1.0-alpha.518",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",