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
/**
* Stale `.agent-done-*` sentinel sweep.
*
* A run that reaches an outcome deletes its own sentinel, through
* `removeCompletionSentinel` in agentCompletionCleanup.js: the step list every
* live completion path shares (TUI spawner, direct-CLI spawner, runner event),
* plus the two recovery paths that retire a run without reaching it — the
* post-restart completion in agentLifecycle.js and the orphan sweep in
* agentManagement.js, which is where a hard kill (`pm2 restart`, SIGKILL,
* reboot) lands. So in the happy case nothing is left behind. What still can be:
*
* - a run whose record the orphan sweep never reaps (no durable record, or a
* workspace the record does not name);
* - a host shutdown ABANDONS the run rather than finalizing it (#3202), so no
* completion cleanup runs — the abandon gate only fires when the run wrote
* NO sentinel, but a race can still strand one;
* - a completion whose sentinel removal failed (an unreadable agent record,
* a transient I/O error);
* - the bare unscoped `.agent-done`, which names no run, so no completion
* path will ever claim it.
*
* Worktree-less agents share a real checkout — the PortOS repo, or a managed
* app's own repo — so for them a skipped cleanup leaves an untracked file in the
* USER'S repository, forever, one per dead run. That is what this sweeps.
*
* Safety is the whole design: a sentinel is deleted only when its run is
* provably not live (its agent id is absent from `protectedAgentIds`) AND the
* file is older than `STALE_SENTINEL_MIN_AGE_MS`. The age floor covers the
* window where a sentinel exists before its run is registered, and gives the
* bare unscoped `.agent-done` — which names no agent and so can never be
* matched to a live run — its only protection.
*/
import { readdir, stat } from 'fs/promises';
import { join } from 'path';
import { doneSentinelAgentId } from '../lib/agentSentinel.js';
import { execGit } from '../lib/execGit.js';
import { HOUR, rmGuarded } from '../lib/fileUtils.js';
/** How long a sentinel must have sat untouched before it counts as abandoned. */
export const STALE_SENTINEL_MIN_AGE_MS = HOUR;
/**
* Delete abandoned done-sentinels from the given directories.
*
* @param {string[]} dirs - workspace roots to sweep (duplicates are fine).
* @param {Set<string>} protectedAgentIds - agents whose sentinel must survive:
* everything live, paused, or otherwise not finished. Anything else is
* "liveness unknown" and removes nothing — the caller passes a non-Set when it
* could not read the agent state, and sweeping on that list would delete the
* resume signal of every paused and interrupted run.
* @returns {Promise<number>} sentinels removed.
*/
export async function sweepStaleDoneSentinels(dirs, protectedAgentIds) {
if (!(protectedAgentIds instanceof Set)) return 0;
const cutoff = Date.now() - STALE_SENTINEL_MIN_AGE_MS;
let removed = 0;
for (const dir of new Set((dirs || []).filter(d => typeof d === 'string' && d))) {
const entries = await readdir(dir).catch(() => null);
if (!entries) continue;
for (const entry of entries) {
const agentId = doneSentinelAgentId(entry);
if (agentId === null) continue;
if (agentId && protectedAgentIds.has(agentId)) continue;
const target = join(dir, entry);
const info = await stat(target).catch(() => null);
if (!info?.isFile() || info.mtimeMs >= cutoff) continue;
const gone = await rmGuarded(target, { force: true }).then(() => true, (err) => {
console.warn(`⚠️ Failed to remove stale sentinel ${entry}: ${err.message}`);
return false;
});
if (gone) removed++;
}
}
return removed;
}
/**
* Every checkout of the given repos: the repo itself plus its linked worktrees.
* A sentinel stranded in a preserved agent worktree reads as uncommitted work, so
* it blocks that worktree's merged-tree cleanup until something deletes it; the
* sweep above only helps if it is pointed at those directories.
*
* @param {string[]} repoPaths
* @returns {Promise<string[]>} unique checkout paths; an unreadable repo contributes itself only
*/
export async function checkoutDirsOf(repoPaths) {
const dirs = new Set();
for (const repo of new Set((repoPaths || []).filter(p => typeof p === 'string' && p))) {
dirs.add(repo);
const listed = await execGit(['worktree', 'list', '--porcelain'], repo).catch(() => null);
for (const line of (listed?.stdout || '').split(/\r?\n/)) {
if (line.startsWith('worktree ')) dirs.add(line.slice(9));
}
}
return [...dirs];
}