@ouro.bot/cli 0.1.0-alpha.479 → 0.1.0-alpha.480

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_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.480",
+      "changes": [
+        "`ouro mail import-mbox` and `ouro mail backfill-indexes` now launch as durable background operations by default, so large delegated-mail imports and hosted index repairs no longer block ordinary conversation.",
+        "Mail background jobs now persist queued/running/succeeded/failed state with progress, show up in `query_active_work`, and wake the agent immediately on completion or failure with actionable remediation context.",
+        "The background-operation runtime and CLI lifecycle are covered back to a restored 100% statements/branches/functions/lines gate, including detached background spawn defaults, malformed persisted records, and non-Error failure paths."
+      ]
+    },
     {
       "version": "0.1.0-alpha.479",
       "changes": [

package/dist/heart/active-work.js

@@ -513,6 +513,7 @@ function buildActiveWorkFrame(input) {
             allOtherLiveSessions,
         },
         codingSessions: liveCodingSessions,
+        backgroundOperations: input.backgroundOperations ?? [],
         otherCodingSessions,
         pendingObligations,
         targetCandidates: input.targetCandidates ?? [],
@@ -640,6 +641,30 @@ function formatActiveWorkFrame(frame, options) {
             /* v8 ignore stop */
         }
     }
+    const backgroundOperations = frame.backgroundOperations ?? [];
+    if (backgroundOperations.length > 0) {
+        lines.push("");
+        lines.push("## background operations");
+        for (const operation of backgroundOperations) {
+            let line = `- [${operation.status}] ${operation.title}`;
+            if (operation.summary.trim().length > 0) {
+                line += `: ${operation.summary}`;
+            }
+            if (operation.detail?.trim()) {
+                line += `\n  ${operation.detail.trim()}`;
+            }
+            if (operation.progress) {
+                const current = typeof operation.progress.current === "number" ? String(operation.progress.current) : "?";
+                const total = typeof operation.progress.total === "number" ? String(operation.progress.total) : null;
+                const unit = operation.progress.unit?.trim() ? ` ${operation.progress.unit.trim()}` : "";
+                line += `\n  progress: ${total ? `${current}/${total}` : current}${unit}`;
+            }
+            if (operation.error?.message?.trim()) {
+                line += `\n  error: ${operation.error.message.trim()}`;
+            }
+            lines.push(line);
+        }
+    }
     if (otherActiveSessions.length > 0) {
         lines.push("");
         lines.push("## other active sessions");

package/dist/heart/background-operations.js

@@ -0,0 +1,234 @@
+"use strict";
+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.readBackgroundOperation = readBackgroundOperation;
+exports.listBackgroundOperations = listBackgroundOperations;
+exports.startBackgroundOperation = startBackgroundOperation;
+exports.markBackgroundOperationRunning = markBackgroundOperationRunning;
+exports.updateBackgroundOperation = updateBackgroundOperation;
+exports.completeBackgroundOperation = completeBackgroundOperation;
+exports.failBackgroundOperation = failBackgroundOperation;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("./identity");
+function operationsDir(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return path.join(agentRoot, "state", "background-operations");
+}
+function operationPath(locator) {
+    return path.join(operationsDir(locator.agentName, locator.agentRoot), `${locator.id}.json`);
+}
+function normalizeProgress(progress) {
+    if (!progress)
+        return undefined;
+    const normalized = {};
+    if (typeof progress.current === "number" && Number.isFinite(progress.current))
+        normalized.current = progress.current;
+    if (typeof progress.total === "number" && Number.isFinite(progress.total))
+        normalized.total = progress.total;
+    if (typeof progress.unit === "string" && progress.unit.trim().length > 0)
+        normalized.unit = progress.unit.trim();
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function normalizeRecord(record) {
+    if (record.schemaVersion !== 1)
+        return null;
+    if (typeof record.id !== "string" || record.id.trim().length === 0)
+        return null;
+    if (typeof record.agentName !== "string" || record.agentName.trim().length === 0)
+        return null;
+    if (typeof record.kind !== "string" || record.kind.trim().length === 0)
+        return null;
+    if (typeof record.title !== "string" || record.title.trim().length === 0)
+        return null;
+    if (typeof record.summary !== "string" || record.summary.trim().length === 0)
+        return null;
+    if (typeof record.createdAt !== "string" || record.createdAt.trim().length === 0)
+        return null;
+    if (typeof record.updatedAt !== "string" || record.updatedAt.trim().length === 0)
+        return null;
+    if (record.status !== "queued"
+        && record.status !== "running"
+        && record.status !== "succeeded"
+        && record.status !== "failed") {
+        return null;
+    }
+    const normalized = {
+        schemaVersion: 1,
+        id: record.id,
+        agentName: record.agentName,
+        kind: record.kind,
+        title: record.title,
+        status: record.status,
+        summary: record.summary,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    };
+    if (typeof record.detail === "string" && record.detail.trim().length > 0)
+        normalized.detail = record.detail.trim();
+    if (typeof record.startedAt === "string" && record.startedAt.trim().length > 0)
+        normalized.startedAt = record.startedAt;
+    if (typeof record.finishedAt === "string" && record.finishedAt.trim().length > 0)
+        normalized.finishedAt = record.finishedAt;
+    const progress = normalizeProgress(record.progress);
+    if (progress)
+        normalized.progress = progress;
+    if (record.spec && typeof record.spec === "object" && !Array.isArray(record.spec))
+        normalized.spec = { ...record.spec };
+    if (record.result && typeof record.result === "object" && !Array.isArray(record.result))
+        normalized.result = { ...record.result };
+    if (record.error && typeof record.error.message === "string" && record.error.message.trim().length > 0) {
+        normalized.error = { message: record.error.message.trim() };
+    }
+    if (Array.isArray(record.remediation)) {
+        const remediation = record.remediation.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+        if (remediation.length > 0)
+            normalized.remediation = remediation;
+    }
+    return normalized;
+}
+function readRecord(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return normalizeRecord(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+function writeRecord(locator, record) {
+    fs.mkdirSync(operationsDir(locator.agentName, locator.agentRoot), { recursive: true });
+    fs.writeFileSync(operationPath(locator), `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.background_operation_written",
+        message: "background operation state written",
+        meta: { agentName: locator.agentName, id: locator.id, kind: record.kind, status: record.status },
+    });
+    return record;
+}
+function requireRecord(locator) {
+    const record = readBackgroundOperation(locator);
+    if (!record) {
+        throw new Error(`background operation not found: ${locator.id}`);
+    }
+    return record;
+}
+function readBackgroundOperation(locator) {
+    return readRecord(operationPath(locator));
+}
+function listBackgroundOperations(input) {
+    const dir = operationsDir(input.agentName, input.agentRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => readRecord(path.join(dir, entry)))
+        .filter((entry) => entry !== null)
+        .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))
+        .slice(0, input.limit ?? 10);
+}
+function startBackgroundOperation(input) {
+    return writeRecord(input, {
+        schemaVersion: 1,
+        id: input.id,
+        agentName: input.agentName,
+        kind: input.kind,
+        title: input.title,
+        status: "queued",
+        summary: input.summary,
+        createdAt: input.createdAt,
+        updatedAt: input.createdAt,
+        ...(input.spec ? { spec: input.spec } : {}),
+    });
+}
+function markBackgroundOperationRunning(input) {
+    const current = requireRecord(input);
+    const updatedAt = input.updatedAt ?? input.startedAt;
+    return writeRecord(input, {
+        ...current,
+        status: "running",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        startedAt: input.startedAt,
+        updatedAt,
+        ...(current.finishedAt ? { finishedAt: current.finishedAt } : {}),
+    });
+}
+function updateBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        updatedAt: input.updatedAt ?? current.updatedAt,
+    });
+}
+function completeBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        status: "succeeded",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        ...(input.result ? { result: input.result } : {}),
+        finishedAt: input.finishedAt,
+        updatedAt: input.updatedAt ?? input.finishedAt,
+    });
+}
+function failBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        status: "failed",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        error: { message: input.error },
+        ...(input.remediation && input.remediation.length > 0 ? { remediation: input.remediation } : {}),
+        finishedAt: input.finishedAt,
+        updatedAt: input.updatedAt ?? input.finishedAt,
+    });
+}

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

@@ -171,6 +171,14 @@ async function defaultFetchCliRegistryJson(timeoutMs) {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function defaultSpawnBackgroundCli(argv) {
+    const child = (0, child_process_1.spawn)(process.execPath, argv, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    return Promise.resolve({ pid: child.pid ?? null });
+}
 function defaultFallbackPendingMessage(command) {
     const inboxDir = path.join((0, identity_1.getAgentBundlesRoot)(), `${command.to}.ouro`, "inbox");
     const pendingPath = path.join(inboxDir, "pending.jsonl");
@@ -529,6 +537,7 @@ function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SO
         readHealthUpdatedAt: defaultReadHealthUpdatedAt,
         readRecentDaemonLogLines: defaultReadRecentDaemonLogLines,
         sleep: defaultSleep,
+        spawnBackgroundCli: defaultSpawnBackgroundCli,
         now: () => Date.now(),
         updateCheckTimeoutMs: update_checker_1.CLI_UPDATE_CHECK_TIMEOUT_MS,
         startupPollIntervalMs: 250,

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

@@ -82,6 +82,8 @@ const sync_1 = require("../sync");
 const core_1 = require("../../mailroom/core");
 const mbox_import_1 = require("../../mailroom/mbox-import");
 const reader_1 = require("../../mailroom/reader");
+const pending_1 = require("../../mind/pending");
+const background_operations_1 = require("../background-operations");
 const cli_parse_1 = require("./cli-parse");
 const cli_parse_2 = require("./cli-parse");
 const cli_help_1 = require("./cli-help");
@@ -3400,9 +3402,192 @@ function stringField(record, key) {
     const value = record[key];
     return typeof value === "string" ? value.trim() : "";
 }
+function cliNowIso(deps) {
+    return new Date(deps.now?.() ?? Date.now()).toISOString();
+}
+function makeBackgroundOperationId(kind) {
+    const prefix = kind === "mail.import-mbox" ? "op_mail_import" : "op_mail_backfill";
+    return `${prefix}_${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+}
+function notifyMailOperation(agentName, record, deps) {
+    const lines = [
+        "[Background Operation]",
+        `${record.title} ${record.status === "failed" ? "failed" : "finished"}.`,
+        `operation: ${record.id}`,
+        `status: ${record.status}`,
+        `summary: ${record.summary}`,
+        `detail: ${record.detail}`,
+        ...(record.error?.message ? [`error: ${record.error.message}`] : []),
+        ...(record.remediation && record.remediation.length > 0 ? ["", "next steps:", ...record.remediation.map((step) => `- ${step}`)] : []),
+        "",
+        "Use query_active_work for the live background-work view before drilling into mail details.",
+    ];
+    (0, pending_1.queuePendingMessage)((0, pending_1.getInnerDialogPendingDir)(agentName), {
+        from: "mailroom",
+        friendId: "self",
+        channel: "inner",
+        key: "dialog",
+        content: lines.join("\n"),
+        timestamp: deps.now?.() ?? Date.now(),
+        mode: "reflect",
+    });
+    return deps.sendCommand(deps.socketPath, { kind: "inner.wake", agent: agentName })
+        .then(() => undefined)
+        .catch(() => undefined);
+}
+function ensureTrackedMailOperation(input) {
+    if (!input.operationId)
+        return null;
+    const operationId = input.operationId;
+    const agentRoot = providerCliAgentRoot({ agent: input.agentName }, input.deps);
+    const existing = (0, background_operations_1.readBackgroundOperation)({
+        agentName: input.agentName,
+        agentRoot,
+        id: operationId,
+    });
+    const record = existing ?? (0, background_operations_1.startBackgroundOperation)({
+        agentName: input.agentName,
+        agentRoot,
+        id: operationId,
+        kind: input.kind,
+        title: input.title,
+        summary: input.queuedSummary,
+        createdAt: cliNowIso(input.deps),
+        ...(input.spec ? { spec: input.spec } : {}),
+    });
+    return {
+        record,
+        running: (summary, detail, progress) => {
+            (0, background_operations_1.markBackgroundOperationRunning)({
+                agentName: input.agentName,
+                agentRoot,
+                id: operationId,
+                startedAt: cliNowIso(input.deps),
+                summary,
+                ...(detail ? { detail } : {}),
+                ...(progress ? { progress } : {}),
+            });
+        },
+        update: (summary, detail, progress) => {
+            (0, background_operations_1.updateBackgroundOperation)({
+                agentName: input.agentName,
+                agentRoot,
+                id: operationId,
+                summary,
+                updatedAt: cliNowIso(input.deps),
+                ...(detail ? { detail } : {}),
+                ...(progress ? { progress } : {}),
+            });
+        },
+        succeed: async (summary, detail, result) => {
+            const completed = (0, background_operations_1.completeBackgroundOperation)({
+                agentName: input.agentName,
+                agentRoot,
+                id: operationId,
+                finishedAt: cliNowIso(input.deps),
+                summary,
+                detail,
+                result,
+            });
+            await notifyMailOperation(input.agentName, { ...completed, detail }, input.deps);
+        },
+        fail: async (error, summary, detail, remediation) => {
+            const failed = (0, background_operations_1.failBackgroundOperation)({
+                agentName: input.agentName,
+                agentRoot,
+                id: operationId,
+                finishedAt: cliNowIso(input.deps),
+                summary,
+                detail,
+                error: error instanceof Error ? error.message : String(error),
+                remediation,
+            });
+            await notifyMailOperation(input.agentName, { ...failed, detail }, input.deps);
+        },
+    };
+}
+async function launchBackgroundMailCommand(command, deps, args, title, queuedSummary, spec) {
+    const spawnBackgroundCli = deps.spawnBackgroundCli;
+    if (!spawnBackgroundCli) {
+        throw new Error("background CLI launch is not available in this runtime");
+    }
+    const operationId = makeBackgroundOperationId(command.kind);
+    const agentRoot = providerCliAgentRoot({ agent: command.agent }, deps);
+    (0, background_operations_1.startBackgroundOperation)({
+        agentName: command.agent,
+        agentRoot,
+        id: operationId,
+        kind: command.kind,
+        title,
+        summary: queuedSummary,
+        createdAt: cliNowIso(deps),
+        ...(spec ? { spec } : {}),
+    });
+    try {
+        await spawnBackgroundCli([process.argv[1], ...args, "--foreground", "--operation-id", operationId]);
+    }
+    catch (error) {
+        (0, background_operations_1.failBackgroundOperation)({
+            agentName: command.agent,
+            agentRoot,
+            id: operationId,
+            finishedAt: cliNowIso(deps),
+            summary: `${title} could not be started`,
+            error: error instanceof Error ? error.message : String(error),
+            remediation: ["retry the command once the local runtime is healthy"],
+        });
+        throw error;
+    }
+    const message = [
+        `Started background ${title} for ${command.agent}`,
+        `operation: ${operationId}`,
+        ...(spec ? Object.entries(spec).map(([key, value]) => `${key}: ${String(value)}`) : []),
+        `${command.agent} will be woken on failure or completion.`,
+        "Use query_active_work to check live progress.",
+    ].join("\n");
+    deps.writeStdout(message);
+    return message;
+}
 async function executeMailImportMbox(command, deps) {
+    const filePath = path.resolve(command.filePath);
+    if (!command.foreground) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`no such file: ${filePath}`);
+        }
+        return launchBackgroundMailCommand(command, deps, [
+            "mail",
+            "import-mbox",
+            "--agent",
+            command.agent,
+            "--file",
+            filePath,
+            ...(command.ownerEmail ? ["--owner-email", command.ownerEmail] : []),
+            ...(command.source ? ["--source", command.source] : []),
+        ], "mail import", "queued delegated mail import", {
+            filePath,
+            ...(command.ownerEmail ? { ownerEmail: command.ownerEmail } : {}),
+            ...(command.source ? { source: command.source } : {}),
+        });
+    }
     const progress = createHumanCommandProgress(deps, "mail import");
+    const trackedOperation = ensureTrackedMailOperation({
+        agentName: command.agent,
+        deps,
+        operationId: command.operationId,
+        kind: "mail.import-mbox",
+        title: "mail import",
+        queuedSummary: "queued delegated mail import",
+        spec: {
+            filePath,
+            ...(command.ownerEmail ? { ownerEmail: command.ownerEmail } : {}),
+            ...(command.source ? { source: command.source } : {}),
+        },
+    });
     try {
+        trackedOperation?.running("reading Mailroom config", `file: ${filePath}`, {
+            current: 0,
+            unit: "messages",
+        });
         progress.startPhase("reading Mailroom config");
         const runtime = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(command.agent, { preserveCachedOnFailure: true });
         if (!runtime.ok) {
@@ -3437,9 +3622,10 @@ async function executeMailImportMbox(command, deps) {
             throw new Error(resolved.error);
         }
         progress.updateDetail("reading registry and MBOX");
+        trackedOperation?.update("reading registry and MBOX", `file: ${filePath}`);
         const registry = await (0, reader_1.readMailroomRegistry)(resolved.config);
-        const filePath = path.resolve(command.filePath);
         progress.updateDetail("importing delegated mail");
+        trackedOperation?.update("importing delegated mail", `file: ${filePath}`);
         const result = await (0, mbox_import_1.importMboxFileToStore)({
             registry,
             store: resolved.store,
@@ -3447,6 +3633,12 @@ async function executeMailImportMbox(command, deps) {
             filePath,
             ownerEmail: command.ownerEmail,
             source: command.source,
+            onProgress: (importProgress) => {
+                trackedOperation?.update("importing delegated mail", `scanned ${importProgress.scanned} messages`, {
+                    current: importProgress.scanned,
+                    unit: "messages",
+                });
+            },
         });
         progress.completePhase("reading Mailroom config", "imported");
         progress.end();
@@ -3461,17 +3653,44 @@ async function executeMailImportMbox(command, deps) {
             "archive imports are historical; they do not create Screener wakeups.",
             "body reads remain explicit through mail_recent/mail_search/mail_thread and are access-logged.",
         ].join("\n");
+        await trackedOperation?.succeed("imported delegated mail archive", `scanned ${result.scanned}; imported ${result.imported}; duplicates ${result.duplicates}`, {
+            scanned: result.scanned,
+            imported: result.imported,
+            duplicates: result.duplicates,
+            sourceFreshThrough: result.sourceFreshThrough,
+        });
         deps.writeStdout(message);
         return message;
     }
     catch (error) {
         progress.end();
+        await trackedOperation?.fail(error, "delegated mail import failed", `file: ${filePath}`, [
+            "fix the reported Mailroom or MBOX problem, then rerun the import",
+            "use query_active_work to confirm whether the operation has cleared",
+        ]);
         throw error;
     }
 }
 async function executeMailBackfillIndexes(command, deps) {
+    if (!command.foreground) {
+        return launchBackgroundMailCommand(command, deps, [
+            "mail",
+            "backfill-indexes",
+            "--agent",
+            command.agent,
+        ], "mail index repair", "queued hosted mail index repair");
+    }
     const progress = createHumanCommandProgress(deps, "mail index repair");
+    const trackedOperation = ensureTrackedMailOperation({
+        agentName: command.agent,
+        deps,
+        operationId: command.operationId,
+        kind: "mail.backfill-indexes",
+        title: "mail index repair",
+        queuedSummary: "queued hosted mail index repair",
+    });
     try {
+        trackedOperation?.running("resolving Mailroom store");
         progress.startPhase("resolving Mailroom store");
         const runtime = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(command.agent, { preserveCachedOnFailure: true });
         if (!runtime.ok) {
@@ -3491,6 +3710,7 @@ async function executeMailBackfillIndexes(command, deps) {
                 `store: ${resolved.storeLabel}`,
                 "This agent is using the local file Mailroom store, so recent mail reads do not depend on hosted blob indexes.",
             ].join("\n");
+            await trackedOperation?.succeed("hosted mail index repair not needed", `store: ${resolved.storeLabel}`, { indexed: 0, store: resolved.storeLabel, reason: "local-file-store" });
             deps.writeStdout(message);
             return message;
         }
@@ -3500,7 +3720,14 @@ async function executeMailBackfillIndexes(command, deps) {
             throw new Error(`hosted Mailroom store for ${command.agent} does not expose index backfill`);
         }
         progress.updateDetail("backfilling hosted message indexes");
-        const indexed = await store.backfillMessageIndexes(command.agent);
+        trackedOperation?.update("backfilling hosted message indexes");
+        const indexed = await store.backfillMessageIndexes(command.agent, (backfillProgress) => {
+            trackedOperation?.update("backfilling hosted message indexes", `indexed ${backfillProgress.indexed} of ${backfillProgress.total}`, {
+                current: backfillProgress.scanned,
+                total: backfillProgress.total,
+                unit: "blobs",
+            });
+        });
         progress.completePhase("resolving Mailroom store", "backfilled");
         progress.end();
         const message = [
@@ -3509,11 +3736,16 @@ async function executeMailBackfillIndexes(command, deps) {
             `indexed: ${indexed}`,
             "Safe to rerun. Existing index entries are rewritten in place.",
         ].join("\n");
+        await trackedOperation?.succeed("hosted mail index repair finished", `indexed ${indexed} message indexes`, { indexed, store: resolved.storeLabel });
         deps.writeStdout(message);
         return message;
     }
     catch (error) {
         progress.end();
+        await trackedOperation?.fail(error, "hosted mail index repair failed", "store resolution or blob backfill failed", [
+            "rerun the hosted index repair to retry remaining blobs",
+            "if the same residue repeats, inspect the failed blob ids and timeouts",
+        ]);
         throw error;
     }
 }

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

@@ -323,12 +323,12 @@ const SUBCOMMAND_HELP = {
     },
     "mail import-mbox": {
         description: "Import a HEY or other MBOX export into an existing delegated Mailroom source grant",
-        usage: "ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>]",
+        usage: "ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",
         example: "ouro mail import-mbox --file ~/Downloads/hey.mbox --owner-email ari@mendelow.me --source hey --agent slugger",
     },
     "mail backfill-indexes": {
         description: "Rebuild hosted blob mailbox indexes for faster recent-mail reads after large legacy imports or drift repair.",
-        usage: "ouro mail backfill-indexes [--agent <name>]",
+        usage: "ouro mail backfill-indexes [--agent <name>] [--foreground]",
         example: "ouro mail backfill-indexes --agent slugger",
     },
     "provider refresh": {

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

@@ -86,8 +86,8 @@ function usage() {
         "  ouro auth [--agent <name>] [--provider <provider>]",
         "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
-        "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>]",
-        "  ouro mail backfill-indexes [--agent <name>]",
+        "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",
+        "  ouro mail backfill-indexes [--agent <name>] [--foreground]",
         "  ouro auth verify [--agent <name>] [--provider <provider>]",
         "  ouro auth switch [--agent <name>] --provider <provider>",
         "  ouro vault create [--agent <name>] --email <email> [--server <url>] [--store <store>]",
@@ -885,14 +885,28 @@ function parseConnectCommand(args) {
 }
 function parseMailCommand(args) {
     const [sub, ...subArgs] = args;
-    const usageText = "Usage: ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>]\n       ouro mail backfill-indexes [--agent <name>]";
+    const usageText = "Usage: ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]\n       ouro mail backfill-indexes [--agent <name>] [--foreground]";
     if (sub === "backfill-indexes") {
         const { agent, rest } = extractAgentFlag(subArgs);
-        if (rest.length > 0)
+        let foreground = false;
+        let operationId;
+        for (let i = 0; i < rest.length; i += 1) {
+            const token = rest[i];
+            if (token === "--foreground") {
+                foreground = true;
+                continue;
+            }
+            if (token === "--operation-id" && rest[i + 1]) {
+                operationId = rest[++i];
+                continue;
+            }
             throw new Error(usageText);
+        }
         return {
             kind: "mail.backfill-indexes",
             ...(agent ? { agent } : {}),
+            ...(foreground ? { foreground: true } : {}),
+            ...(operationId ? { operationId } : {}),
         };
     }
     if (sub !== "import-mbox") {
@@ -902,6 +916,8 @@ function parseMailCommand(args) {
     let filePath;
     let ownerEmail;
     let source;
+    let foreground = false;
+    let operationId;
     for (let i = 0; i < rest.length; i += 1) {
         const token = rest[i];
         if (token === "--file" && rest[i + 1]) {
@@ -916,6 +932,14 @@ function parseMailCommand(args) {
             source = rest[++i];
             continue;
         }
+        if (token === "--foreground") {
+            foreground = true;
+            continue;
+        }
+        if (token === "--operation-id" && rest[i + 1]) {
+            operationId = rest[++i];
+            continue;
+        }
         throw new Error(usageText);
     }
     if (!filePath) {
@@ -927,6 +951,8 @@ function parseMailCommand(args) {
         filePath,
         ...(ownerEmail ? { ownerEmail } : {}),
         ...(source ? { source } : {}),
+        ...(foreground ? { foreground: true } : {}),
+        ...(operationId ? { operationId } : {}),
     };
 }
 function parseAccountCommand(args) {

package/dist/mailroom/blob-store.js

@@ -273,7 +273,7 @@ class AzureBlobMailroomStore {
             .sort(compareNewestFirst)
             .slice(0, filters.limit ?? 20);
     }
-    async backfillMessageIndexes(agentId) {
+    async backfillMessageIndexes(agentId, onProgress) {
         await this.ensureContainer();
         const messageBlobNames = [];
         for await (const item of this.container.listBlobsFlat({ prefix: "messages/" })) {
@@ -281,6 +281,7 @@ class AzureBlobMailroomStore {
         }
         let indexed = 0;
         const failures = [];
+        let scanned = 0;
         let nextIndex = 0;
         const worker = async () => {
             while (nextIndex < messageBlobNames.length) {
@@ -298,6 +299,10 @@ class AzureBlobMailroomStore {
                 catch (error) {
                     failures.push(error instanceof Error ? error.message : String(error));
                 }
+                finally {
+                    scanned += 1;
+                    onProgress?.({ scanned, indexed, failures: failures.length, total: messageBlobNames.length });
+                }
             }
         };
         await Promise.all(Array.from({ length: Math.min(this.backfillConcurrency, Math.max(messageBlobNames.length, 1)) }, async () => worker()));

package/dist/mailroom/mbox-import.js

@@ -246,6 +246,7 @@ async function importParsedMessagesToStore(input) {
                 imported += 1;
             else
                 duplicates += 1;
+            input.onProgress?.({ scanned, imported, duplicates });
         })().finally(() => {
             inFlight.delete(task);
         });
@@ -254,6 +255,7 @@ async function importParsedMessagesToStore(input) {
     };
     for await (const parsedMessage of input.parsedMessages) {
         scanned += 1;
+        input.onProgress?.({ scanned, imported, duplicates });
         enqueue(parsedMessage);
         if (inFlight.size >= maxConcurrency) {
             await Promise.race(inFlight);
@@ -334,5 +336,6 @@ async function importMboxFileToStore(input) {
         collectMessages: false,
         sourceFreshThrough,
         maxConcurrency: 8,
+        onProgress: input.onProgress,
     });
 }

package/dist/repertoire/tools-session.js

@@ -46,6 +46,7 @@ const manager_1 = require("../heart/bridges/manager");
 const session_transcript_1 = require("../heart/session-transcript");
 const session_activity_1 = require("../heart/session-activity");
 const active_work_1 = require("../heart/active-work");
+const background_operations_1 = require("../heart/background-operations");
 const coding_1 = require("./coding");
 const tasks_1 = require("./tasks");
 const pending_1 = require("../mind/pending");
@@ -263,6 +264,11 @@ async function buildToolActiveWorkFrame(ctx) {
             && obligation.origin.channel === currentSession.channel
             && obligation.origin.key === currentSession.key)?.content ?? null
         : null;
+    const backgroundOperations = (0, background_operations_1.listBackgroundOperations)({
+        agentName: (0, identity_1.getAgentName)(),
+        agentRoot,
+        limit: 5,
+    });
     return (0, active_work_1.buildActiveWorkFrame)({
         currentSession,
         currentObligation,
@@ -270,6 +276,7 @@ async function buildToolActiveWorkFrame(ctx) {
         inner: readActiveWorkInnerState(),
         bridges,
         codingSessions,
+        backgroundOperations,
         otherCodingSessions,
         pendingObligations,
         taskBoard: (() => {

package/package.json

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