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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* App Activity Tracking Service
*
* Manages per-app cooldowns, review history, and active work tracking.
* Prevents the CoS from working on the same app in a loop.
*/
import { join } from 'path';
import { ensureDir, PATHS, readJSONFile, atomicWrite } from '../lib/fileUtils.js';
const DATA_DIR = PATHS.cos;
const ACTIVITY_FILE = join(DATA_DIR, 'app-activity.json');
const DEFAULT_ACTIVITY = {
apps: {},
global: {
lastIdleReviewAt: null,
totalReviews: 0
}
};
/**
* Load app activity data
*/
export async function loadAppActivity() {
await ensureDir(DATA_DIR);
// Strict (#4115): every writer here is `loadAppActivity → mutate →
// saveAppActivity`, so a swallowed unreadable file writes DEFAULT_ACTIVITY
// over every app's cooldown, active-agent binding and lifetime review stats —
// which also drops every app off cooldown at once, so the CoS immediately
// re-reviews the whole fleet. Throwing skips the cycle and keeps the file.
const loaded = await readJSONFile(ACTIVITY_FILE, null, { strict: true });
// structuredClone, not a spread. `{ ...DEFAULT_ACTIVITY }` is shallow, so the
// returned `apps` and `global` were the SAME objects on every call: on an
// absent file the first `updateAppActivity`/`markIdleReviewStarted` mutated
// the module-level default in place, and every later load inherited that
// app map and its incremented totalReviews. Same "the default must never
// become shared mutable state" family as the strict read above.
const base = structuredClone(DEFAULT_ACTIVITY);
return loaded ? { ...base, ...loaded } : base;
}
/**
* Save app activity data
*/
export async function saveAppActivity(activity) {
await ensureDir(DATA_DIR);
await atomicWrite(ACTIVITY_FILE, activity);
}
/**
* Get activity for a specific app
*/
export async function getAppActivityById(appId) {
const activity = await loadAppActivity();
return activity.apps[appId] || null;
}
/**
* Update activity for a specific app
*/
export async function updateAppActivity(appId, updates) {
const activity = await loadAppActivity();
if (!activity.apps[appId]) {
activity.apps[appId] = {
lastReviewedAt: null,
lastTaskCompletedAt: null,
activeAgentId: null,
cooldownUntil: null,
lastImprovementType: null, // Track last self-improvement analysis type
stats: {
reviewCount: 0,
issuesFound: 0,
issuesFixed: 0
}
};
}
// Merge updates, handling nested stats object
if (updates.stats) {
activity.apps[appId].stats = { ...activity.apps[appId].stats, ...updates.stats };
delete updates.stats;
}
activity.apps[appId] = { ...activity.apps[appId], ...updates };
await saveAppActivity(activity);
return activity.apps[appId];
}
/**
* Start cooldown for an app (called when agent completes work on it)
*/
export async function startAppCooldown(appId, cooldownMs) {
const cooldownUntil = new Date(Date.now() + cooldownMs).toISOString();
return updateAppActivity(appId, {
cooldownUntil,
activeAgentId: null,
lastTaskCompletedAt: new Date().toISOString()
});
}
/**
* Advance an app's review cooldown WITHOUT binding an active agent.
*
* Stamps `lastReviewedAt` (which `isAppActivityOnCooldown` reads) so the app
* isn't re-picked on the very next idle tick — the re-pick-storm guard. This
* runs *before* the per-app task generator, since a no-op poll (task generator
* returns `null`) still has to advance the cooldown. Crucially it does NOT
* touch `activeAgentId`, so a null result can't leave a phantom "in review"
* marker. See `bindAppReviewAgent` for the agent-binding half, called only once
* a task actually exists. These two were previously a single eager
* `markAppReviewStarted` step, which stranded the marker on no-op polls (#978).
*/
export async function markAppReviewCooldown(appId) {
return updateAppActivity(appId, {
lastReviewedAt: new Date().toISOString()
});
}
/**
* Bind an active agent to an app whose review cooldown was already advanced by
* `markAppReviewCooldown`. Call this only after the per-app task generator has
* produced a task — binding before generation is what stranded `activeAgentId`
* on no-op polls (the app read as "in review" until stale-agent cleanup).
*/
export async function bindAppReviewAgent(appId, agentId) {
return updateAppActivity(appId, {
activeAgentId: agentId
});
}
/**
* Synthetic review markers bound by `bindAppReviewAgent` before the real agent
* spawns: `idle-review-<ts>` (idle loop) and `on-demand-<ts>` (on-demand loop).
* A *real* agent marker is `agent-<id>` and must never be cleared by the
* spawn-failure release below.
*/
const SYNTHETIC_REVIEW_AGENT_RE = /^(idle-review|on-demand)-/;
/**
* Release a *synthetic* app-review marker stranded by a spawn that failed before
* completion.
*
* `bindAppReviewAgent` writes a synthetic `activeAgentId` (`idle-review-*` /
* `on-demand-*`) the instant a review task is produced — but `spawnAgentForTask`
* has several `return null` failure paths *after* that bind (provider resolution
* fails, workspace prep deferred/blocked, the in_progress `updateTask` fails,
* max-spawns block). On any of those, no agent runs to completion, so
* `processAgentCompletion` never clears the marker via `markAppReviewCompleted` +
* `startAppCooldown` — the app reads "in review" until the next daemon restart's
* `clearStaleActiveAgents` sweep (the synthetic id is never in the live
* `agent-*` set). This is the same failure *class* as #978, one step later in the
* lifecycle. See issue #989.
*
* Releasing only clears `activeAgentId`: it does NOT bump `reviewCount` /
* `issuesFound` (no review actually ran) and it leaves the cooldown that
* `markAppReviewCooldown` already advanced intact — so the app is re-picked after
* its normal cooldown window, not immediately. The synthetic-id guard makes this
* safe to call on any failing task that carries `metadata.app`: a real `agent-*`
* marker (a different live agent) is left untouched, and a no-marker app is a
* no-op.
*/
export async function releaseAppReviewMarker(appId) {
if (!appId) return null;
const activity = await loadAppActivity();
const app = activity.apps?.[appId];
if (!SYNTHETIC_REVIEW_AGENT_RE.test(app?.activeAgentId || '')) return null;
return updateAppActivity(appId, { activeAgentId: null });
}
/**
* Mark an app review as completed
*/
export async function markAppReviewCompleted(appId, issuesFound = 0, issuesFixed = 0) {
const activity = await getAppActivityById(appId) || { stats: {} };
return updateAppActivity(appId, {
activeAgentId: null,
stats: {
reviewCount: (activity.stats?.reviewCount || 0) + 1,
issuesFound: (activity.stats?.issuesFound || 0) + issuesFound,
issuesFixed: (activity.stats?.issuesFixed || 0) + issuesFixed
}
});
}
/**
* Clear cooldown for an app (manual override)
*/
export async function clearAppCooldown(appId) {
return updateAppActivity(appId, { cooldownUntil: null });
}
/**
* Clear `activeAgentId` entries that reference agents no longer in the live agent set.
*
* Called at daemon startup. Without this, an idle-review agent that died across a
* server restart (or a Feb-vintage state file that never finished cleanly) leaves a
* stale activeAgentId pointing at a dead PID. `isAppOnCooldown` treats any non-null
* activeAgentId as "still working" → the app is stuck on cooldown forever, and
* `queueEligibleImprovementTasks` silently skips it every cycle.
*
* @param {Set<string>|Array<string>} liveAgentIds - The currently-running agent IDs from cosState
* @returns {Promise<{cleared: string[]}>} - List of app IDs whose activeAgentId was cleared
*/
export async function clearStaleActiveAgents(liveAgentIds) {
const live = liveAgentIds instanceof Set ? liveAgentIds : new Set(liveAgentIds || []);
const activity = await loadAppActivity();
const cleared = [];
for (const [appId, app] of Object.entries(activity.apps || {})) {
if (app.activeAgentId && !live.has(app.activeAgentId)) {
cleared.push(appId);
app.activeAgentId = null;
}
}
if (cleared.length > 0) {
await saveAppActivity(activity);
}
return { cleared };
}
/**
* Pure cooldown predicate — takes a per-app activity record (already
* extracted from an `apps` map) plus the cooldown window and returns
* true/false without any disk I/O. The async `isAppOnCooldown` below is
* a thin wrapper that loads the activity snapshot from disk and delegates
* here. Loops that iterate over many apps in one tick (e.g.
* `queueEligibleImprovementTasks` in cos.js) should load
* `loadAppActivity()` *once* before the loop and call this predicate per
* app, instead of calling `isAppOnCooldown` per app (which re-reads
* the same JSON file N times). See cos.js for the canonical usage.
*/
export function isAppActivityOnCooldown(appActivity, cooldownMs) {
if (!appActivity) return false;
const now = Date.now();
// Check explicit cooldown
if (appActivity.cooldownUntil) {
const cooldownTime = new Date(appActivity.cooldownUntil).getTime();
if (cooldownTime > now) {
return true;
}
}
// Check last activity time against cooldown period
const lastActivity = Math.max(
appActivity.lastReviewedAt ? new Date(appActivity.lastReviewedAt).getTime() : 0,
appActivity.lastTaskCompletedAt ? new Date(appActivity.lastTaskCompletedAt).getTime() : 0
);
if (lastActivity && (now - lastActivity) < cooldownMs) {
return true;
}
// Check if already has an active agent
if (appActivity.activeAgentId) {
return true;
}
return false;
}
/**
* Check if an app is on cooldown by `appId`. Loads the activity snapshot
* from disk and delegates to the pure predicate. For loops over many
* apps, prefer hoisting `loadAppActivity()` once and calling
* `isAppActivityOnCooldown(activity.apps?.[appId], cooldownMs)` directly.
*/
export async function isAppOnCooldown(appId, cooldownMs) {
const activity = await loadAppActivity();
// Optional chain — a hand-edited / corrupted activity.json could lose
// the `apps` field, and `null.appId` would throw before the predicate's
// own falsy guard ran.
return isAppActivityOnCooldown(activity.apps?.[appId], cooldownMs);
}
/**
* Get the next app eligible for review (not on cooldown, oldest review first)
*/
export async function getNextAppForReview(apps, cooldownMs) {
const activity = await loadAppActivity();
const now = Date.now();
// Build list of eligible apps with their last review time
const eligible = [];
for (const app of apps) {
const appActivity = activity.apps[app.id];
// Skip if on cooldown
if (appActivity) {
// Check explicit cooldown
if (appActivity.cooldownUntil && new Date(appActivity.cooldownUntil).getTime() > now) {
continue;
}
// Check last activity cooldown
const lastActivity = Math.max(
appActivity.lastReviewedAt ? new Date(appActivity.lastReviewedAt).getTime() : 0,
appActivity.lastTaskCompletedAt ? new Date(appActivity.lastTaskCompletedAt).getTime() : 0
);
if (lastActivity && (now - lastActivity) < cooldownMs) {
continue;
}
// Check active agent
if (appActivity.activeAgentId) {
continue;
}
}
// App is eligible
const lastReview = appActivity?.lastReviewedAt
? new Date(appActivity.lastReviewedAt).getTime()
: 0;
eligible.push({
app,
lastReview,
timeSinceReview: now - lastReview
});
}
// Sort by longest time since review (oldest first)
eligible.sort((a, b) => b.timeSinceReview - a.timeSinceReview);
return eligible[0]?.app || null;
}
/**
* Update global idle review timestamp
*/
export async function markIdleReviewStarted() {
const activity = await loadAppActivity();
activity.global.lastIdleReviewAt = new Date().toISOString();
activity.global.totalReviews = (activity.global.totalReviews || 0) + 1;
await saveAppActivity(activity);
return activity.global;
}
/**
* Get time until next eligible app is off cooldown
*/
export async function getNextCooldownExpiry(apps, cooldownMs) {
const activity = await loadAppActivity();
const now = Date.now();
let nextExpiry = null;
for (const app of apps) {
const appActivity = activity.apps[app.id];
if (!appActivity) continue;
// Check explicit cooldown
if (appActivity.cooldownUntil) {
const expiryTime = new Date(appActivity.cooldownUntil).getTime();
if (expiryTime > now && (!nextExpiry || expiryTime < nextExpiry)) {
nextExpiry = expiryTime;
}
}
// Check activity-based cooldown
const lastActivity = Math.max(
appActivity.lastReviewedAt ? new Date(appActivity.lastReviewedAt).getTime() : 0,
appActivity.lastTaskCompletedAt ? new Date(appActivity.lastTaskCompletedAt).getTime() : 0
);
if (lastActivity) {
const expiryTime = lastActivity + cooldownMs;
if (expiryTime > now && (!nextExpiry || expiryTime < nextExpiry)) {
nextExpiry = expiryTime;
}
}
}
return nextExpiry ? nextExpiry - now : null;
}