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
import { assertDatabaseAdmission } from '../lib/databaseMaintenanceJournal.js';
/**
* Agent lifecycle guard primitives.
*
* Two tiny, dependency-injected control-flow helpers carved out of the
* ~470-LOC `spawnAgentForTask` and `handleAgentCompletion` orchestrators
* (agentLifecycle.js) so the concurrency contracts they enforce are unit-
* testable against the REAL code path instead of a hand-copied replica
* (issue #2548). Spawn admission also consults the persistent database fence
* before registering work; the other guards use the supplied predicates.
*/
/**
* Sentinel returned by `withSpawnDedupGuard` when the guard was already held
* for `taskId` — i.e. a concurrent spawn is already in flight and this call
* must not proceed. A Symbol (not `null`) so the caller can distinguish
* "deduped, do nothing" from a legitimate `null` result of the wrapped work.
*/
export const SPAWN_DEDUP_SKIP = Symbol('spawn-dedup-skip');
/**
* Run `fn` under a per-task spawn dedup guard.
*
* Contract (the race closed by issue #1563 / the spawningTasks fix):
* 1. If `spawningTasks` already holds `taskId`, return `SPAWN_DEDUP_SKIP`
* without touching the set — a duplicate `task:ready` re-emit is rejected.
* 2. Otherwise acquire the guard SYNCHRONOUSLY (before the first `await`
* inside `fn`), so a second call landing while `fn` is suspended at any
* await sees the guard held and dedups at step 1 rather than spawning a
* second agent for the same task id.
* 3. Release the guard in a `finally` so it outlives the entire wrapped
* body — every early `return`, and any throw, still releases it. Holding
* the guard until `fn` settles (not merely until the task is flipped to
* in_progress) is what prevents the late-delete race where a racer slips
* in between the release and the runner actually accepting the agent.
*
* @param {Set<string>} spawningTasks - the in-process dedup set
* @param {string} taskId
* @param {() => Promise<any>} fn - the guarded spawn work
* @returns {Promise<any|typeof SPAWN_DEDUP_SKIP>}
*/
export async function withSpawnDedupGuard(spawningTasks, taskId, fn) {
assertDatabaseAdmission();
if (spawningTasks.has(taskId)) return SPAWN_DEDUP_SKIP;
spawningTasks.add(taskId);
try {
return await fn();
} finally {
spawningTasks.delete(taskId);
}
}
/**
* Sentinel returned by `withUpdateInProgressGuard` when a PortOS self-update is
* running. A distinct Symbol from `SPAWN_DEDUP_SKIP` so the caller can log the
* right reason — "held for an update" is a temporary, self-clearing hold, not a
* duplicate dispatch — while both share the same "no-op, leave the task queued"
* contract.
*/
export const SPAWN_UPDATE_SKIP = Symbol('spawn-update-skip');
/**
* Run `fn` only when no self-update is in progress.
*
* Contract (the race closed by issue #4124): `/api/update/execute` blocks on
* live CoS agents both before and after acquiring the update lock, but
* `update.sh` then spends multiple seconds in `git pull` / submodule update /
* `npm install` before it reaches `pm2 delete`. An agent that starts inside
* THAT window is severed by the restart — its PTY/child process is a child of
* this server. This guard closes it from the spawn side: while the update flag
* is set, a spawn is a no-op and the task stays queued for after the restart,
* rather than burning a spawn (and its retry budget) on a doomed run.
*
* The predicate is injected rather than imported so this module stays free of
* module state and I/O, and so a test can drive the real guard with a stub.
*
* @param {() => boolean} isUpdateInProgress - synchronous flag reader
* @param {() => Promise<any>} fn - the guarded spawn work
* @returns {Promise<any|typeof SPAWN_UPDATE_SKIP>}
*/
export async function withUpdateInProgressGuard(isUpdateInProgress, fn) {
if (isUpdateInProgress()) return SPAWN_UPDATE_SKIP;
return fn();
}
/**
* Run `fn`, then unconditionally delete `key` from `map` in a `finally`.
*
* The completion-side counterpart to `withSpawnDedupGuard`: a throw from any
* inner step of `handleAgentCompletion` (completeAgent, updateTask,
* processAgentCompletion, finalizeAgent…) must never strand the agent's entry
* in the in-memory `runnerAgents` map — a stale entry grows memory unboundedly
* and can re-trigger/misroute completion if the runner re-emits the event.
* The error still propagates to the caller; the finally only guards the map.
*
* @param {Map<string, any>} map
* @param {string} key
* @param {() => Promise<any>} fn
* @returns {Promise<any>}
*/
export async function withMapEntryCleanup(map, key, fn) {
try {
return await fn();
} finally {
map.delete(key);
}
}