Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

33.1 KB
Raw Blame
/**
 * System Resources report + AI-assisted cleanup triage.
 *
 * The report is deliberately bounded to storage PortOS already understands:
 * classified data categories, PostgreSQL, model stores, package caches,
 * runtime dependencies, and aggregate browser-download usage. It never walks
 * arbitrary home-directory files and never sends filesystem paths or personal
 * record names to an AI provider.
 */

import os from 'os';
import { scanModelDuplicates } from './modelDeduplication.js';
import { statfs } from 'fs/promises';
import { parseFilesystemStats } from '../lib/fileCore.js';
import { join } from 'path';
import { z } from 'zod';
import { query } from '../lib/db.js';
import { PATHS, dirSize } from '../lib/fileUtils.js';
import { ServerError } from '../lib/errorHandler.js';
import { assertProvider, resolveProviderAndModel, runPromptThroughProvider } from './promptRunner.js';
import { getDataOverview } from './dataManager.js';
import { listHfModelStorage, listLoraStorage } from './mediaModelStorage.js';
import { listModelStore } from './modelStoreStorage.js';
import * as ollamaManager from './ollamaManager.js';
import * as lmStudioManager from './lmStudioManager.js';
import { getQueueCapacity } from './mediaJobQueue/index.js';
import { getAgents } from './cosAgentLifecycle.js';
import { getAllTasks } from './cosTaskStore.js';
import { getStatus } from './cos.js';
import { runningAgentsByTaskId, countSpawningTasks } from '../lib/cosSpawnWindow.js';
import { getSettings } from './settings.js';
import {
  hfInventoryRow,
  localModelInventoryRow,
  loraInventoryRow,
  modelInventoryId,
  modelStoreInventoryRow,
  MODEL_STORE_BACKENDS,
} from '../lib/modelInventory.js';
import { getModelManifest, reconcileModelManifest } from './modelManifest.js';

export const REPORT_CACHE_TTL_MS = 30_000;

const LOW_RISK_DATA_CATEGORIES = new Set([
  'autofixer',
  'browser-downloads',
  'browser-profile',
  'cache',
  'conflict-journal',
  'image-clean-tmp',
  'insights',
  'jira-reports',
  'runs',
  'screenshots',
  'tools',
  'update-detached',
  'video-thumbnails',
]);

const TRIAGE_RESPONSE_SCHEMA = z.object({
  summary: z.string().trim().min(1).max(1400),
  recommendations: z.array(z.object({
    candidateId: z.string().trim().min(1).max(320),
    priority: z.enum(['first', 'next', 'optional']),
    reason: z.string().trim().min(1).max(600),
    tradeoff: z.string().trim().min(1).max(600),
  }).strict()).max(8),
  cautions: z.array(z.string().trim().min(1).max(500)).max(8),
}).strict();

const finiteOrNull = (value) => {
  if (value == null || value === '') return null;
  const number = Number(value);
  return Number.isFinite(number) && number >= 0 ? number : null;
};

const sumBytes = (values) => values.reduce(
  (sum, value) => sum + (Number.isFinite(value) ? value : 0),
  0,
);

const sumKnownBytes = (values) => {
  const known = values.filter(Number.isFinite);
  return known.length > 0 ? sumBytes(known) : null;
};

const backendState = (value) => (value == null ? 'unavailable' : 'ready');

function dataCleanupCandidates(categories) {
  if (!Array.isArray(categories)) return [];
  return categories
    .filter((category) => category.deletable && category.size > 0)
    .map((category) => {
      const oneClick = category.purgeScope === 'category'
        && !category.busy
        && LOW_RISK_DATA_CATEGORIES.has(category.key);
      const manualReview = category.purgeScope === 'items';
      return {
        id: `data:${category.key}`,
        label: category.label,
        kind: 'data',
        estimatedBytes: category.size,
        risk: oneClick ? 'low' : manualReview ? 'high' : 'medium',
        reason: category.description,
        loaded: false,
        busy: Boolean(category.busy),
        manualOnly: !oneClick,
        managePath: '/data',
        action: oneClick ? { type: 'data-category', key: category.key } : null,
      };
    });
}

/**
 * The cleanup candidate for each downloaded-model row.
 *
 * Exported because the manifest-backed inventory (`getTrackedModelInventory`)
 * has to describe its rows exactly as a scan would — the Status page renders both
 * through one component, and a second copy of this risk/`manualOnly` logic is how
 * a delete button ends up armed on a tracked row the scan would have refused.
 *
 * @param {Array<Object>} downloaded Downloaded-model inventory rows
 * @returns {Array<Object>}
 */
export function modelCleanupCandidates(downloaded) {
  return downloaded.map((model) => ({
    id: model.id,
    label: model.name,
    kind: 'model',
    estimatedBytes: model.sizeBytes,
    risk: model.risk || 'medium',
    reason: model.loaded
      ? 'Model weights are installed and the model is currently resident in memory.'
      : model.residencyUnknown
        ? 'PortOS could not verify whether this model is resident. Refresh the backend before deleting it.'
        : model.inventoryUnknown
          ? 'The backend reported this model, but its on-disk folder could not be verified for safe cleanup.'
          : model.cleanupReason || 'Downloaded model weights can be installed again later, but re-downloading may be slow or bandwidth-intensive.',
    loaded: model.loaded,
    busy: model.loaded || model.residencyUnknown,
    manualOnly: model.loaded || model.residencyUnknown || model.inventoryUnknown,
    managePath: model.managePath,
    action: model.loaded || model.residencyUnknown || model.inventoryUnknown ? null : model.action,
  }));
}

/**
 * Build a sorted array of cleanup candidates from data categories, downloaded models, and package caches.
 *
 * @param {Object} options
 * @param {Array<Object>} options.categories Data categories from dataManager
 * @param {Array<Object>} options.downloadedModels Model inventory objects
 * @param {number|null} options.npmCacheBytes Size of npm cache in bytes
 * @returns {Array<Object>} Sorted cleanup candidates by estimated size descending
 */
export function buildCleanupCandidates({ categories, downloadedModels, npmCacheBytes }) {
  const candidates = [
    ...dataCleanupCandidates(categories),
    ...modelCleanupCandidates(downloadedModels),
  ];
  if (Number.isFinite(npmCacheBytes) && npmCacheBytes > 0) {
    candidates.push({
      id: 'cache:npm',
      label: 'npm download cache',
      kind: 'cache',
      estimatedBytes: npmCacheBytes,
      risk: 'low',
      reason: 'Package tarballs are re-downloadable. PortOS reports this cache but does not delete global package-manager state in-app.',
      loaded: false,
      busy: false,
      manualOnly: true,
      managePath: null,
      action: null,
    });
  }
  return candidates.sort((a, b) => (b.estimatedBytes || 0) - (a.estimatedBytes || 0));
}

const normalizeLmStudioRepo = (value) => String(value || '')
  .split('/').pop()
  .trim()
  .toLowerCase()
  .replace(/[-.]gguf$/i, '')
  .replace(/[-.]mlx[-.].*$/i, '');

// File-system model stores beyond the HF hub cache and `data/loras/`; one
// storage area, one inventory backend, one totals key each.
const MODEL_STORES = [
  { backend: 'mtplx', total: 'mtplx', label: 'MTPLX models', note: 'MTPLX checkpoints and the session bank.' },
  { backend: 'hy3dgen', total: 'hy3dgen', label: 'Hunyuan3D models', note: 'Image-to-3D weights in the hy3dgen cache.' },
  { backend: 'hf-xet-cache', total: 'hfXetCache', label: 'Hugging Face xet cache', note: 'Regenerable download chunk cache and xet logs older than 7 days; counted separately from the Hub cache.' },
  { backend: 'pixie-forge', total: 'pixieForge', label: 'Pixie Forge LoRAs', note: 'LoRA adapters outside PortOS data.' },
];

const MODEL_STORE_MANAGE_PATH = Object.fromEntries(Object.entries(MODEL_STORE_BACKENDS).map(([id, store]) => [id, store.managePath]));

const modelStoreRows = (stores) => MODEL_STORES.flatMap(({ backend }) => (stores?.[backend]?.items || []).map((entry) => ({
  ...modelStoreInventoryRow({
    backend,
    key: entry.key,
    name: entry.name,
    detail: entry.detail,
    sizeBytes: entry.size,
    risk: entry.risk,
    cleanupReason: entry.cleanupReason,
  }),
  loaded: false,
})));

function downloadedModelInventory({
  hf,
  loraStorage,
  stores,
  ollamaStatus,
  ollamaStored,
  ollamaLoaded,
  ollamaResidencyError,
  lmStudioModels,
  lmStudioStored,
  lmStudioLoaded,
  lmStudioResidencyError,
}) {
  const ollamaLoadedIds = new Set((ollamaLoaded || []).flatMap((model) => [model.id, model.name]).filter(Boolean));
  const lmStudioLoadedIds = new Set((lmStudioLoaded || []).flatMap((model) => [
    model.id,
    normalizeLmStudioRepo(model.id),
  ]).filter(Boolean));

  // The durable half of every row comes from the shared builders in
  // `lib/modelInventory.js`, which the install chokepoints call too — so a row's
  // risk, manage path, delete action and cleanup sentence cannot drift between the
  // scan and the manifest. Only the LIVE half (residency, whether the on-disk
  // folder could be verified) is added here, because only a scan can know it.
  const huggingFace = (hf?.models || []).map((model) => ({
    ...hfInventoryRow({
      dirName: model.id,
      name: model.label || model.repo,
      detail: model.repo,
      sizeBytes: model.size,
    }),
    loaded: false,
  }));
  const loras = (loraStorage?.loras || []).map((model) => ({
    ...loraInventoryRow({ filename: model.filename, name: model.name, sizeBytes: model.size }),
    loaded: false,
  }));
  const ollamaApi = new Map((ollamaStatus?.models || []).map((model) => [model.id, model]));
  const ollamaDiskModels = Array.isArray(ollamaStored) ? ollamaStored : [];
  const ollamaRows = [
    ...ollamaDiskModels,
    ...(ollamaStatus?.models || []).filter((model) => !ollamaDiskModels.some((stored) => stored.id === model.id))
      .map((model) => ({ ...model, inventoryUnknown: true })),
  ];
  const ollama = ollamaRows.map((stored) => {
    const model = ollamaApi.get(stored.id) || stored;
    return {
      ...localModelInventoryRow({
        backend: 'ollama',
        modelId: stored.id,
        name: model.name || stored.name || stored.id,
        detail: [model.params, model.quantization, model.family].filter(Boolean).join(' · '),
        sizeBytes: finiteOrNull(stored.size ?? model.size),
        // A backend that is not running cannot be asked to delete anything.
        deletable: Boolean(ollamaStatus?.available),
      }),
      loaded: !ollamaResidencyError && ollamaLoadedIds.has(stored.id),
      residencyUnknown: Boolean(ollamaResidencyError),
      inventoryUnknown: !Array.isArray(ollamaStored) || Boolean(stored.inventoryUnknown),
    };
  });

  const lmStudioApiGroups = new Map();
  for (const model of (lmStudioModels || [])) {
    const key = normalizeLmStudioRepo(model.id);
    const group = lmStudioApiGroups.get(key) || { models: [], ids: new Set(), quantizations: new Set() };
    group.models.push(model);
    group.ids.add(model.id);
    if (model.quantization) group.quantizations.add(model.quantization);
    lmStudioApiGroups.set(key, group);
  }
  const lmStudioDiskModels = Array.isArray(lmStudioStored) ? lmStudioStored : [];
  const diskKeys = new Set(lmStudioDiskModels.map((model) => normalizeLmStudioRepo(model.id)));
  const lmStudioRows = [
    ...lmStudioDiskModels,
    ...[...lmStudioApiGroups.entries()]
      .filter(([key]) => !diskKeys.has(key))
      .map(([, group]) => ({
        id: [...group.ids][0],
        name: [...group.ids][0],
        size: group.models.map((model) => finiteOrNull(model.size)).find(Number.isFinite) ?? null,
        inventoryUnknown: true,
      })),
  ];
  const lmstudio = lmStudioRows.map((stored) => {
    const group = lmStudioApiGroups.get(normalizeLmStudioRepo(stored.id));
    const quantizations = group ? [...group.quantizations] : [];
    const loaded = !lmStudioResidencyError && (
      lmStudioLoadedIds.has(stored.id)
      || lmStudioLoadedIds.has(normalizeLmStudioRepo(stored.id))
      || group?.models.some((model) => model.state === 'loaded')
    );
    return {
      ...localModelInventoryRow({
        backend: 'lmstudio',
        modelId: stored.id,
        name: stored.name || stored.id,
        detail: [
          quantizations.length ? `${quantizations.length} quantization${quantizations.length === 1 ? '' : 's'}: ${quantizations.join(', ')}` : null,
          'removes the whole model folder',
        ].filter(Boolean).join(' · '),
        sizeBytes: finiteOrNull(stored.size),
      }),
      // A row the API reported but the disk listing did not is sized from the
      // API's own number, which is a claim rather than a measurement.
      sizeIsEstimate: Boolean(stored.inventoryUnknown),
      loaded,
      residencyUnknown: Boolean(lmStudioResidencyError),
      inventoryUnknown: !Array.isArray(lmStudioStored) || Boolean(stored.inventoryUnknown),
    };
  });
  return [...huggingFace, ...loras, ...modelStoreRows(stores), ...ollama, ...lmstudio]
    .sort((a, b) => (b.sizeBytes || 0) - (a.sizeBytes || 0));
}

function loadedModelInventory({ ollamaLoaded, lmStudioLoaded }) {
  return [
    ...(ollamaLoaded || []).map((model) => ({
      id: modelInventoryId('ollama', model.id),
      backend: 'ollama',
      name: model.name || model.id,
      memoryBytes: finiteOrNull(model.sizeVram ?? model.size),
      expiresAt: model.expiresAt || null,
    })),
    ...(lmStudioLoaded || []).map((model) => ({
      id: modelInventoryId('lmstudio', model.id),
      backend: 'lmstudio',
      name: model.id,
      memoryBytes: null,
      expiresAt: null,
    })),
  ];
}

// Remember transitions across report/cache refreshes without logging private errors.
let agentCensusUnavailable = false;

function readAgentCensus() {
  return getAgents().then((agents) => {
    if (agentCensusUnavailable) console.log('✅ Resource probe recovered (source=agent-census)');
    agentCensusUnavailable = false;
    return agents;
  }).catch((error) => {
    if (!agentCensusUnavailable) {
      const code = typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]{0,31}$/.test(error.code) ? error.code : 'unknown';
      console.error(`❌ Resource probe unavailable (source=agent-census, code=${code})`);
    }
    agentCensusUnavailable = true;
    return null;
  });
}

/**
 * Queue depth vs work in flight, settled against the agent list.
 *
 * A mid-spawn task moves from the pending counts to `inProgress` rather than
 * being counted on both sides (lib/cosSpawnWindow.js), so the two halves move
 * together and the summary's queued+running total never dips while a spawn
 * lands. `awaitingApproval` needs no settling: approval is a pre-spawn gate
 * (`forceSpawnTask` refuses an unapproved task and approving clears the flag),
 * so no live agent can hold one.
 */
function agentQueueSummary(tasks, status, agents) {
  if (!tasks) return null;
  const censusAvailable = agents != null;
  const runningAgents = runningAgentsByTaskId(agents);
  const pendingUser = tasks.user?.grouped?.pending || [];
  const pendingSystem = tasks.cos?.grouped?.pending || [];
  const spawningUser = countSpawningTasks(pendingUser, runningAgents);
  const spawningSystem = countSpawningTasks(pendingSystem, runningAgents);
  return {
    pendingUser: censusAvailable ? pendingUser.length - spawningUser : null,
    pendingSystem: censusAvailable ? pendingSystem.length - spawningSystem : null,
    awaitingApproval: tasks.cos?.awaitingApproval?.length || 0,
    inProgress: censusAvailable ? (tasks.user?.grouped?.in_progress?.length || 0)
      + (tasks.cos?.grouped?.in_progress?.length || 0)
      + spawningUser + spawningSystem : null,
    activeAgents: status ? status.activeAgents || 0 : null,
    pausedAgents: status ? status.pausedAgents || 0 : null,
    daemonRunning: status?.running ?? null,
    daemonPaused: status?.paused ?? null,
  };
}

export async function buildSystemResourceReport() {
  const npmCachePath = process.env.npm_config_cache || join(os.homedir(), '.npm');
  const dependencyPaths = [
    join(PATHS.root, 'node_modules'),
    join(PATHS.root, 'client', 'node_modules'),
    join(PATHS.root, 'server', 'node_modules'),
  ];

  const [
    diskStats,
    dataDiskStats,
    dataOverview,
    databaseRow,
    hf,
    loraStorage,
    mtplxStore,
    hy3dgenStore,
    xetStore,
    pixieForgeStore,
    ollamaStatus,
    ollamaStored,
    ollamaLoaded,
    ollamaBytes,
    lmStudioAvailable,
    lmStudioModels,
    lmStudioStored,
    lmStudioLoaded,
    lmStudioBytes,
    settings,
    npmCacheBytes,
    dependencySizes,
    browserDownloadsBytes,
    cosTasks,
    cosStatus,
    cosAgents,
    modelDuplicates,
  ] = await Promise.all([
    statfs('/').catch(() => null),
    statfs(PATHS.data).catch(() => null),
    getDataOverview({ strict: true }).catch(() => null),
    query('SELECT pg_database_size(current_database()) AS bytes')
      .then((result) => result.rows[0] || null)
      .catch(() => null),
    listHfModelStorage({ strict: true }).catch(() => null),
    listLoraStorage({ strict: true }).catch(() => null),
    ...MODEL_STORES.map(({ backend }) => listModelStore(backend).catch(() => null)),
    ollamaManager.getStatus(true).catch(() => null),
    ollamaManager.listStoredModels().catch(() => null),
    ollamaManager.getLoadedModels().catch(() => null),
    dirSize(ollamaManager.getModelsDir(), { strict: true }).catch(() => null),
    lmStudioManager.checkLMStudioAvailable(true).catch(() => null),
    lmStudioManager.getAvailableModels(true).catch(() => null),
    lmStudioManager.listStoredModels().catch(() => null),
    lmStudioManager.getLoadedModels(true).catch(() => null),
    lmStudioManager.getModelsDir().then((path) => dirSize(path, { strict: true })).catch(() => null),
    getSettings().catch(() => null),
    dirSize(npmCachePath, { strict: true }).catch(() => null),
    Promise.all(dependencyPaths.map((path) => dirSize(path, { strict: true }).catch(() => null))),
    dirSize(PATHS.browserDownloads, { strict: true }).catch(() => null),
    getAllTasks().catch(() => null),
    getStatus().catch(() => null),
    readAgentCensus(),
    scanModelDuplicates().catch(() => ({ pinokioDetected: null, items: [], totalReclaimableBytes: 0, error: 'Duplicate model scan unavailable' })),
  ]);

  const parsedFilesystem = parseFilesystemStats(diskStats);
  const filesystem = parsedFilesystem && {
    totalBytes: parsedFilesystem.totalBytes,
    usedBytes: parsedFilesystem.usedBytes,
    freeBytes: parsedFilesystem.freeBytes,
    usagePercent: parsedFilesystem.usagePercent,
  };
  const parsedDataFilesystem = parseFilesystemStats(dataDiskStats);
  const dataFilesystem = parsedDataFilesystem && {
    totalBytes: parsedDataFilesystem.totalBytes,
    usedBytes: parsedDataFilesystem.usedBytes,
    freeBytes: parsedDataFilesystem.freeBytes,
    usagePercent: parsedDataFilesystem.usagePercent,
  };
  const databaseBytes = finiteOrNull(databaseRow?.bytes);
  const dependenciesBytes = sumKnownBytes(dependencySizes);
  const ollamaResidencyError = ollamaLoaded == null
    ? 'Ollama residency probe failed'
    : ollamaManager.getLastLoadedModelsError();
  const lmStudioResidencyError = lmStudioLoaded == null
    ? 'LM Studio residency probe failed'
    : lmStudioManager.getLastLoadedModelsError();
  const lmStudioListError = lmStudioModels == null
    ? 'LM Studio model inventory failed'
    : lmStudioManager.getLastListError();
  const disabledSources = [
    ...(settings?.localLlm?.ollama?.disabled ? ['ollama'] : []),
    ...(settings?.localLlm?.lmstudio?.disabled ? ['lmstudio'] : []),
  ];
  const stores = {
    mtplx: mtplxStore,
    hy3dgen: hy3dgenStore,
    'hf-xet-cache': xetStore,
    'pixie-forge': pixieForgeStore,
  };
  const downloadedModels = downloadedModelInventory({
    hf,
    loraStorage,
    stores,
    ollamaStatus,
    ollamaStored,
    ollamaLoaded,
    ollamaResidencyError,
    lmStudioModels,
    lmStudioStored,
    lmStudioLoaded,
    lmStudioResidencyError,
  });
  const loadedModels = loadedModelInventory({ ollamaLoaded, lmStudioLoaded });
  const categories = dataOverview?.categories || null;
  const cleanupCandidates = buildCleanupCandidates({
    categories,
    downloadedModels,
    npmCacheBytes,
  });
  const capacity = getQueueCapacity();
  const mediaQueue = {
    queued: capacity.totals.queued,
    running: capacity.totals.running,
    byKind: capacity.byKind,
  };
  const agentQueue = agentQueueSummary(cosTasks, cosStatus, cosAgents);
  const modelBytes = sumKnownBytes([
    hf?.totalBytes,
    loraStorage?.totalBytes,
    ...MODEL_STORES.map(({ backend }) => stores[backend]?.totalBytes),
    ollamaBytes,
    lmStudioBytes,
  ]);
  const storageAreas = [
    {
      id: 'portos-data', label: 'PortOS data', kind: 'data',
      sizeBytes: finiteOrNull(dataOverview?.totalSize), status: backendState(dataOverview),
      managePath: '/data', protected: false,
      note: 'Generated media, records, backups, worktrees, caches, and other classified app data.',
    },
    {
      id: 'postgres', label: 'PostgreSQL', kind: 'database',
      sizeBytes: databaseBytes, status: backendState(databaseRow),
      managePath: '/settings/database', protected: true,
      note: 'Primary relational records and vector indexes.',
    },
    {
      id: 'huggingface', label: 'Hugging Face models', kind: 'model',
      sizeBytes: finiteOrNull(hf?.totalBytes), status: backendState(hf),
      managePath: '/models/media', protected: false,
      note: 'Image, video, audio, and text-encoder weights in the shared Hub cache.',
    },
    {
      id: 'loras', label: 'LoRA adapters', kind: 'model',
      sizeBytes: finiteOrNull(loraStorage?.totalBytes), status: backendState(loraStorage),
      managePath: '/models/loras', protected: false,
      note: 'Fine-tuning adapters in PortOS data. This total also appears inside PortOS data.',
    },
    ...MODEL_STORES.map(({ backend, label, note }) => ({
      id: backend, label, kind: 'model',
      sizeBytes: finiteOrNull(stores[backend]?.totalBytes), status: backendState(stores[backend]),
      managePath: MODEL_STORE_MANAGE_PATH[backend], protected: false,
      note,
    })),
    {
      id: 'ollama', label: 'Ollama models', kind: 'model',
      sizeBytes: finiteOrNull(ollamaBytes), status: backendState(ollamaBytes),
      managePath: '/models/llms', protected: false,
      note: 'Local language-model manifests and shared blobs.',
    },
    {
      id: 'lmstudio', label: 'LM Studio models', kind: 'model',
      sizeBytes: finiteOrNull(lmStudioBytes), status: backendState(lmStudioBytes),
      managePath: '/models/llms', protected: false,
      note: 'Downloaded GGUF or MLX model directories.',
    },
    {
      id: 'npm-cache', label: 'npm cache', kind: 'cache',
      sizeBytes: finiteOrNull(npmCacheBytes), status: backendState(npmCacheBytes),
      managePath: null, protected: false,
      note: 'Global package download cache; reported only, never deleted in-app.',
    },
    {
      id: 'dependencies', label: 'PortOS dependencies', kind: 'runtime',
      sizeBytes: dependenciesBytes,
      status: dependencySizes.every(Number.isFinite) ? 'ready' : 'unavailable',
      managePath: null, protected: true,
      note: 'Installed Node.js dependencies required by the running app.',
    },
    {
      id: 'browser-downloads', label: 'Browser downloads', kind: 'personal',
      sizeBytes: finiteOrNull(browserDownloadsBytes), status: backendState(browserDownloadsBytes),
      managePath: null, protected: true,
      note: 'Aggregate Downloads-folder usage. File names are never inspected or sent to AI.',
    },
  ];
  const storageErrors = storageAreas
    .filter((area) => area.status === 'unavailable')
    .map((area) => area.id);
  const sourceErrors = [...new Set([
    ...storageErrors,
    ...(!filesystem ? ['filesystem'] : []),
    ...(!dataFilesystem ? ['data-filesystem'] : []),
    ...(!ollamaStatus?.available ? ['ollama-backend'] : []),
    ...(ollamaStored == null ? ['ollama-inventory'] : []),
    ...(ollamaResidencyError ? ['ollama-residency'] : []),
    ...(lmStudioAvailable !== true ? ['lmstudio-backend'] : []),
    ...(lmStudioStored == null ? ['lmstudio-inventory'] : []),
    ...(lmStudioListError ? ['lmstudio-catalog'] : []),
    ...(lmStudioResidencyError ? ['lmstudio-residency'] : []),
    ...(cosTasks == null ? ['agent-queue'] : []),
    ...(cosStatus == null ? ['agent-status'] : []),
    ...(cosAgents == null ? ['agent-census'] : []),
  ])];
  const managedReclaimableBytes = sumBytes(cleanupCandidates
    .filter((candidate) => candidate.risk === 'low' && candidate.action)
    .map((candidate) => candidate.estimatedBytes));
  const queuedAgents = agentQueue && cosAgents != null
    // Awaiting-approval tasks are already part of pendingSystem. Keep the
    // review count as a useful breakdown without counting those tasks twice in
    // the top-line queued total.
    ? agentQueue.pendingUser + agentQueue.pendingSystem
    : null;

  // Every full scan heals the persisted manifest, so Models → Status has a fresh
  // answer to fall back on next time without walking the model stores again, and
  // weights installed or deleted outside PortOS get picked up. Scoped to the
  // backends this scan could actually see — `reconcileModelManifest` will not
  // prune against a disabled or unreachable one.
  const manifest = await reconcileModelManifest(downloadedModels, { sourceErrors, disabledSources });

  return {
    generatedAt: new Date().toISOString(),
    inventorySource: 'scan',
    manifestReconciledAt: manifest?.reconciledAt || null,
    filesystem,
    dataFilesystem,
    summary: {
      knownFootprintBytes: sumKnownBytes(storageAreas.map((area) => area.sizeBytes)),
      footprintMayOverlap: true,
      portosDataBytes: finiteOrNull(dataOverview?.totalSize),
      databaseBytes,
      modelBytes,
      managedReclaimableBytes,
      loadedModels: loadedModels.length,
      queuedJobs: queuedAgents != null ? mediaQueue.queued + queuedAgents : null,
      runningJobs: agentQueue?.inProgress != null ? mediaQueue.running + agentQueue.inProgress : null,
    },
    storageAreas,
    dataCategories: categories,
    models: {
      downloaded: downloadedModels,
      loaded: loadedModels,
      totals: {
        huggingface: finiteOrNull(hf?.totalBytes),
        loras: finiteOrNull(loraStorage?.totalBytes),
        ...Object.fromEntries(MODEL_STORES.map(({ backend, total }) => [total, finiteOrNull(stores[backend]?.totalBytes)])),
        ollama: finiteOrNull(ollamaBytes),
        lmstudio: finiteOrNull(lmStudioBytes),
        all: modelBytes,
      },
    },
    queues: { media: mediaQueue, agents: agentQueue },
    cleanupCandidates,
    modelDuplicates,
    sourceErrors,
    disabledSources,
  };
}

let reportCache = null;
let reportCacheAt = 0;
let reportInFlight = null;

export function resetSystemResourceReportCache() {
  reportCache = null;
  reportCacheAt = 0;
  reportInFlight = null;
}

/**
 * Fetch or compute the cached system resource report.
 *
 * @param {Object} [options]
 * @param {boolean} [options.force=false] Force bypassing the 30-second report cache
 * @returns {Promise<Object>} System resource report containing storage breakdown, queues, and cleanup candidates
 */
export function getSystemResourceReport({ force = false } = {}) {
  if (!force && reportCache && Date.now() - reportCacheAt < REPORT_CACHE_TTL_MS) {
    return Promise.resolve(reportCache);
  }
  if (!reportInFlight) {
    reportInFlight = buildSystemResourceReport().then(
      (report) => {
        reportCache = report;
        reportCacheAt = Date.now();
        reportInFlight = null;
        return report;
      },
      (error) => {
        reportInFlight = null;
        throw error;
      },
    );
  }
  return reportInFlight;
}

/**
 * The downloaded-model inventory as the manifest already knows it — no disk scan.
 *
 * This is what Models → Status loads on arrival. It is shaped as a PARTIAL system
 * resource report rather than a bespoke payload so the page renders it through the
 * same component that renders a live scan: the two differ in `inventorySource` and
 * in the fields only a scan can supply — live residency, and the duplicate-weight
 * report, whose scan is the most expensive walk of them all.
 *
 * `reconciledAt: null` means no scan has ever reconciled this install — the page
 * shows its "run the inventory" prompt rather than claiming an empty machine.
 *
 * @returns {Promise<Object>} Partial report: `{ inventorySource: 'manifest', … }`
 */
export async function getTrackedModelInventory() {
  const manifest = await getModelManifest();
  const downloaded = manifest.models;
  // `sumKnownBytes` already answers null for a list with no finite sizes, which
  // covers a backend with no tracked rows at all.
  const backendTotal = (backend) => sumKnownBytes(
    downloaded.filter((model) => model.backend === backend).map((model) => model.sizeBytes),
  );
  return {
    inventorySource: 'manifest',
    generatedAt: manifest.reconciledAt,
    reconciledAt: manifest.reconciledAt,
    models: {
      downloaded,
      loaded: [],
      totals: {
        huggingface: backendTotal('huggingface'),
        loras: backendTotal('lora'),
        ...Object.fromEntries(MODEL_STORES.map(({ backend, total }) => [total, backendTotal(backend)])),
        ollama: backendTotal('ollama'),
        lmstudio: backendTotal('lmstudio'),
        all: sumKnownBytes(downloaded.map((model) => model.sizeBytes)),
      },
    },
    cleanupCandidates: modelCleanupCandidates(downloaded),
    // A duplicate-weight scan is exactly the expensive walk this endpoint exists to
    // avoid, so the panel renders nothing for it until the user asks for a refresh.
    modelDuplicates: null,
    sourceErrors: [],
    disabledSources: [],
  };
}

export function buildSystemResourceTriagePrompt(report) {
  const candidates = report.cleanupCandidates.slice(0, 50).map((candidate, index) => ({
    // Deliberately opaque. A model id or LoRA filename can contain a personal
    // project name, so even candidate identifiers stay machine-local.
    id: `candidate-${index + 1}`,
    kind: candidate.kind,
    estimatedBytes: candidate.estimatedBytes,
    risk: candidate.risk,
    reason: candidate.reason,
    loaded: candidate.loaded,
    busy: candidate.busy,
    manualOnly: candidate.manualOnly,
    actionable: Boolean(candidate.action),
  }));
  const context = {
    filesystem: report.filesystem,
    summary: report.summary,
    queues: report.queues,
    unavailableSources: report.sourceErrors,
    candidates,
  };
  return `You are triaging disk pressure for a private, single-user PortOS installation.

Rank only the cleanup candidates supplied below. Never invent a path, file, command, candidate id, or deletion action. Treat byte counts as estimates: model layers and hardlinks can overlap, and deleting one tagged model may reclaim less than its displayed size. Do not recommend deleting a loaded or busy item until it is unloaded or idle. Respect risk: prefer low-risk reproducible caches, explain rebuild/download costs, and put protected or user-authored data behind manual review. If free space is healthy, say so and keep recommendations conservative.

Return ONLY JSON with this exact shape:
{
  "summary": "short assessment",
  "recommendations": [
    { "candidateId": "one supplied id", "priority": "first|next|optional", "reason": "why it helps", "tradeoff": "what is lost or rebuilt" }
  ],
  "cautions": ["important caveat"]
}

SYSTEM REPORT (no filesystem paths or personal filenames):
${JSON.stringify(context, null, 2)}`;
}

/**
 * Perform AI-assisted system storage triage based on the current system resource report.
 *
 * @param {Object} [options]
 * @param {string} [options.providerId] AI provider identifier
 * @param {string} [options.model] Specific AI model to use
 * @param {string} [options.effort] Effort level for supported reasoning models
 * @param {Function} [options.onRunCreated] Callback invoked when an AI run is spawned
 * @param {Function} [options.onRunSettled] Callback invoked when an AI run settles
 * @returns {Promise<Object>} Triage result containing structured recommendations and cautions
 */
export async function triageSystemResources({
  providerId,
  model,
  effort,
  onRunCreated,
  onRunSettled,
} = {}) {
  const report = await getSystemResourceReport();
  const triageCandidates = report.cleanupCandidates.slice(0, 50);
  const { provider, selectedModel } = await resolveProviderAndModel({ providerId, model });
  assertProvider(provider, {
    message: 'No AI provider is configured for system-resource triage',
    code: 'NO_PROVIDER',
  });

  const result = await runPromptThroughProvider({
    provider,
    model: selectedModel,
    effort,
    prompt: buildSystemResourceTriagePrompt(report),
    source: 'system-resource-triage',
    responseSchema: TRIAGE_RESPONSE_SCHEMA,
    onRunCreated,
    onRunSettled,
  });
  const parsed = TRIAGE_RESPONSE_SCHEMA.parse(JSON.parse(result.text));
  const candidatesById = new Map(triageCandidates.map((candidate, index) => [`candidate-${index + 1}`, candidate]));
  const seen = new Set();
  const recommendations = parsed.recommendations.flatMap((recommendation) => {
    const candidate = candidatesById.get(recommendation.candidateId);
    if (!candidate || seen.has(candidate.id)) return [];
    seen.add(candidate.id);
    return [{ ...recommendation, candidateId: candidate.id, candidate }];
  });
  if (parsed.recommendations.length > 0 && recommendations.length === 0) {
    throw new ServerError('AI triage did not reference any known cleanup candidate', {
      status: 502,
      code: 'LLM_OUTPUT_CONTRACT',
    });
  }

  return {
    report,
    triage: {
      summary: parsed.summary,
      recommendations,
      cautions: parsed.cautions,
      runId: result.runId,
      providerId: result.provider?.id || provider.id,
      model: result.model || selectedModel,
    },
  };
}