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

5.0 KB
Raw Blame
/**
 * The CoS task STATUS TRANSITION vocabulary (#6620).
 *
 * `writeTaskUpdate` (services/cosTaskStore.js) applies half a dozen lifecycle
 * rules to a task update — clear the blocked/pause metadata, drop a spent resume
 * pointer, retire the retry hold, release the federation claim, stamp or clear
 * the requeue marker, pick the `tasks:changed` action. Each of those used to
 * re-derive "what transition is this?" from the raw `(previousStatus,
 * updates.status)` pair at its own site, spread over 130 lines: the retry-hold
 * clear and the claim release were the IDENTICAL predicate written twice twelve
 * lines apart, and the requeue stamp and the emitted action independently keyed
 * on the same `in_progress → pending` edge 52 lines apart while having to agree.
 *
 * Every one of those sites arrived in a different feature commit, and getting one
 * wrong is not cosmetic: a missed pause-key clear made `resumeAgent` read its own
 * pause as spent and spawn a SECOND agent on a fresh task; a stale claim lease
 * blocks a legitimate retry by this instance or its peer for a full lease window;
 * a stale `existingBranch` silently attaches a fresh perpetual run to a
 * long-merged branch. So the question is asked ONCE, here, and every rule reads
 * the answer off the descriptor rather than re-deriving one.
 *
 * Pure and dependency-free — it answers only "what KIND of transition is this?".
 * Metadata predicates (is this block a pause? is this branch pointer the resume's?)
 * are deliberately NOT here: they read the task's metadata, not its status pair,
 * and belong at the application site.
 */

/**
 * A task is terminal once it is `completed` or `blocked` — the point at which a
 * resume pointer is spent and the federated merge stops advancing it. One
 * definition for `writeTaskUpdate`'s pointer drop, its stale-failure reaper, and
 * `cosTaskMerge`'s release-on-transition, which each carried their own copy.
 */
export const isTerminalTaskStatus = (status) => status === 'completed' || status === 'blocked';

/**
 * Classify one `(previousStatus, nextStatus)` pair.
 *
 * `nextStatus` is the update patch's `status` field AS PASSED — `undefined` (or
 * empty) when the write carries no status at all, which is a meaningful case and
 * not a synonym for "unchanged": a lease-renewal heartbeat passes no status and
 * must release nothing, while an explicit write to the status the task already
 * holds does apply the transition rules for that status. Fields that gate a
 * RELEASE therefore require a status to be present; fields that describe the
 * task's resulting state fall back to `previousStatus`.
 *
 * @param {string|undefined} previousStatus - the task's status before the write
 * @param {string|undefined} nextStatus - `updates.status`, or undefined/'' when absent
 * @returns {{
 *   action: 'unblocked'|'requeued'|'updated',
 *   isRevive: boolean, isRequeue: boolean,
 *   entersInProgress: boolean, leavesInProgress: boolean,
 *   leavesBlocked: boolean, isTerminal: boolean
 * }}
 */
export function resolveTaskStatusTransition(previousStatus, nextStatus) {
  // A falsy `nextStatus` is "no status in this patch": `writeTaskUpdate` spreads
  // the status onto the task with the same truthiness test, so '' never lands.
  const setsStatus = Boolean(nextStatus);
  // The status the task will hold after the write.
  const resultingStatus = setsStatus ? nextStatus : previousStatus;

  // A revive: the task was parked and is spawnable again. Drives the `unblocked`
  // action, which is what re-runs cos.init's dequeue (#2614).
  const isRevive = resultingStatus === 'pending' && (previousStatus === 'blocked' || previousStatus === 'completed');
  // The one BACKWARD step in the lifecycle (#3376) — the orphan sweep and the
  // retry-hold release both perform it, and the federated merge has to tell it
  // apart from an ordinary edit landing on a peer's stale `pending` copy.
  const isRequeue = resultingStatus === 'pending' && previousStatus === 'in_progress';

  return {
    action: isRevive ? 'unblocked' : (isRequeue ? 'requeued' : 'updated'),
    isRevive,
    isRequeue,
    // A fresh spawn. Retires the requeue stamp: from here on THIS run's
    // `lastSpawnedAt` is what a future requeue must beat.
    entersInProgress: nextStatus === 'in_progress',
    // The write lands a status OTHER than `in_progress` — the edge that retires
    // every in-flight-only marker (the retry hold, the federation claim/lease).
    // False for a patch carrying no status, so a heartbeat releases nothing.
    leavesInProgress: setsStatus && nextStatus !== 'in_progress',
    // Out of `blocked` by any door — a dedupe revive, an autopilot re-dispatch, a
    // cooldown expiry, or a human unblocking it from the task list.
    leavesBlocked: setsStatus && nextStatus !== 'blocked' && previousStatus === 'blocked',
    // Keyed on the PATCH, not the resulting state: re-editing an already-completed
    // task is not a fresh arrival at a terminal status and must not re-run the
    // one-shot terminal cleanups.
    isTerminal: isTerminalTaskStatus(nextStatus)
  };
}