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

31.0 KB
Raw Blame
import { join } from 'path';
import { statSync } from 'fs';
import { v4 as uuidv4 } from '../lib/uuid.js';
import EventEmitter from 'events';
import { atomicWrite, ensureDir, readJSONFile, PATHS } from '../lib/fileUtils.js';
import {
  containsPortosRootToken,
  expandPortosRootInApp,
} from '../lib/portosRootPlaceholder.js';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
import { NON_PM2_TYPES } from './appProcessTypes.js';
import { SELF_IMPROVEMENT_TASK_TYPES } from './taskScheduleRegistry.js';
import { sanitizeTaskMetadata } from '../lib/cosValidation.js';
import { isPlainObject } from '../lib/objects.js';
import { createMutex } from '../lib/asyncMutex.js';
import { resolveAppWorkTracker } from '../lib/workTracker.js';
import { PORTS } from '../lib/ports.js';
import { hasTailscaleCert } from '../../lib/tailscale-https.js';
import { certPaths } from '../../lib/certPaths.js';

const DATA_DIR = PATHS.data;
const APPS_FILE = join(DATA_DIR, 'apps.json');

function isExistingDirectory(p) {
  if (typeof p !== 'string' || !p) return false;
  try { return statSync(p).isDirectory(); } catch { return false; }
}

// Stable ID for the PortOS app — always present, never deletable. Defined in
// `lib/appIdentity.js` so a caller that only needs to name PortOS (a CoS task's
// target app, a scope check) can import it without this whole service graph;
// re-exported here so every existing importer is unchanged.
export { PORTOS_APP_ID };

/**
 * Build the baseline PortOS app entry with repoPath resolved to the actual project root.
 */
function buildPortosApp() {
  // tlsPort reflects whether the Tailscale cert is actually on disk; if not,
  // don't advertise HTTPS so the Launch button doesn't target a broken scheme.
  const certPresent = hasTailscaleCert(certPaths(PATHS.data).dir);
  return {
    name: 'PortOS',
    description: 'Local App OS portal for dev machines',
    repoPath: PATHS.root,
    type: 'express',
    uiPort: PORTS.API,
    // Production serves the built client from the API process; no Vite dev UI
    // is available for the PortOS management entry.
    devUiPort: null,
    apiPort: PORTS.API,
    tlsPort: certPresent ? PORTS.API : null,
    buildCommand: 'npm run build',
    startCommands: ['npm start'],
    // Match npm start: Vite is development-only, not an expected production process.
    pm2ProcessNames: [
      'portos-server',
      'portos-cos',
      'portos-autofixer',
      'portos-autofixer-ui',
      'portos-browser'
    ],
    processes: [
      // portos-server binds a loopback HTTP mirror on API_LOCAL only when HTTPS is active
      // on API. If no cert is present, don't advertise api-local — nothing is listening
      // there and Overview would otherwise show a dead port.
      { name: 'portos-server', port: PORTS.API, ports: certPresent ? { api: PORTS.API, 'api-local': PORTS.API_LOCAL } : { api: PORTS.API } },
      { name: 'portos-cos', port: PORTS.COS, ports: { api: PORTS.COS } },
      { name: 'portos-autofixer', port: PORTS.AUTOFIXER, ports: { api: PORTS.AUTOFIXER } },
      { name: 'portos-autofixer-ui', port: PORTS.AUTOFIXER_UI, ports: { ui: PORTS.AUTOFIXER_UI } },
      { name: 'portos-browser', port: PORTS.CDP, ports: { cdp: PORTS.CDP, health: PORTS.CDP_HEALTH } }
    ],
    envFile: '.env',
    icon: 'portos',
    editorCommand: 'code .',
    archived: false,
    createdAt: '2024-01-01T00:00:00.000Z',
    updatedAt: '2024-01-01T00:00:00.000Z'
  };
}

// Event emitter for apps changes
export const appsEvents = new EventEmitter();

// Every apps.json read-modify-write runs under this mutex. Without it, two
// writers that both missed the cache (or that interleave across an await such
// as resetWatchersIfDisabled) each mutate their own snapshot and the later
// atomicWrite silently reverts the earlier writer's change.
const withAppsLock = createMutex();
// Bumped on every save/invalidate so a read that began before a write cannot
// install its stale snapshot into the cache after the write lands.
let cacheGeneration = 0;

// In-memory cache for apps data
let appsCache = null;
let cacheTimestamp = 0;
const CACHE_TTL_MS = 2000; // Cache for 2 seconds to reduce file reads during rapid polling

/**
 * Load apps registry from disk (with caching).
 * Ensures the PortOS baseline app always exists.
 */
async function loadApps() {
  const now = Date.now();

  // Return cached data if still valid
  if (appsCache && (now - cacheTimestamp) < CACHE_TTL_MS) {
    return appsCache;
  }

  const generation = cacheGeneration;
  await ensureDir(DATA_DIR);

  // STRICT (#4115): this reader WRITES — an empty `data.apps` makes the baseline
  // branch below rewrite apps.json with a lone PortOS entry, so a swallowed
  // EACCES/EIO would delete every registered app. Absent is still a legitimate
  // first-run empty; unreadable is not.
  const data = await readJSONFile(APPS_FILE, { apps: {} }, { strict: true });

  // Normalize: ensure data.apps is always an object
  if (!data.apps || typeof data.apps !== 'object') {
    data.apps = {};
  }

  // Safety net: expand leftover `__PORTOS_ROOT__` tokens from a partial
  // data.reference copy (setup-data only rewrote them on first create historically).
  // Persist so Apps → Git stops looking for `__PORTOS_ROOT__/.git`.
  let placeholderDirty = false;
  for (const [id, app] of Object.entries(data.apps)) {
    const { app: expanded, changed } = expandPortosRootInApp(app, PATHS.root);
    if (changed) {
      data.apps[id] = expanded;
      placeholderDirty = true;
    }
  }

  // Ensure PortOS baseline app is always present and up-to-date
  const baseline = buildPortosApp();
  if (!data.apps[PORTOS_APP_ID]) {
    data.apps[PORTOS_APP_ID] = baseline;
    await atomicWrite(APPS_FILE, data);
    console.log('📦 Seeded baseline PortOS app into apps registry');
  } else {
    // Reconcile: merge new baseline fields into existing entry (preserves user overrides)
    let dirty = placeholderDirty;
    for (const [key, value] of Object.entries(baseline)) {
      if (!(key in data.apps[PORTOS_APP_ID])) {
        data.apps[PORTOS_APP_ID][key] = value;
        dirty = true;
      }
    }
    // Force-sync specific fields that should always match the code definition
    const forceSync = ['uiPort', 'devUiPort', 'apiPort', 'tlsPort', 'buildCommand', 'startCommands', 'processes', 'pm2ProcessNames'];
    for (const key of forceSync) {
      if (JSON.stringify(data.apps[PORTOS_APP_ID][key]) !== JSON.stringify(baseline[key])) {
        data.apps[PORTOS_APP_ID][key] = baseline[key];
        dirty = true;
      }
    }
    // A literal `__PORTOS_ROOT__` is not a real user override — force repoPath
    // to the live checkout. Concrete custom paths are preserved (expand left them).
    if (containsPortosRootToken(data.apps[PORTOS_APP_ID].repoPath)) {
      data.apps[PORTOS_APP_ID].repoPath = baseline.repoPath;
      dirty = true;
    }
    // A restored snapshot from another checkout carries that checkout's absolute
    // path. A repoPath that is not an existing directory cannot be a working
    // override, so rebind to the running checkout (#12483).
    const storedRepoPath = data.apps[PORTOS_APP_ID].repoPath;
    if (storedRepoPath !== baseline.repoPath && !isExistingDirectory(storedRepoPath)) {
      console.warn(`⚠️ PortOS app repoPath ${storedRepoPath} is not a directory; resetting to ${baseline.repoPath}`);
      data.apps[PORTOS_APP_ID].repoPath = baseline.repoPath;
      dirty = true;
    }
    if (dirty) {
      await atomicWrite(APPS_FILE, data);
      console.log(placeholderDirty
        ? '📦 Expanded __PORTOS_ROOT__ placeholders and reconciled PortOS baseline app'
        : '📦 Reconciled PortOS baseline app with latest fields');
    }
  }

  // A write (or invalidate) that landed while we were reading means this
  // snapshot is stale: hand it to our caller but never cache it, or the next
  // locked writer would start from it and revert that write.
  if (generation === cacheGeneration) {
    appsCache = data;
    cacheTimestamp = now;
  }
  return data;
}

/**
 * Save apps registry to disk (and invalidate cache)
 */
async function saveApps(data) {
  await ensureDir(DATA_DIR);
  await atomicWrite(APPS_FILE, data);
  // Update cache with saved data
  cacheGeneration += 1;
  appsCache = data;
  cacheTimestamp = Date.now();
}

/**
 * Run a read-modify-write of apps.json exclusively. The cached object is mutated
 * in place, so a body that throws before saving would leave uncommitted edits in
 * the cache for readers; drop the cache so the next read reflects the file.
 */
function withAppsWrite(fn) {
  return withAppsLock(async () => {
    try {
      return await fn();
    } catch (err) {
      invalidateCache();
      throw err;
    }
  });
}

/**
 * Invalidate the apps cache (call after external changes)
 */
export function invalidateCache() {
  cacheGeneration += 1;
  appsCache = null;
  cacheTimestamp = 0;
}

/**
 * Notify clients that apps data has changed
 * Call this after any operation that modifies app state
 */
export function notifyAppsChanged(action = 'update', appId) {
  appsEvents.emit('changed', {
    action,
    ...(appId ? { appId } : {}),
    timestamp: Date.now()
  });
}

/**
 * Get all apps (injects id from key)
 * @param {Object} options - Filter options
 * @param {boolean} options.includeArchived - Include archived apps (default: true for backwards compatibility)
 */
export async function getAllApps({ includeArchived = true } = {}) {
  const data = await loadApps();
  const apps = Object.entries(data.apps).map(([id, app]) => ({ id, ...app }));

  if (!includeArchived) {
    return apps.filter(app => !app.archived);
  }

  return apps;
}

/**
 * Get all active (non-archived) apps
 */
export async function getActiveApps() {
  return getAllApps({ includeArchived: false });
}

/**
 * Get app by ID (injects id from key)
 */
export async function getAppById(id) {
  const data = await loadApps();
  const app = data?.apps?.[id];
  return app ? { id, ...app } : null;
}

/**
 * Create a new app
 */
export function createApp(appData) {
  return withAppsWrite(() => createAppUnlocked(appData));
}

async function createAppUnlocked(appData) {
  const data = await loadApps();
  const id = uuidv4();
  const now = new Date().toISOString();

  // Store without id (key is id) and without uiUrl (derived from uiPort)
  const app = {
    name: appData.name,
    description: appData.description || '',
    repoPath: appData.repoPath,
    companionRepoPaths: Array.isArray(appData.companionRepoPaths) ? [...appData.companionRepoPaths] : [],
    type: appData.type || 'unknown',
    uiPort: appData.uiPort || null,
    devUiPort: appData.devUiPort || null,
    apiPort: appData.apiPort || null,
    buildCommand: appData.buildCommand || undefined,
    updateCommand: appData.updateCommand || undefined,
    startCommands: appData.startCommands || ['npm run dev'],
    pm2ProcessNames: appData.pm2ProcessNames || [appData.name.toLowerCase().replace(/\s+/g, '-')],
    nativeLaunch: appData.nativeLaunch || null,
    envFile: appData.envFile || '.env',
    icon: appData.icon || null,
    appIconPath: appData.appIconPath || null,
    editorCommand: appData.editorCommand
      || (NON_PM2_TYPES.has(appData.type) && process.platform === 'darwin' ? 'xed .' : 'code .'),
    archived: false,
    jira: appData.jira || null,
    // Where this app's autonomous work items live. 'auto' resolves to a
    // concrete tracker (PLAN.md / GitHub / GitLab / JIRA) from the git origin
    // host at dispatch time — see server/lib/workTracker.js.
    workTracker: appData.workTracker || 'auto',
    // Preserve explicit workflow choices at creation as well as update. Missing
    // fields inherit the current defaults when a new task is queued.
    ...(typeof appData.defaultUseWorktree === 'boolean' ? { defaultUseWorktree: appData.defaultUseWorktree } : {}),
    ...(typeof appData.defaultOpenPR === 'boolean' ? { defaultOpenPR: appData.defaultOpenPR } : {}),
    ...(appData.defaultPrCompletion !== undefined ? { defaultPrCompletion: appData.defaultPrCompletion } : {}),
    // The gh account this app's repo is driven under. Absent (the default) means
    // "infer from the repo owner" — see services/forgeAuth.js.
    ...(appData.forgeAccount?.trim() ? { forgeAccount: appData.forgeAccount.trim() } : {}),
    // Only persisted when explicitly sent. Absent means ON (see
    // repoStateVerificationEnabled), so writing a default here would freeze the
    // app against a future change of that default — but an explicit `false` on
    // create MUST survive, or a new app cannot opt out through POST at all.
    ...(Number.isSafeInteger(appData.mergeHandoffMinQueuedRuns) && appData.mergeHandoffMinQueuedRuns > 0
      ? { mergeHandoffMinQueuedRuns: appData.mergeHandoffMinQueuedRuns } : {}),
    ...(typeof appData.verifyRepoStateOnCompletion === 'boolean'
      ? { verifyRepoStateOnCompletion: appData.verifyRepoStateOnCompletion }
      : {}),
    taskTypeOverrides: Object.fromEntries(
      SELF_IMPROVEMENT_TASK_TYPES.map(t => [t, { enabled: false }])
    ),
    createdAt: now,
    updatedAt: now
  };

  // Persist an explicitly-provided Layered Intelligence config on create; when
  // omitted the app has no key and the config accessor supplies the baseline on
  // first read (no per-app seed write). Only set it when present so absent stays
  // absent — createApp otherwise builds the object field-by-field and would drop it.
  if (appData.layeredIntelligence && typeof appData.layeredIntelligence === 'object') {
    app.layeredIntelligence = appData.layeredIntelligence;
  }

  // An absent map means every managed-app feature inherits the install-wide
  // setting. Preserve an explicitly supplied (possibly empty) map so create
  // and update have the same override contract.
  if (isPlainObject(appData.featureOverrides)) {
    app.featureOverrides = appData.featureOverrides;
  }

  data.apps[id] = app;
  await saveApps(data);

  // Return with id injected
  return { id, ...app };
}

/**
 * Update an existing app
 */
export function updateApp(id, updates) {
  return withAppsWrite(() => updateAppUnlocked(id, updates));
}

async function updateAppUnlocked(id, updates) {
  const data = await loadApps();

  if (!data.apps[id]) {
    return null;
  }

  // Remove id and uiUrl from updates if present (id is key, uiUrl is derived)
  const { id: _id, uiUrl: _uiUrl, ...cleanUpdates } = updates;
  // Feature overrides are a partial map: changing one app feature must not
  // erase the other per-app choices that are already persisted.
  const featureOverrides = isPlainObject(cleanUpdates.featureOverrides)
    ? {
      ...(isPlainObject(data.apps[id].featureOverrides) ? data.apps[id].featureOverrides : {}),
      ...cleanUpdates.featureOverrides,
    }
    : null;

  const app = {
    ...data.apps[id],
    ...cleanUpdates,
    ...(featureOverrides ? { featureOverrides } : {}),
    createdAt: data.apps[id].createdAt, // Preserve creation date
    updatedAt: new Date().toISOString()
  };

  data.apps[id] = app;
  await saveApps(data);

  // Return with id injected
  return { id, ...app };
}

/**
 * Remove an app from PortOS's registry (the repository on disk is untouched).
 * The PortOS baseline app cannot be removed.
 */
export function deleteApp(id) {
  return withAppsWrite(() => deleteAppUnlocked(id));
}

async function deleteAppUnlocked(id) {
  if (id === PORTOS_APP_ID) return false;

  const data = await loadApps();

  if (!data.apps[id]) {
    return false;
  }

  delete data.apps[id];
  await saveApps(data);
  console.log(`🗑️ Removed app ${id} from registry`);

  return true;
}

/**
 * Archive an app (soft-delete that excludes from COS tasks).
 * PortOS baseline app cannot be archived.
 */
export async function archiveApp(id) {
  if (id === PORTOS_APP_ID) return null;
  return updateApp(id, { archived: true });
}

/**
 * Unarchive an app (restore to active status)
 */
export async function unarchiveApp(id) {
  return updateApp(id, { archived: false });
}

/**
 * Migrate one app in `data` from the legacy disabledTaskTypes array to a
 * taskTypeOverrides object, in place. Returns true when it changed anything.
 * Operates on the caller's `data` so it never depends on loadApps() returning
 * the same cached object.
 */
function migrateTaskTypeOverridesInData(data, id) {
  const app = data?.apps?.[id];
  if (!app?.disabledTaskTypes || app.taskTypeOverrides) return false;
  const overrides = {};
  for (const taskType of app.disabledTaskTypes) {
    overrides[taskType] = { enabled: false };
  }
  app.taskTypeOverrides = overrides;
  delete app.disabledTaskTypes;
  console.log(`📋 Migrated ${id} from disabledTaskTypes to taskTypeOverrides`);
  return true;
}

/**
 * Persist the legacy → taskTypeOverrides migration for one app. Writes to disk
 * when it migrated, so it only runs once per app.
 */
function migrateTaskTypeOverrides(id) {
  return withAppsWrite(async () => {
    const data = await loadApps();
    if (migrateTaskTypeOverridesInData(data, id)) await saveApps(data);
  });
}

/**
 * Start a task-type override commit for one app: migrate the legacy field,
 * let `apply(overrides)` mutate the (possibly empty) overrides map, then clear
 * the legacy field and stamp updatedAt. Mutates `data` in place; the caller
 * saves via saveAndAnnounceTaskTypes. Every override write path goes through
 * here so none can skip the migration.
 */
async function commitTaskTypeOverrides(data, id, apply) {
  migrateTaskTypeOverridesInData(data, id);
  const appRecord = data.apps[id];
  const overrides = appRecord.taskTypeOverrides || {};
  await apply(overrides, appRecord);
  appRecord.taskTypeOverrides = overrides;
  delete appRecord.disabledTaskTypes; // Remove legacy field
  appRecord.updatedAt = new Date().toISOString();
  return appRecord;
}

async function saveAndAnnounceTaskTypes(data) {
  await saveApps(data);
  appsEvents.emit('changed', { action: 'update-task-types', timestamp: Date.now() });
}

/**
 * Resolve an app's effective work tracker (the single source its `claim-work`
 * task ships from). Returns `{ configured, resolved, host, forge, source }`;
 * see resolveAppWorkTracker. Returns null when the app id is unknown.
 */
export async function getAppWorkTracker(id) {
  const app = await getAppById(id);
  if (!app) return null;
  return resolveAppWorkTracker(app);
}

/**
 * Get an app's effective Layered Intelligence config (the loop's per-app
 * settings). Merges the stored `layeredIntelligence` over the defaults so a
 * partial/absent config still yields a complete, safe config. PortOS gets the
 * meta/self scopes. Returns null when the app id is unknown.
 *
 * `isPortos` is passed to the merge so a missing config picks up the right
 * default scopes without a per-app seed write — an install adopts the baseline
 * the first time the loop reads it.
 */
export async function getAppLayeredIntelligenceConfig(id) {
  const app = await getAppById(id);
  if (!app) return null;
  const { getEffectiveConfig } = await import('./layeredIntelligence.js');
  return getEffectiveConfig({ ...app, isPortos: id === PORTOS_APP_ID });
}

/**
 * Update an app's Layered Intelligence config. Shallow-merges `updates` over the
 * *stored* config only (with `sources` merged one level deep) so a partial PATCH
 * doesn't wipe untouched fields. We deliberately merge over the raw stored value,
 * NOT the effective (defaults-filled) config — persisting the full default set to
 * disk would freeze this install against future default changes (the config
 * accessor's "adopt baseline on read" forward-compat property). Untouched fields
 * stay absent and keep resolving to the shipped default via getEffectiveConfig.
 * Returns the updated app, or null if unknown.
 */
export function updateAppLayeredIntelligence(id, updates = {}) {
  return withAppsWrite(() => updateAppLayeredIntelligenceUnlocked(id, updates));
}

async function updateAppLayeredIntelligenceUnlocked(id, updates) {
  const app = await getAppById(id);
  if (!app) return null;
  const stored = (app.layeredIntelligence && typeof app.layeredIntelligence === 'object' && !Array.isArray(app.layeredIntelligence))
    ? app.layeredIntelligence
    : {};
  const merged = { ...stored, ...updates };
  if (updates.sources && typeof updates.sources === 'object') {
    merged.sources = { ...(stored.sources && typeof stored.sources === 'object' ? stored.sources : {}), ...updates.sources };
  }
  if (updates.handoff && typeof updates.handoff === 'object') {
    merged.handoff = { ...(stored.handoff && typeof stored.handoff === 'object' ? stored.handoff : {}), ...updates.handoff };
  }
  return updateAppUnlocked(id, { layeredIntelligence: merged });
}

/**
 * Get task type overrides for an app. NOTE: not a pure read — it first migrates
 * a legacy `disabledTaskTypes` array to `taskTypeOverrides`, which writes to disk.
 */
export async function getAppTaskTypeOverrides(id) {
  await migrateTaskTypeOverrides(id);
  const app = await getAppById(id);
  if (!app) return {};
  return app.taskTypeOverrides || {};
}

/**
 * Check if a task type is enabled for a specific app
 */
export async function isTaskTypeEnabledForApp(id, taskType) {
  const overrides = await getAppTaskTypeOverrides(id);
  // No override means disabled — new task types must be explicitly enabled per app
  return overrides[taskType]?.enabled === true;
}

/**
 * Get per-app interval for a task type (null = inherit global)
 */
export async function getAppTaskTypeInterval(appId, taskType) {
  const overrides = await getAppTaskTypeOverrides(appId);
  return overrides[taskType]?.interval || null;
}

/**
 * Get a per-app numeric intervalMs override for a task type (null = none). Used
 * by handler-backed tasks (e.g. layered-intelligence) whose per-app cadence can
 * be sub-daily — the string `interval` enum ('daily'/'weekly'/…) can't express
 * that, so those override entries also carry a numeric `intervalMs` that the
 * scheduler's CUSTOM branch honors. Returns null for a missing/invalid value.
 */
export async function getAppTaskTypeIntervalMs(appId, taskType) {
  const overrides = await getAppTaskTypeOverrides(appId);
  const ms = overrides[taskType]?.intervalMs;
  return typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms : null;
}

/**
 * Merge one override patch into an app's stored overrides, in place.
 *
 * Extracted so a single-type edit and a whole-plan write (the Quality tab's
 * schedule form rewrites ~26 types at once) apply IDENTICAL field semantics —
 * the alternative was a second copy of the absent-vs-null ladder below, which
 * is exactly where "cleared back to inherit" and "left alone" drift apart.
 * Returns nothing; callers clear watcher state separately via
 * resetWatchersIfDisabled.
 */
function mergeTaskTypeOverride(overrides, taskType, { enabled, interval, intervalMs, providerId, model, taskMetadata } = {}) {
  const updated = { ...(overrides[taskType] || {}) };
  if (typeof enabled === 'boolean') updated.enabled = enabled;
  if (interval !== undefined) updated.interval = interval;
  // intervalMs / providerId / model are the per-app scheduling fields for
  // handler-backed tasks (layered-intelligence, option A). `null` clears the
  // stored value (back to "inherit / use default").
  if (intervalMs !== undefined) {
    if (intervalMs === null) delete updated.intervalMs;
    else updated.intervalMs = intervalMs;
  }
  if (providerId !== undefined) {
    if (providerId === null || providerId === '') delete updated.providerId;
    else updated.providerId = providerId;
  }
  if (model !== undefined) {
    if (model === null || model === '') delete updated.model;
    else updated.model = model;
  }
  if (taskMetadata !== undefined) {
    const sanitized = sanitizeTaskMetadata(taskMetadata);
    if (!sanitized) {
      delete updated.taskMetadata;
    } else {
      updated.taskMetadata = sanitized;
    }
  }

  // Remove entry when every field is inherit (enabled undefined, no interval, no
  // intervalMs/provider/model, no metadata) — an empty override is just noise.
  if (updated.enabled === undefined && !updated.interval && updated.intervalMs === undefined &&
      updated.providerId === undefined && updated.model === undefined && !updated.taskMetadata) {
    delete overrides[taskType];
  } else {
    overrides[taskType] = updated;
  }
}

/**
 * Disabling pr-watcher/issue-watcher clears the high-water mark AND the
 * execution cooldown so a later re-enable baselines promptly (like first
 * enable) instead of dispatching the backlog opened while it was off. See
 * prWatcher.js / cosTaskGenerator.js.
 */
async function resetWatchersIfDisabled(appRecord, id, taskType, patch) {
  // Only an explicit `enabled: false` is a disable; undefined (a non-toggling
  // patch) and true must leave watcher state alone.
  if (patch?.enabled !== false) return;
  if (taskType === 'pr-watcher') {
    delete appRecord.prWatcherState;
    await resetWatcherCooldown('pr-watcher', id);
  }
  if (taskType === 'issue-watcher') {
    delete appRecord.issueWatcherState;
    await resetWatcherCooldown('issue-watcher', id);
  }
}

/**
 * Update a task type override for a specific app (enable/disable + optional interval)
 */
export async function updateAppTaskTypeOverride(id, taskType, patch = {}) {
  return updateAppTaskTypeOverrides(id, { [taskType]: patch });
}

/**
 * Apply several task-type override patches to one app in a single write.
 *
 * `patches` maps task type → the same patch object `updateAppTaskTypeOverride`
 * takes. One load/save for the whole set: the Quality schedule form touches
 * every audit type at once, and doing that as ~26 sequential read-modify-writes
 * of `apps.json` is both slow and a window in which a partial plan is live.
 *
 * @param {string} id - App id
 * @param {Record<string, object>} patches - Task type → override patch
 * @returns {Promise<object|null>} The updated app record, or null when unknown
 */
export function updateAppTaskTypeOverrides(id, patches = {}) {
  return withAppsWrite(async () => {
    const data = await loadApps();
    if (!data.apps[id]) return null;

    const appRecord = await commitTaskTypeOverrides(data, id, async (overrides, record) => {
      for (const [taskType, patch] of Object.entries(patches)) {
        mergeTaskTypeOverride(overrides, taskType, patch);
        await resetWatchersIfDisabled(record, id, taskType, patch);
      }
    });
    await saveAndAnnounceTaskTypes(data);

    return { id, ...appRecord };
  });
}

/**
 * Reset the schedule execution cooldown for an app's pr-watcher so a re-enable
 * baselines on the next tick instead of waiting out the prior 30-min custom
 * interval — otherwise PRs opened in that delayed window slip past the firstRun
 * baseline. Dynamic import avoids a static apps↔taskSchedule cycle (taskSchedule
 * already imports this module). Best-effort: a missing history is a no-op and a
 * storage failure must not block the primary app-disable write, but it is logged
 * with app context instead of disappearing.
 */
async function resetWatcherCooldown(taskType, appId) {
  try {
    const { resetExecutionHistory } = await import('./taskSchedule.js');
    const result = await resetExecutionHistory(taskType, appId);
    if (result?.error && result.error !== 'No execution history found') {
      console.error(`❌ Failed to reset ${taskType} cooldown for app ${appId}: ${result.error}`);
    }
    return result;
  } catch (err) {
    console.error(`❌ Failed to reset ${taskType} cooldown for app ${appId}: ${err.message}`);
    return { error: err.message };
  }
}

/**
 * Clear the pr-watcher high-water mark on every app. Called when pr-watcher is
 * disabled GLOBALLY (CoS → Schedule), the counterpart to the per-app disable
 * clears in updateAppTaskTypeOverride/bulk/toggle-all — so a later global
 * re-enable baselines silently instead of dispatching the backlog of PRs
 * opened while it was paused. See prWatcher.js.
 */
export function clearAllPrWatcherState() {
  return withAppsWrite(async () => {
    const data = await loadApps();
    let changed = false;
    for (const app of Object.values(data.apps)) {
      if (app.prWatcherState) {
        delete app.prWatcherState;
        changed = true;
      }
    }
    if (changed) await saveApps(data);
    return { changed };
  });
}

/** Clear issue-watcher cursors/pending approvals on global disable. */
export function clearAllIssueWatcherState() {
  return withAppsWrite(async () => {
    const data = await loadApps();
    let changed = false;
    for (const app of Object.values(data.apps)) {
      if (app.issueWatcherState) {
        delete app.issueWatcherState;
        changed = true;
      }
    }
    if (changed) await saveApps(data);
    return { changed };
  });
}

/**
 * Bulk update a task type override for all active (non-archived) apps
 */
export function bulkUpdateAppTaskTypeOverride(taskType, { enabled } = {}) {
  return withAppsWrite(async () => {
    const data = await loadApps();
    const activeIds = Object.entries(data.apps)
      .filter(([, app]) => !app.archived)
      .map(([id]) => id);

    for (const id of activeIds) {
      await commitTaskTypeOverrides(data, id, async (overrides, record) => {
        mergeTaskTypeOverride(overrides, taskType, { enabled });
        await resetWatchersIfDisabled(record, id, taskType, { enabled });
      });
    }

    await saveAndAnnounceTaskTypes(data);

    return { count: activeIds.length };
  });
}

/**
 * Toggle all task types for a single app to enabled or disabled
 */
export function toggleAllAppTaskTypes(id, enabled) {
  return withAppsWrite(async () => {
    const data = await loadApps();
    if (!data.apps[id]) return null;

    const appRecord = await commitTaskTypeOverrides(data, id, async (overrides, record) => {
      for (const taskType of SELF_IMPROVEMENT_TASK_TYPES) {
        const existing = overrides[taskType] || {};
        overrides[taskType] = { ...existing, enabled };
      }
      // Disabling everything disables the watchers too — same reset as any other
      // path that moves their gate, so a later re-enable baselines promptly.
      for (const watcher of ['pr-watcher', 'issue-watcher']) {
        await resetWatchersIfDisabled(record, id, watcher, { enabled });
      }
    });
    await saveAndAnnounceTaskTypes(data);

    return { id, ...appRecord };
  });
}

/**
 * Reserved ports across every app — top-level uiPort/devUiPort/apiPort/tlsPort
 * plus every value in each process's `ports` map. Walking processes[] is what
 * lets the scaffolder avoid colliding with non-public ports (engine IPC, CDP)
 * that have no top-level field of their own.
 */
export async function getReservedPorts() {
  const apps = await getAllApps();
  const ports = new Set();

  const addPort = (p) => {
    let n = null;
    if (typeof p === 'number' && Number.isInteger(p)) n = p;
    // Strict /^\d+$/ rather than parseInt — '5565abc' should not coerce to 5565.
    else if (typeof p === 'string' && /^\d+$/.test(p)) n = Number(p);
    if (n !== null && n >= 1 && n <= 65535) ports.add(n);
  };

  for (const app of apps) {
    addPort(app.uiPort);
    addPort(app.devUiPort);
    addPort(app.apiPort);
    addPort(app.tlsPort);
    if (Array.isArray(app.processes)) {
      for (const proc of app.processes) {
        if (proc?.port) addPort(proc.port);
        if (proc?.ports && typeof proc.ports === 'object') {
          for (const value of Object.values(proc.ports)) addPort(value);
        }
      }
    }
  }

  // Also reserve PortOS ports
  addPort(PORTS.API);
  addPort(PORTS.UI);

  return Array.from(ports).sort((a, b) => a - b);
}