@fnndsc/salsa 3.5.0 → 3.6.0

package/dist/vfs/providers/proc.js

@@ -21,50 +21,83 @@ exports.procFeed_ensureLoaded = procFeed_ensureLoaded;
 exports.feedMeta_ensure = feedMeta_ensure;
 exports.feedStatus_refresh = feedStatus_refresh;
 exports.procTopology_warmup = procTopology_warmup;
+exports.procTopology_reconcileFeeds = procTopology_reconcileFeeds;
+exports.procTopology_retry = procTopology_retry;
+exports.procTopology_status = procTopology_status;
+exports.procTopology_await = procTopology_await;
 exports.procCache_refresh = procCache_refresh;
 const cumin_1 = require("@fnndsc/cumin");
 const index_js_1 = require("../../jobs/index.js");
 /** Virtual filenames inside each instance directory. */
-const INSTANCE_FILES = new Set(['status', 'params', 'log']);
+const INSTANCE_FILES = new Set(['status', 'params', 'log', 'data']);
 /** Virtual filenames inside each feed directory. */
 const FEED_FILES = new Set(['status', 'title']);
+const PROC_JOBS_PREFIX = '/proc/jobs';
 const PAGE = 100;
+let procTopologyPromise = null;
+let procTopologyFailure;
+let procTopologyResumeState = null;
+let procTopologyScopedResumeFeedIDs = null;
+/** Converts a CUBE feed row into the cache's feed model. */
+function procFeed_create(feed) {
+    return {
+        id: Number(feed.id),
+        title: String(feed.name),
+        ownerUsername: String(feed.owner_username ?? ''),
+        public: Boolean(feed.public ?? false),
+        creationDate: String(feed.creation_date ?? ''),
+        finishedJobs: Number(feed.finished_jobs ?? 0),
+        erroredJobs: Number(feed.errored_jobs ?? 0),
+        startedJobs: Number(feed.started_jobs ?? 0),
+        scheduledJobs: Number(feed.scheduled_jobs ?? 0),
+        cancelledJobs: Number(feed.cancelled_jobs ?? 0),
+        createdJobs: Number(feed.created_jobs ?? 0),
+    };
+}
+/** Indexes one complete paginated CUBE feed collection into the shared cache. */
+async function procFeeds_index(page_fetch, indexed) {
+    let offset = 0;
+    let total = 0;
+    const seenFeedIDs = new Set();
+    while (true) {
+        const page = await page_fetch({ limit: PAGE, offset });
+        const chunk = page.data ?? [];
+        if (offset === 0 && typeof page.totalCount === 'number' && page.totalCount >= 0) {
+            total = page.totalCount;
+        }
+        for (const feed of chunk) {
+            const procFeed = procFeed_create(feed);
+            indexed.set(procFeed.id, procFeed);
+            seenFeedIDs.add(Number(feed.id));
+        }
+        if (chunk.length === 0 || (total > 0 && seenFeedIDs.size >= total))
+            break;
+        if (total === 0 && chunk.length < PAGE)
+            break;
+        offset += chunk.length;
+    }
+}
 // ── Cache build ────────────────────────────────────────────────────────────
 /**
- * Builds the feed index (fast). Fetches all feeds with job counters.
+ * Builds the feed index (fast). Fetches owned/shared and public feeds with job counters.
  * Instance topology is loaded separately via procTopology_warmup().
  */
 async function procCache_build() {
     const cache = (0, cumin_1.procCache_get)();
-    cache.cache_clear();
     const client = await cumin_1.chrisConnection.client_get();
     if (!client) {
         cumin_1.errorStack.stack_push('error', 'procCache_build: not connected');
-        return;
+        throw new Error('not connected');
     }
     const typedClient = client;
-    let feedOffset = 0;
-    while (true) {
-        const feedPage = await typedClient.getFeeds({ limit: PAGE, offset: feedOffset });
-        const chunk = feedPage.data ?? [];
-        for (const f of chunk) {
-            cache.feed_add({
-                id: Number(f.id),
-                title: String(f.name),
-                creationDate: String(f.creation_date ?? ''),
-                finishedJobs: Number(f.finished_jobs ?? 0),
-                erroredJobs: Number(f.errored_jobs ?? 0),
-                startedJobs: Number(f.started_jobs ?? 0),
-                scheduledJobs: Number(f.scheduled_jobs ?? 0),
-                cancelledJobs: Number(f.cancelled_jobs ?? 0),
-                createdJobs: Number(f.created_jobs ?? 0),
-            });
-        }
-        if (chunk.length < PAGE)
-            break;
-        feedOffset += PAGE;
+    const indexed = new Map();
+    await procFeeds_index(typedClient.getFeeds.bind(typedClient), indexed);
+    if (typedClient.getPublicFeeds) {
+        await procFeeds_index(typedClient.getPublicFeeds.bind(typedClient), indexed);
     }
+    const reconciliationTargets = cache.feeds_reconcile(Array.from(indexed.values()));
     cache.built_set();
+    return reconciliationTargets;
 }
 /** Ensures the feed index is built, building it on first access. */
 async function cache_ensure() {
@@ -80,21 +113,28 @@ async function feedInstances_load(feedID) {
     const cache = (0, cumin_1.procCache_get)();
     const client = await cumin_1.chrisConnection.client_get();
     if (!client)
-        return;
+        throw new Error('not connected');
     const typedClient = client;
-    const instances = [];
+    const instances = new Map();
     let offset = 0;
+    let total = 0;
     while (true) {
         const page = await typedClient.getPluginInstances({
             feed_id: feedID, limit: PAGE, offset,
         });
         const chunk = page.data ?? [];
-        instances.push(...chunk);
-        if (chunk.length < PAGE)
+        if (offset === 0 && typeof page.totalCount === 'number' && page.totalCount >= 0) {
+            total = page.totalCount;
+        }
+        for (const instance of chunk)
+            instances.set(Number(instance.id), instance);
+        if (chunk.length === 0 || (total > 0 && instances.size >= total))
             break;
-        offset += PAGE;
+        if (total === 0 && chunk.length < PAGE)
+            break;
+        offset += chunk.length;
     }
-    for (const inst of instances) {
+    for (const inst of instances.values()) {
         const prevID = (inst.previous_id !== null && inst.previous_id !== undefined)
             ? Number(inst.previous_id)
             : null;
@@ -105,6 +145,7 @@ async function feedInstances_load(feedID) {
             pluginName: String(inst.plugin_name),
             pluginType: inst.plugin_type !== undefined ? String(inst.plugin_type) : undefined,
             params: null,
+            outputPath: outputPath_normalize(inst.output_path) ?? undefined,
             status: String(inst.status ?? 'unknown'),
         });
     }
@@ -124,8 +165,12 @@ async function feedInstances_ensureLoaded(feedID) {
         return inflight;
     const promise = feedInstances_load(feedID);
     cache.loading_set(feedID, promise);
-    await promise;
-    cache.loading_clear(feedID);
+    try {
+        await promise;
+    }
+    finally {
+        cache.loading_clear(feedID);
+    }
 }
 // ── Aggregate status ───────────────────────────────────────────────────────
 /** Derives aggregate feed status from stored job counters — no API call. */
@@ -143,7 +188,14 @@ function feedStatus_derive(feed) {
 }
 // ── Path parsing ───────────────────────────────────────────────────────────
 function procPath_parse(pathStr) {
-    const parts = pathStr.replace(/^\/proc\/feeds\/?/, '').split('/').filter(Boolean);
+    let relativePath = pathStr;
+    if (pathStr === PROC_JOBS_PREFIX) {
+        relativePath = '';
+    }
+    else if (pathStr.startsWith(`${PROC_JOBS_PREFIX}/`)) {
+        relativePath = pathStr.slice(PROC_JOBS_PREFIX.length + 1);
+    }
+    const parts = relativePath.split('/').filter(Boolean);
     let feedID = null;
     let instanceID = null;
     let virtualFile = null;
@@ -178,6 +230,79 @@ function params_render(inst) {
         .map(([k, v]) => `${k}=${String(v)}`)
         .join('\n');
 }
+/**
+ * Normalizes CUBE's output-path spelling into an absolute CFS path.
+ *
+ * @param value - Raw `output_path` value from a plugin-instance resource.
+ * @returns Absolute CFS path, or null when no usable path was supplied.
+ */
+function outputPath_normalize(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return null;
+    const clean = value.trim();
+    return clean.startsWith('/') ? clean : `/${clean}`;
+}
+/**
+ * Resolves and memoizes the authoritative CFS output directory for one job.
+ *
+ * @param instanceID - Plugin-instance ID whose output path is needed.
+ * @returns Absolute output path, or null when CUBE has not recorded one.
+ */
+async function instanceOutputPath_ensure(instanceID) {
+    const cache = (0, cumin_1.procCache_get)();
+    const inst = cache.instance_get(instanceID);
+    if (!inst)
+        return null;
+    if (inst.outputPath !== undefined)
+        return inst.outputPath;
+    const client = await cumin_1.chrisConnection.client_get();
+    if (!client)
+        return null;
+    try {
+        const resource = await client
+            .getPluginInstance(instanceID);
+        const outputPath = outputPath_normalize(resource?.data?.['output_path']);
+        cache.outputPath_update(instanceID, outputPath);
+        return outputPath;
+    }
+    catch (error) {
+        // "No CFS output path" downstream must not mask a failed fetch.
+        const msg = error instanceof Error ? error.message : String(error);
+        cumin_1.errorStack.stack_push("warning", `Could not fetch output path for instance ${instanceID}: ${msg}`);
+        return null;
+    }
+}
+/**
+ * Reads every page of effective parameter values from one plugin instance.
+ *
+ * @param resource - Detail resource for the instance being inspected.
+ * @returns Parameter names mapped to their recorded invocation values.
+ */
+async function instanceParams_fetch(resource) {
+    const params = {};
+    let offset = 0;
+    let total = 0;
+    let fetched = 0;
+    while (true) {
+        const page = await resource.getParameters({ limit: PAGE, offset });
+        const items = page.data
+            ?? (page.getItems ? page.getItems().map((item) => item.data) : []);
+        if (offset === 0 && typeof page.totalCount === 'number' && page.totalCount >= 0) {
+            total = page.totalCount;
+        }
+        for (const item of items) {
+            if (item.param_name)
+                params[item.param_name] = item.value;
+        }
+        fetched += items.length;
+        if (items.length === 0 || (total > 0 && fetched >= total))
+            break;
+        if (total === 0 && items.length < PAGE)
+            break;
+        offset += items.length;
+    }
+    return params;
+}
 /** Collects all instance IDs for a feed recursively. */
 function getAllInstanceIDs_forFeed(feedID, cache) {
     const result = [];
@@ -194,13 +319,35 @@ function getAllInstanceIDs_forFeed(feedID, cache) {
  * VFS provider exposing running jobs and feeds under the /proc namespace.
  */
 class ProcVfsProvider {
-    prefix = '/proc/jobs';
+    prefix = PROC_JOBS_PREFIX;
+    /**
+     * Resolves the synthetic `data` link for one job only when navigation asks
+     * to follow it. This keeps `/proc` topology listings and recursive trees
+     * entirely cache-backed.
+     *
+     * @param pathStr - Absolute `/proc/jobs/.../data` path to resolve.
+     * @returns The authoritative CFS output path, or an error when absent.
+     */
+    async linkTarget_resolve(pathStr) {
+        await cache_ensure();
+        const clean = pathStr.replace(/\/$/, '');
+        const { feedID, instanceID, virtualFile } = procPath_parse(clean);
+        if (feedID === null || instanceID === null || virtualFile !== 'data') {
+            cumin_1.errorStack.stack_push('error', `Not a /proc job data link: ${pathStr}`);
+            return (0, cumin_1.Err)();
+        }
+        const outputPath = await instanceOutputPath_ensure(instanceID);
+        if (outputPath)
+            return (0, cumin_1.Ok)(outputPath);
+        cumin_1.errorStack.stack_push('error', `No CFS output path is available for job ${instanceID}`);
+        return (0, cumin_1.Err)();
+    }
     async list(pathStr, _options) {
         await cache_ensure();
         const cache = (0, cumin_1.procCache_get)();
         const clean = pathStr.replace(/\/$/, '');
         // /proc/jobs — list all feeds with aggregate status from counters
-        if (clean === '/proc/jobs') {
+        if (clean === PROC_JOBS_PREFIX) {
             const items = cache.feedIDs_get().map((feedID) => {
                 const feed = cache.feed_get(feedID);
                 const status = feed ? feedStatus_derive(feed) : 'unknown';
@@ -264,6 +411,15 @@ class ProcVfsProvider {
             items.push({ name: 'status', type: 'file', size: 0, owner: '', date: '' });
             items.push({ name: 'params', type: 'file', size: 0, owner: '', date: '' });
             items.push({ name: 'log', type: 'file', size: 0, owner: '', date: '' });
+            // `data` is structural: list it without fetching the per-instance detail
+            // endpoint. Its target is resolved only when `cd data` follows the link.
+            // A known null means CUBE has no output directory, so omit it entirely.
+            if (inst.outputPath !== null) {
+                const dataLink = { name: 'data', type: 'link', size: 0, owner: '', date: '' };
+                if (inst.outputPath)
+                    dataLink.target = inst.outputPath;
+                items.push(dataLink);
+            }
             for (const childID of childIDs) {
                 const child = cache.instance_get(childID);
                 if (!child)
@@ -314,22 +470,21 @@ class ProcVfsProvider {
             }
             if (virtualFile === 'params') {
                 if (inst.params === null) {
-                    // Fetch params on first read and cache permanently
+                    // CUBE stores the effective run values in the parameter sub-resource;
+                    // the instance detail payload itself is operational metadata.
                     const client = await cumin_1.chrisConnection.client_get();
                     if (client) {
                         try {
-                            const raw = await client.getPluginInstance(instanceID);
-                            if (raw?.data) {
-                                const p = { ...raw.data };
-                                delete p['id'];
-                                delete p['feed_id'];
-                                delete p['plugin_name'];
-                                delete p['status'];
-                                delete p['previous_id'];
-                                cache.params_update(instanceID, p);
-                            }
+                            const resource = await client
+                                .getPluginInstance(instanceID);
+                            if (resource)
+                                cache.params_update(instanceID, await instanceParams_fetch(resource));
+                        }
+                        catch {
+                            // Deliberate absorption, adjudicated 2026-08: parameters are a
+                            // lazy display enrichment; a failed fetch renders as
+                            // "(no parameters)" and the next read retries.
                         }
-                        catch { /* leave null */ }
                     }
                 }
                 return (0, cumin_1.Ok)(params_render(inst));
@@ -349,12 +504,21 @@ class ProcVfsProvider {
         if (feedID !== null && instanceID === null) {
             const allIDs = getAllInstanceIDs_forFeed(feedID, cache);
             const statusMap = await (0, index_js_1.jobs_statusBatch)(allIDs);
+            // Every cancel Result is checked: reporting success while jobs kept
+            // running would leave the user believing the feed's work was stopped.
+            const failedCancels = [];
             await Promise.all(allIDs.map(async (id) => {
                 const s = statusMap.get(id) ?? '';
                 if (!(0, cumin_1.status_isTerminal)(s)) {
-                    await (0, index_js_1.job_cancel)(id);
+                    const cancelResult = await (0, index_js_1.job_cancel)(id);
+                    if (!cancelResult.ok)
+                        failedCancels.push(id);
                 }
             }));
+            if (failedCancels.length > 0) {
+                cumin_1.errorStack.stack_push('error', `rm: failed to cancel ${failedCancels.length} running job(s) in feed ${feedID}: instance(s) ${failedCancels.sort((a, b) => a - b).join(', ')}`);
+                return false;
+            }
             cache.feed_remove(feedID);
             return true;
         }
@@ -392,7 +556,7 @@ async function procFeed_ensureLoaded(feedID) {
     const cache = (0, cumin_1.procCache_get)();
     if (!cache.feed_get(feedID)) {
         cache.feed_add({
-            id: feedID, title: `feed_${feedID}`, creationDate: '',
+            id: feedID, title: `feed_${feedID}`, ownerUsername: '', public: false, creationDate: '',
             finishedJobs: 0, erroredJobs: 0, startedJobs: 0,
             scheduledJobs: 0, cancelledJobs: 0, createdJobs: 0,
         });
@@ -424,23 +588,13 @@ async function feedMeta_ensure(feedID) {
         return;
     const client = await cumin_1.chrisConnection.client_get();
     if (!client)
-        return;
+        throw new Error('not connected');
     const typedClient = client;
     const page = await typedClient.getFeeds({ id: feedID, limit: 1, offset: 0 });
     const f = (page.data ?? [])[0];
     if (!f)
         return;
-    cache.feed_add({
-        id: Number(f.id),
-        title: String(f.name),
-        creationDate: String(f.creation_date ?? ''),
-        finishedJobs: Number(f.finished_jobs ?? 0),
-        erroredJobs: Number(f.errored_jobs ?? 0),
-        startedJobs: Number(f.started_jobs ?? 0),
-        scheduledJobs: Number(f.scheduled_jobs ?? 0),
-        cancelledJobs: Number(f.cancelled_jobs ?? 0),
-        createdJobs: Number(f.created_jobs ?? 0),
-    });
+    cache.feed_add(procFeed_create(f));
 }
 async function feedStatus_refresh(feedID) {
     const cache = (0, cumin_1.procCache_get)();
@@ -449,79 +603,265 @@ async function feedStatus_refresh(feedID) {
         return;
     const typedClient = client;
     let offset = 0;
+    let total = 0;
+    const seenInstanceIDs = new Set();
     while (true) {
         const page = await typedClient.getPluginInstances({
             feed_id: feedID, limit: PAGE, offset,
         });
         const chunk = page.data ?? [];
+        if (offset === 0 && typeof page.totalCount === 'number' && page.totalCount >= 0) {
+            total = page.totalCount;
+        }
         for (const inst of chunk) {
-            cache.status_update(Number(inst.id), String(inst.status ?? 'unknown'));
+            const instanceID = Number(inst.id);
+            cache.status_update(instanceID, String(inst.status ?? 'unknown'));
+            seenInstanceIDs.add(instanceID);
         }
-        if (chunk.length < PAGE)
+        if (chunk.length === 0 || (total > 0 && seenInstanceIDs.size >= total))
             break;
-        offset += PAGE;
+        if (total === 0 && chunk.length < PAGE)
+            break;
+        offset += chunk.length;
     }
 }
 /**
  * Background topology warm-up — single paginated sweep of all plugin instances
  * across all feeds. Replaces the per-feed fan-out that was O(feeds) round trips.
  *
- * Registers itself as the active sweep so that any concurrent
- * feedInstances_ensureLoaded call waits for this sweep rather than launching
- * its own per-feed API call.
+ * Scoped per-feed loads may run concurrently for navigation; the completed
+ * global sweep reconciles the cache to its authoritative instance set.
+ *
+ * @param state - Private pagination and reconciliation state for this sweep.
+ * @returns A promise that settles when the complete topology has been reconciled.
  */
-async function procTopology_warmup() {
+async function procTopology_run(state) {
     await cache_ensure();
     const cache = (0, cumin_1.procCache_get)();
+    cache.lifecycle_set('reconciling');
+    if (state.total > 0) {
+        cache.warmup_progress(state.fetchedInstanceIDs.size, state.total);
+    }
     const client = await cumin_1.chrisConnection.client_get();
     if (!client)
-        return;
-    cache.warmup_progress(0, 0);
+        throw new Error('not connected');
     const typedClient = client;
-    let offset = 0;
-    let loaded = 0;
-    const seenFeedIDs = new Set();
     while (true) {
         const page = await typedClient.getPluginInstances({
-            limit: PAGE, offset,
+            limit: PAGE, offset: state.offset,
         });
         const chunk = page.data ?? [];
+        if (state.offset === 0 && typeof page.totalCount === 'number' && page.totalCount >= 0) {
+            state.total = page.totalCount;
+            if (state.total > 0)
+                cache.warmup_progress(0, state.total);
+        }
         for (const inst of chunk) {
+            const instanceID = Number(inst.id);
             const feedID = Number(inst.feed_id);
+            state.fetchedInstanceIDs.add(instanceID);
             const prevID = (inst.previous_id !== null && inst.previous_id !== undefined)
                 ? Number(inst.previous_id)
                 : null;
-            if (!cache.feed_get(feedID)) {
-                cache.feed_add({
-                    id: feedID, title: `feed_${feedID}`, creationDate: '',
-                    finishedJobs: 0, erroredJobs: 0, startedJobs: 0,
-                    scheduledJobs: 0, cancelledJobs: 0, createdJobs: 0,
-                });
-            }
+            if (!cache.feed_get(feedID))
+                continue;
             cache.instance_add({
-                id: Number(inst.id),
+                id: instanceID,
                 feedID,
                 parentID: prevID,
                 pluginName: String(inst.plugin_name),
                 pluginType: inst.plugin_type !== undefined ? String(inst.plugin_type) : undefined,
                 params: null,
+                outputPath: outputPath_normalize(inst.output_path) ?? undefined,
                 status: String(inst.status ?? 'unknown'),
             });
-            seenFeedIDs.add(feedID);
-            loaded++;
+            state.seenInstanceIDs.add(instanceID);
+            state.seenFeedIDs.add(feedID);
         }
-        cache.warmup_progress(loaded, 0);
-        if (chunk.length < PAGE)
+        if (state.total > 0)
+            cache.warmup_progress(state.fetchedInstanceIDs.size, state.total);
+        if (chunk.length === 0 || (state.total > 0 && state.fetchedInstanceIDs.size >= state.total))
             break;
-        offset += PAGE;
+        if (state.total === 0 && chunk.length < PAGE)
+            break;
+        state.offset += chunk.length;
     }
-    for (const feedID of seenFeedIDs) {
+    cache.topology_reconcile(state.seenInstanceIDs);
+    for (const feedID of state.seenFeedIDs)
         cache.topologyLoaded_mark(feedID);
+    if (state.total === 0) {
+        cache.warmup_progress(state.fetchedInstanceIDs.size, state.fetchedInstanceIDs.size);
     }
     cache.warmup_complete();
 }
+/**
+ * Creates an empty continuation for a fresh global topology sweep.
+ *
+ * @returns New private pagination and reconciliation state.
+ */
+function procTopologyState_create() {
+    return {
+        offset: 0,
+        total: 0,
+        fetchedInstanceIDs: new Set(),
+        seenInstanceIDs: new Set(),
+        seenFeedIDs: new Set(),
+    };
+}
+/**
+ * Starts one topology sweep from the supplied private continuation state.
+ *
+ * @param state - Private pagination and reconciliation state to run or resume.
+ * @returns The in-flight topology sweep promise.
+ */
+function procTopology_start(state) {
+    procTopologyFailure = undefined;
+    procTopologyResumeState = state;
+    procTopologyScopedResumeFeedIDs = null;
+    const sweep = procTopology_run(state);
+    procTopologyPromise = sweep;
+    sweep.then(() => {
+        if (procTopologyPromise !== sweep)
+            return;
+        procTopologyPromise = null;
+        if ((0, cumin_1.procCache_get)().warmupComplete) {
+            procTopologyFailure = undefined;
+            procTopologyResumeState = null;
+        }
+        else {
+            procTopologyFailure = 'the topology sweep ended before the index completed';
+        }
+    }, (error) => {
+        if (procTopologyPromise !== sweep)
+            return;
+        procTopologyPromise = null;
+        (0, cumin_1.procCache_get)().warmup_abort();
+        procTopologyFailure = error instanceof Error ? error.message : String(error);
+    });
+    return sweep;
+}
+/**
+ * Runs a feed-scoped topology reconciliation selected after checkpoint restore.
+ *
+ * @param feedIDs - Canonical feed IDs whose topology needs a fresh load.
+ * @returns A promise that settles after the supplied feeds are reconciled.
+ */
+async function procTopologyScoped_run(feedIDs) {
+    const cache = (0, cumin_1.procCache_get)();
+    cache.lifecycle_set('reconciling');
+    for (const feedID of feedIDs)
+        await procCache_refresh(feedID);
+    cache.warmup_complete();
+}
+/**
+ * Starts one scoped reconciliation and retains its targets for `proc retry`.
+ *
+ * @param feedIDs - Canonical feed IDs selected by the fresh feed index.
+ * @returns The in-flight scoped reconciliation promise.
+ */
+function procTopologyScoped_start(feedIDs) {
+    const targets = [...feedIDs];
+    procTopologyFailure = undefined;
+    procTopologyResumeState = null;
+    procTopologyScopedResumeFeedIDs = targets;
+    const sweep = procTopologyScoped_run(targets);
+    procTopologyPromise = sweep;
+    sweep.then(() => {
+        if (procTopologyPromise !== sweep)
+            return;
+        procTopologyPromise = null;
+        if ((0, cumin_1.procCache_get)().warmupComplete) {
+            procTopologyFailure = undefined;
+            procTopologyScopedResumeFeedIDs = null;
+        }
+        else {
+            procTopologyFailure = 'the scoped topology reconciliation ended before the index completed';
+        }
+    }, (error) => {
+        if (procTopologyPromise !== sweep)
+            return;
+        procTopologyPromise = null;
+        (0, cumin_1.procCache_get)().warmup_abort();
+        procTopologyFailure = error instanceof Error ? error.message : String(error);
+    });
+    return sweep;
+}
+/**
+ * Starts or joins the session's global plugin-instance topology sweep.
+ *
+ * @returns The single in-flight sweep promise.
+ */
+function procTopology_warmup() {
+    if (procTopologyPromise)
+        return procTopologyPromise;
+    return procTopology_start(procTopologyState_create());
+}
+/**
+ * Reconciles topology only for feed IDs selected by a restored-cache feed-index
+ * comparison. This preserves the checkpointed topology for unchanged terminal
+ * feeds while refreshing new, changed, and active feeds from CUBE.
+ *
+ * @param feedIDs - Canonical CUBE feed IDs whose topology must be reloaded.
+ * @returns A promise that resolves after all supplied feeds have been refreshed.
+ */
+function procTopology_reconcileFeeds(feedIDs) {
+    if (procTopologyPromise)
+        return procTopologyPromise;
+    return procTopologyScoped_start(feedIDs);
+}
+/**
+ * Continues a failed topology reconciliation from its retained global page or
+ * scoped feed set.
+ *
+ * @returns The resumed sweep promise, or the active sweep when one is running.
+ * @throws {Error} When there is no failed sweep continuation to retry.
+ */
+function procTopology_retry() {
+    if (procTopologyPromise)
+        return procTopologyPromise;
+    if (procTopologyFailure === undefined) {
+        throw new Error('no failed topology sweep to retry');
+    }
+    if (procTopologyResumeState)
+        return procTopology_start(procTopologyResumeState);
+    if (procTopologyScopedResumeFeedIDs)
+        return procTopologyScoped_start(procTopologyScopedResumeFeedIDs);
+    throw new Error('no failed topology sweep to retry');
+}
+/**
+ * Reports the session topology sweep lifecycle.
+ *
+ * @returns A snapshot of the lifecycle state and any failure reason.
+ */
+function procTopology_status() {
+    if (procTopologyPromise)
+        return { state: 'running', failure: undefined };
+    if (procTopologyFailure !== undefined)
+        return { state: 'failed', failure: procTopologyFailure };
+    if ((0, cumin_1.procCache_get)().warmupComplete)
+        return { state: 'complete', failure: undefined };
+    return { state: 'idle', failure: undefined };
+}
+/**
+ * Waits for the active topology sweep without starting another.
+ *
+ * @returns A promise that resolves when the active sweep finishes, or
+ * immediately when no sweep is running.
+ */
+async function procTopology_await() {
+    const sweep = procTopologyPromise;
+    if (sweep)
+        await sweep;
+}
 /**
  * Rebuilds the ProcCache, optionally scoped to one feed.
+ *
+ * A full refresh returns feeds whose topology merits reload after the feed-index
+ * comparison. Callers performing an explicit `proc refresh` can ignore that
+ * result and run a global topology sweep; restored startup uses it to stay scoped.
+ *
+ * @param feedID - One feed to force-refresh, or undefined for the full feed index.
+ * @returns IDs whose topology is new, changed, or currently active.
  */
 async function procCache_refresh(feedID) {
     if (feedID !== undefined) {
@@ -534,23 +874,28 @@ async function procCache_refresh(feedID) {
             const page = await typedClient.getFeeds({ id: feedID, limit: 1, offset: 0 });
             const f = (page.data ?? [])[0];
             if (f) {
-                cache.feed_add({
-                    id: Number(f.id),
-                    title: String(f.name),
-                    creationDate: String(f.creation_date ?? ''),
-                    finishedJobs: Number(f.finished_jobs ?? 0),
-                    erroredJobs: Number(f.errored_jobs ?? 0),
-                    startedJobs: Number(f.started_jobs ?? 0),
-                    scheduledJobs: Number(f.scheduled_jobs ?? 0),
-                    cancelledJobs: Number(f.cancelled_jobs ?? 0),
-                    createdJobs: Number(f.created_jobs ?? 0),
-                });
+                cache.feed_add(procFeed_create(f));
             }
         }
         await feedInstances_ensureLoaded(feedID);
+        return [feedID];
     }
     else {
-        await procCache_build();
+        const activeSweep = procTopologyPromise;
+        if (activeSweep) {
+            try {
+                await activeSweep;
+            }
+            catch {
+                // A full refresh replaces any failed sweep with a new idle lifecycle.
+            }
+        }
+        procTopologyPromise = null;
+        procTopologyFailure = undefined;
+        procTopologyResumeState = null;
+        procTopologyScopedResumeFeedIDs = null;
+        (0, cumin_1.procCache_get)().warmup_reset();
+        return procCache_build();
     }
 }
 //# sourceMappingURL=proc.js.map