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
/**
* Tests for cos.js — focused on the two hot-spot internals that gate every
* agent spawn but have no full-function test sibling:
*
* 1. `evaluateTasks` priority ordering — Priority 0 (on-demand) > Priority 1
* (user) > Priority 2 (auto-approved system) > Priority 3.6 (feature agents) >
* Priority 4 (idle review).
* Within a priority bucket tasks are taken in the order they appear in
* TASKS.md (the parser sorts nothing for the pending slice — file order is
* the tie-breaker).
*
* 2. `dequeueNextTask` capacity guards — global `maxConcurrentAgents` cap
* and per-project `maxConcurrentAgentsPerProject` cap. The function must
* short-circuit when no slots are available and must skip tasks whose
* project bucket is already saturated even if the global slot count
* permits one more spawn.
*
* `evaluateTasks` and `dequeueNextTask` are 250+ LOC each and pull in 40+
* imported helpers (loadState, getAllTasks, addTask, getActiveApps,
* taskSchedule, etc.). Mocking the full graph would be a brittle
* test of mocks rather than logic, so we exercise the *real* capacity/gate
* exports the scheduler uses — `createDequeueCapacity`,
* `isIdleTierEligible` from cosDequeue.js (issue #2530) — through a thin drain
* harness. Only the tier-ordering loop glue is local; every capacity and
* eligibility decision routes through the same helpers `dequeueNextTask` calls,
* so a guard-logic regression fails here instead of only in production.
*
* A source-level regression check at the bottom asserts the priority order
* and the capacity-guard early return are still in place in `cos.js`, so a
* future refactor that reorders priorities or removes the
* `availableSlots <= 0` short-circuit flips a clear red flag.
*/
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { isPerpetualRefillCandidate, perpetualRefillPlan, resetOrphanedTasks } from './cos.js';
import { firstLine } from './cosTaskStore.js';
import { canQueueImprovementTasks, DEFAULT_STATE } from './cosState.js';
import { createDequeueCapacity, countRunningAgentsByLocalEndpoint, isIdleTierEligible, isUserTaskRunnableUnattended } from './cosDequeue.js';
import { generateTasksMarkdown, parseTasksMarkdown } from '../lib/taskParser.js';
import {
createLocalEndpointSlotContext,
cloudSwarmThreadCapacity,
localEndpointOfProvider,
providerBaseUrl,
reserveLocalEndpointSpawn,
acquireLocalEndpointProviderSlot,
pendingLocalEndpointSpawns,
__resetLocalEndpointSpawnReservations,
readEndpointCapacity,
} from './cosLocalEndpointSlots.js';
import { PENDING_MERGE_SWEEP_INTERVAL_MS, MAX_PENDING_MERGE_TICKS } from './prWatcher.js';
import { PERSISTENT_MIND_SCHEMA_VERSION } from '../lib/persistentMind.js';
const __dirname = dirname(fileURLToPath(import.meta.url));
const COS_SRC = readFileSync(join(__dirname, 'cos.js'), 'utf-8');
const SPAWN_WINDOW_SRC = readFileSync(join(__dirname, '..', 'lib', 'cosSpawnWindow.js'), 'utf-8');
// The task-generation engine (evaluateTasks + the improvement/idle generators
// + applyPlanIdMetadata) was extracted to cosTaskGenerator.js (issue-741). The
// spawn-side scheduler (dequeueNextTask, tryImmediateSpawn, the tasks:changed
// listener) stays in cos.js. Source-level guards below read each invariant from
// whichever module now owns it.
const GEN_SRC = readFileSync(join(__dirname, 'cosTaskGenerator.js'), 'utf-8');
const PRESTEP_SRC = readFileSync(join(__dirname, 'cosTaskPreStepBlocks.js'), 'utf-8');
const SCHED_SRC = readFileSync(join(__dirname, 'cosJobScheduler.js'), 'utf-8');
// The pure capacity tracker + idle tier-eligibility predicate that
// dequeueNextTask (and these tests) call live in cosDequeue.js (issue #2530).
const DEQ_SRC = readFileSync(join(__dirname, 'cosDequeue.js'), 'utf-8');
// ─── Real capacity/gate exports driven by a thin harness ───────────────────
/**
* Build the REAL per-cycle capacity tracker (`createDequeueCapacity` from
* cosDequeue.js) from a fixture state — the same tracker `dequeueNextTask`
* constructs. Exposes `availableSlots`, `perProjectLimit`, `spawnProjectCounts`,
* and the `canSpawn`/`trackSpawn` closure the scheduler enforces. `spawned` is a
* live numeric getter (not an array), so the drain harness below keeps its own
* `admitted` list of the task objects it let through.
*/
function makeCapacityTracker(state, agentsByProject = {}) {
return createDequeueCapacity(state, { agentsByProject });
}
/**
* Thin drain harness modelling the priority-bucket loop in `dequeueNextTask`.
* The four buckets are drained in this exact order:
*
* 0. onDemand — explicit user requests (highest, bypasses pause)
* 1. user — user-authored pending tasks
* 2. autoSystem — auto-approved system / improvement tasks
* 3. idle — generated idle-review task (only when eligible)
*
* Only the ordering/glue is local: every capacity decision routes through the
* real `capacity.canSpawn`/`trackSpawn`, and the idle fence uses the real
* `isIdleTierEligible` predicate the scheduler calls. Within a bucket,
* iteration order is the source array order (file order for parsed TASKS.md;
* arrival order for the on-demand queue) — the loop does NOT re-sort by
* priorityValue.
*
* `isIdleTierEligible` requires `spawned === 0`, so ANY earlier spawn
* (autoSystem) suppresses idle on the same cycle. Tests run with auto-run in
* `execute` and idle review enabled so the tier predicate reduces to the
* pending-user + spawned gates.
*/
function priorityDequeue(buckets, capacity, { paused = false } = {}) {
const admitted = [];
const hasPendingUserTasks = (buckets.user || []).length > 0;
const drain = (bucketName) => {
// Priorities 0 and 3 opt OUT of the local-endpoint cap, exactly as
// production does: a denial there DISCARDS an already-committed task (a
// cleared on-demand request, a bound app-review marker) instead of
// deferring it, so they emit and let the spawner chokepoint hold.
const committed = ['onDemand', 'idle'].includes(bucketName);
for (const task of buckets[bucketName] || []) {
if (capacity.spawned >= capacity.availableSlots) return;
// The user tier withholds a row that says it is not auto-approved (#7300),
// through the same predicate both production engines call.
if (bucketName === 'user' && !isUserTaskRunnableUnattended(task)) continue;
if (!(committed ? capacity.canSpawnCommitted(task) : capacity.canSpawn(task))) continue;
capacity.trackSpawn(task);
admitted.push({ ...task, _bucket: bucketName });
}
};
// Priority 0 (on-demand) drains even when paused.
drain('onDemand');
// Global pause stops every autonomous/scheduled/user tier below.
if (paused) return admitted;
drain('user');
drain('autoSystem');
if (isIdleTierEligible({
spawned: capacity.spawned, hasPendingUserTasks,
idleReviewEnabled: true, autonomyMode: 'execute'
})) drain('idle');
return admitted;
}
// ─── Fixture helpers ───────────────────────────────────────────────────────
function makeState({ maxConcurrentAgents = 3, maxConcurrentAgentsPerProject = null, runningAgents = [] } = {}) {
return {
config: { maxConcurrentAgents, maxConcurrentAgentsPerProject },
agents: Object.fromEntries(runningAgents.map((a, i) => [`agent-${i}`, a])),
};
}
function makeRunningAgent(app = '_self') {
return { status: 'running', metadata: { taskApp: app, app } };
}
const task = (id, priority = 'MEDIUM', { app } = {}) => ({
id,
priority,
status: 'pending',
metadata: app !== undefined ? { app } : {},
});
// ─── evaluateTasks: priority ordering ──────────────────────────────────────
describe('evaluateTasks — priority ordering', () => {
it('drains buckets in order: onDemand > user > autoSystem > idle', () => {
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [task('task-onDemand-1')],
user: [task('task-user-1')],
autoSystem: [task('sys-auto-1')],
// Idle should be SKIPPED here because user bucket is non-empty
// (matches production line 795 `hasPendingUserTasks` gate).
idle: [task('sys-idle-1')],
};
const spawned = priorityDequeue(buckets, capacity);
// Order is: onDemand, user, autoSystem (idle blocked by user-pending gate)
expect(spawned.map(t => t.id)).toEqual([
'task-onDemand-1',
'task-user-1',
'sys-auto-1',
]);
expect(spawned.map(t => t._bucket)).toEqual(['onDemand', 'user', 'autoSystem']);
});
it('when globally paused, only the on-demand bucket drains (manual Run bypasses pause)', () => {
// A global pause stops scheduled/autonomous/user spawning, but an explicit
// user "Run" pushes an on-demand request that must still fire. Mirrors the
// production gate: Priority 0 (on-demand) is processed, then `if (paused) return;`.
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [task('task-onDemand-1')],
user: [task('task-user-1')],
autoSystem: [task('sys-auto-1')],
idle: [task('sys-idle-1')],
};
const spawned = priorityDequeue(buckets, capacity, { paused: true });
// Only the on-demand request spawns; everything else stays paused.
expect(spawned.map(t => t.id)).toEqual(['task-onDemand-1']);
expect(spawned.map(t => t._bucket)).toEqual(['onDemand']);
});
it('idle fires only when nothing else has spawned (spawned === 0 gate, cos.js:2480)', () => {
// When autoSystem is empty AND no user-pending, idle
// gets to run. This is the only path through which the idle bucket
// actually drains in production.
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [],
autoSystem: [],
idle: [task('sys-idle-1')],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t._bucket)).toEqual(['idle']);
});
it('idle suppressed when only autoSystem spawned (no user tasks)', () => {
// Pin the asymmetry: even a SINGLE autoSystem spawn is enough to suppress
// idle on the same cycle. This is the production behavior at cos.js:862
// (`tasksToSpawn.length === 0`) and cos.js:2480 (`spawned === 0`).
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [],
autoSystem: [task('sys-auto-1')],
idle: [task('sys-idle-1')],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t._bucket)).toEqual(['autoSystem']);
});
it('within a single bucket, file/arrival order wins (no in-bucket priority re-sort)', () => {
// The dequeue loop does NOT sort by priorityValue at this layer. The
// parsed-tasks slice preserves file order, so a HIGH task placed AFTER
// a LOW task in TASKS.md is taken AFTER the LOW task. This is the
// documented contract: callers using `addTask({ position: 'top' })` are
// expected to control ordering at write time.
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [
task('task-low-first', 'LOW'),
task('task-high-second', 'HIGH'),
task('task-critical-third', 'CRITICAL'),
],
autoSystem: [],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t.id)).toEqual([
'task-low-first',
'task-high-second',
'task-critical-third',
]);
});
it('stops issuing spawns once availableSlots is exhausted (cross-bucket)', () => {
// Only 2 free slots — onDemand fills slot 1, user fills slot 2, the rest
// of the queues are left untouched.
const state = makeState({ maxConcurrentAgents: 2 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [task('task-onDemand-1')],
user: [task('task-user-1'), task('task-user-2')],
autoSystem: [task('sys-auto-1')],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned).toHaveLength(2);
expect(spawned.map(t => t.id)).toEqual(['task-onDemand-1', 'task-user-1']);
});
it('returns no spawns when buckets are empty (idle queue)', () => {
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = { onDemand: [], user: [], autoSystem: [], idle: [] };
expect(priorityDequeue(buckets, capacity)).toEqual([]);
});
});
// ─── dequeueNextTask: capacity guards ──────────────────────────────────────
describe('dequeueNextTask — capacity guards', () => {
it('returns zero spawns when running agents already saturate the global cap', () => {
// 3-slot cap, 3 already running — no headroom.
const state = makeState({
maxConcurrentAgents: 3,
runningAgents: [makeRunningAgent(), makeRunningAgent(), makeRunningAgent()],
});
const capacity = makeCapacityTracker(state);
expect(capacity.availableSlots).toBe(0);
const buckets = {
onDemand: [task('task-onDemand-1')],
user: [task('task-user-1')],
autoSystem: [],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned).toEqual([]);
});
it('returns zero spawns when running agents OVER-saturate the cap (>= guard, not ==)', () => {
// Defensive: if some path registered more agents than the cap (e.g. a
// config change shrunk the cap below current load), availableSlots goes
// negative — the guard must still block, not let `< 0` slip through as
// "infinite slots".
const state = makeState({
maxConcurrentAgents: 2,
runningAgents: [makeRunningAgent(), makeRunningAgent(), makeRunningAgent()],
});
const capacity = makeCapacityTracker(state);
expect(capacity.availableSlots).toBeLessThan(0);
const buckets = { onDemand: [], user: [task('task-user-1')], autoSystem: [], idle: [] };
expect(priorityDequeue(buckets, capacity)).toEqual([]);
});
it('respects per-project cap: project saturated → task skipped, other-project task still fills', () => {
// Global cap 5, but per-project cap 1. App "alpha" already has 1
// running agent, so its pending user task must be skipped. The pending
// task for app "beta" should still spawn (different bucket of the
// per-project counter).
const state = makeState({
maxConcurrentAgents: 5,
maxConcurrentAgentsPerProject: 1,
runningAgents: [makeRunningAgent('alpha')],
});
const agentsByProject = { alpha: 1 };
const capacity = makeCapacityTracker(state, agentsByProject);
const buckets = {
onDemand: [],
user: [
task('task-alpha-1', 'HIGH', { app: 'alpha' }),
task('task-beta-1', 'MEDIUM', { app: 'beta' }),
],
autoSystem: [],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t.id)).toEqual(['task-beta-1']);
});
it('per-project cap counts in-batch spawns too (not just pre-existing runners)', () => {
// Per-project cap 2, none running. Three user tasks all on app "alpha".
// First two must spawn, third must be skipped (in-batch spawn count
// pushed alpha to the per-project cap).
const state = makeState({
maxConcurrentAgents: 10,
maxConcurrentAgentsPerProject: 2,
});
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [
task('task-alpha-1', 'HIGH', { app: 'alpha' }),
task('task-alpha-2', 'HIGH', { app: 'alpha' }),
task('task-alpha-3', 'HIGH', { app: 'alpha' }),
],
autoSystem: [],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t.id)).toEqual(['task-alpha-1', 'task-alpha-2']);
expect(capacity.spawnProjectCounts.alpha).toBe(2);
});
it('per-project cap defaults to global cap when null/0', () => {
// When maxConcurrentAgentsPerProject is null, production lines 638 +
// 2334 fall through to the global cap, so the per-project guard is
// effectively disabled.
const state = makeState({
maxConcurrentAgents: 3,
maxConcurrentAgentsPerProject: null,
});
const capacity = makeCapacityTracker(state);
expect(capacity.perProjectLimit).toBe(3);
const buckets = {
onDemand: [],
user: [
task('task-alpha-1', 'HIGH', { app: 'alpha' }),
task('task-alpha-2', 'HIGH', { app: 'alpha' }),
task('task-alpha-3', 'HIGH', { app: 'alpha' }),
],
autoSystem: [],
idle: [],
};
expect(priorityDequeue(buckets, capacity)).toHaveLength(3);
});
it('null app metadata buckets into the `_self` project key (PortOS work)', () => {
// PortOS-on-itself tasks have no app metadata. The `_self` bucket is a
// sentinel that prevents app-less tasks from bypassing the per-project
// cap (which is a real production guarantee — see line 659).
const state = makeState({
maxConcurrentAgents: 5,
maxConcurrentAgentsPerProject: 1,
});
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [
task('task-self-1', 'HIGH'),
task('task-self-2', 'HIGH'),
],
autoSystem: [],
idle: [],
};
const spawned = priorityDequeue(buckets, capacity);
expect(spawned.map(t => t.id)).toEqual(['task-self-1']);
expect(capacity.spawnProjectCounts._self).toBe(1);
});
});
// ─── dequeueNextTask: per-local-endpoint agent cap (issue #4834) ───────────
//
// A CoS agent runs a vendor CLI that opens its own connection to the local
// model server, so promptRunner's in-flight gate never sees it. These drive the
// REAL `createLocalEndpointSlotContext` resolvers through the REAL capacity
// tracker — the same pair `dequeueNextTask` wires together — so a regression in
// either half fails here.
// What the PROVIDER RECORD holds, vs the normalized SLOT KEY the cap is keyed
// by. They differ on purpose: host+port identifies the model server, so
// `localhost` and `127.0.0.1` on one port must share a single slot.
const LOCAL_URL = 'http://localhost:1234/v1';
const LOCAL_ENDPOINT = 'localhost:1234';
const OTHER_LOCAL_URL = 'http://127.0.0.1:11434';
const OTHER_LOCAL_ENDPOINT = 'localhost:11434';
// A TUI provider pointed at a local server is exactly the case #4834 exists
// for: PortOS launches the CLI, the CLI talks to the GPU directly.
const LOCAL_TUI_PROVIDER = { id: 'lmstudio-tui', type: 'tui', enabled: true, endpoint: LOCAL_URL };
const OTHER_LOCAL_PROVIDER = { id: 'ollama-local', type: 'api', enabled: true, endpoint: OTHER_LOCAL_URL };
// No recorded endpoint — PortOS cannot know where it points, so it stays ungated.
const BARE_CLI_PROVIDER = { id: 'claude-cli', type: 'cli', enabled: true, endpoint: null };
const CLOUD_PROVIDER = { id: 'anthropic', type: 'api', enabled: true, endpoint: 'https://api.anthropic.com/v1' };
const ALL_PROVIDERS = [LOCAL_TUI_PROVIDER, OTHER_LOCAL_PROVIDER, BARE_CLI_PROVIDER, CLOUD_PROVIDER];
/** A running agent stamped with the providerId agentLifecycle persists. */
function makeRunningAgentOnProvider(providerId, app = '_self') {
return { status: 'running', metadata: { taskApp: app, app, providerId } };
}
/** A pending task pinned to a provider via `metadata.provider`. */
const taskOnProvider = (id, providerId) => ({
id,
priority: 'HIGH',
status: 'pending',
metadata: providerId === undefined ? {} : { provider: providerId },
});
/**
* Build the capacity tracker the way `dequeueNextTask` does: real slot context
* over the fixture provider list, real running-agent endpoint tally, real hold
* callback (captured so tests can assert the queued-no-slot log fired).
*/
function makeLocalSlotCapacity(state, { activeProvider = CLOUD_PROVIDER, limit = 1, agentsByProject = {} } = {}) {
const slots = createLocalEndpointSlotContext({ providers: ALL_PROVIDERS, activeProvider, limit });
const holds = [];
const capacity = createDequeueCapacity(state, {
agentsByProject,
localEndpointCounts: countRunningAgentsByLocalEndpoint(state.agents, slots.endpointForAgent),
localEndpointLimit: slots.limit,
resolveLocalEndpoint: slots.resolveLocalEndpoint,
onLocalEndpointHold: (task, endpoint, running) => holds.push({ taskId: task.id, endpoint, running }),
});
return { capacity, holds, slots };
}
const userBuckets = (tasks) => ({ onDemand: [], user: tasks, autoSystem: [], idle: [] });
describe('dequeueNextTask — task ownership beyond registered agents (#11847)', () => {
it('never admits an in-flight spawn, and still counts it against the global slots', () => {
// 4-slot cap: 1 running agent + 2 spawns in flight (no agent record yet)
// leaves one real slot, which the queued task — not the in-flight ones — gets.
const state = makeState({ maxConcurrentAgents: 4, runningAgents: [makeRunningAgent()] });
const capacity = createDequeueCapacity(state, { inFlightTaskIds: new Set(['spawning-a', 'spawning-b']) });
expect(capacity.availableSlots).toBe(1);
const buckets = {
onDemand: [],
user: [task('spawning-a'), task('spawning-b'), task('queued-c'), task('queued-d')],
autoSystem: [],
idle: [],
};
expect(priorityDequeue(buckets, capacity).map(t => t.id)).toEqual(['queued-c']);
});
it('admits nothing when running agents plus in-flight spawns fill maxConcurrentAgents', () => {
const state = makeState({ maxConcurrentAgents: 2, runningAgents: [makeRunningAgent()] });
const capacity = createDequeueCapacity(state, { inFlightTaskIds: ['spawning-a'] });
expect(capacity.availableSlots).toBe(0);
expect(priorityDequeue({ onDemand: [], user: [task('queued-b')], autoSystem: [], idle: [] }, capacity)).toEqual([]);
});
it('does not double-count an in-flight spawn whose agent is already running', () => {
const state = makeState({
maxConcurrentAgents: 3,
runningAgents: [{ ...makeRunningAgent(), taskId: 'spawning-a' }],
});
const capacity = createDequeueCapacity(state, { inFlightTaskIds: ['spawning-a'] });
expect(capacity.availableSlots).toBe(2);
});
it('admits a task id at most once per cycle across tiers', () => {
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = createDequeueCapacity(state, {});
const buckets = {
onDemand: [task('dup-1')],
user: [task('dup-1'), task('user-2')],
autoSystem: [task('dup-1'), task('user-2'), task('sys-3')],
idle: [],
};
expect(priorityDequeue(buckets, capacity).map(t => t.id)).toEqual(['dup-1', 'user-2', 'sys-3']);
expect(capacity.spawnedTaskIds).toEqual(['dup-1', 'user-2', 'sys-3']);
expect(capacity.spawned).toBe(3);
});
});
describe('dequeueNextTask — per-local-endpoint agent cap (#4834)', () => {
it('serializes two queued tasks that resolve to the SAME local endpoint', () => {
// Global cap 5, nothing running: both tasks clear the global and
// per-project guards. Only the local-endpoint slot separates them.
const state = makeState({ maxConcurrentAgents: 5 });
const { capacity, holds } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-local-1', 'lmstudio-tui'),
taskOnProvider('task-local-2', 'lmstudio-tui'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-local-1']);
expect(holds).toEqual([{ taskId: 'task-local-2', endpoint: LOCAL_ENDPOINT, running: 1 }]);
expect(capacity.spawnLocalEndpointCounts[LOCAL_ENDPOINT]).toBe(1);
});
it('does NOT suppress an explicit on-demand Run at a saturated endpoint', () => {
// Priority 0 clears the request and binds the app-review marker BEFORE
// canSpawn runs, and that branch is the only thing that persists the task —
// so a denial here destroys the user's "Run" and strands the marker rather
// than deferring it. The task must be admitted and held at the spawner
// chokepoint instead, which leaves it pending and releases both side effects.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const { capacity, holds } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue({
onDemand: [taskOnProvider('task-run-now', 'lmstudio-tui')],
user: [],
autoSystem: [],
idle: [],
}, capacity);
expect(spawned.map(t => t.id)).toEqual(['task-run-now']);
expect(holds).toEqual([]);
});
it('does NOT suppress an idle task at a saturated endpoint', () => {
// The idle tier commits before canSpawn and never persists: it has already
// bound the app-review marker and advanced its 30-minute cooldown. A denial
// would strand it; the chokepoint's hold at least releases the marker.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const { capacity } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue({
onDemand: [],
user: [],
autoSystem: [],
idle: [taskOnProvider('idle-task', 'lmstudio-tui')],
}, capacity);
expect(spawned.map(t => t.id)).toEqual(['idle-task']);
});
it.each(['user', 'autoSystem'])('keeps gating the deferrable %s tier at the same endpoint', (bucket) => {
// The opt-out is scoped to the tiers whose denial is destructive. A task
// from a persisted queue stays queued, which is a real defer — the next
// cycle re-picks it once the endpoint frees up.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const { capacity } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue({
onDemand: [], user: [], autoSystem: [], idle: [],
[bucket]: [taskOnProvider('deferrable-task', 'lmstudio-tui')],
}, capacity);
expect(spawned).toEqual([]);
});
it('counts an ALREADY-RUNNING agent against its local endpoint', () => {
// One agent is live on the local TUI provider. A queued task for the same
// endpoint must be held even though the global cap has room.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const { capacity, holds } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue(userBuckets([taskOnProvider('task-local-1', 'lmstudio-tui')]), capacity);
expect(spawned).toEqual([]);
expect(holds).toEqual([{ taskId: 'task-local-1', endpoint: LOCAL_ENDPOINT, running: 1 }]);
});
it('leaves cloud and endpoint-less providers unaffected', () => {
// A cloud API provider and a CLI provider with NO recorded endpoint both
// resolve to null. Neither is gated, so all three spawn concurrently even
// though a local agent is already saturating its endpoint.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const { capacity, holds } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-cloud', 'anthropic'),
taskOnProvider('task-bare-cli', 'claude-cli'),
taskOnProvider('task-cloud-2', 'anthropic'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-cloud', 'task-bare-cli', 'task-cloud-2']);
expect(holds).toEqual([]);
});
it('runs two DISTINCT local endpoints in parallel', () => {
// Keyed by endpoint, not by "is local" — two separate local servers each
// get their own slot.
const state = makeState({ maxConcurrentAgents: 5 });
const { capacity } = makeLocalSlotCapacity(state);
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-lmstudio', 'lmstudio-tui'),
taskOnProvider('task-ollama', 'ollama-local'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-lmstudio', 'task-ollama']);
});
it('honors a lifted limit (LOCAL_LLM_MAX_CONCURRENCY > 1)', () => {
const state = makeState({ maxConcurrentAgents: 5 });
const { capacity, holds } = makeLocalSlotCapacity(state, { limit: 2 });
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-local-1', 'lmstudio-tui'),
taskOnProvider('task-local-2', 'lmstudio-tui'),
taskOnProvider('task-local-3', 'lmstudio-tui'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-local-1', 'task-local-2']);
expect(holds.map(h => h.taskId)).toEqual(['task-local-3']);
});
it('gates UNPINNED tasks by the ACTIVE provider endpoint', () => {
// A task with no `metadata.provider` runs on the active provider — when
// that is local, the cap applies to it too.
const state = makeState({ maxConcurrentAgents: 5 });
const { capacity } = makeLocalSlotCapacity(state, { activeProvider: LOCAL_TUI_PROVIDER });
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-unpinned-1'),
taskOnProvider('task-unpinned-2'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-unpinned-1']);
});
it('falls back to the active provider for an UNKNOWN pinned id (mirrors spawn)', () => {
// resolveAgentProviderAndModel logs and uses the active provider when the
// pinned id is missing; the gate must predict the same landing spot.
const state = makeState({ maxConcurrentAgents: 5 });
const { capacity, holds } = makeLocalSlotCapacity(state, { activeProvider: LOCAL_TUI_PROVIDER });
const spawned = priorityDequeue(userBuckets([
taskOnProvider('task-local-1', 'lmstudio-tui'),
taskOnProvider('task-ghost', 'deleted-provider'),
]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-local-1']);
expect(holds).toEqual([{ taskId: 'task-ghost', endpoint: LOCAL_ENDPOINT, running: 1 }]);
});
it('leaves the cap disabled when no limit is supplied', () => {
// createDequeueCapacity's defaults must not gate anything — every existing
// caller (and every test above this block) constructs it without the
// local-endpoint options.
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = createDequeueCapacity(state, {});
expect(capacity.localEndpointLimit).toBe(Infinity);
expect(priorityDequeue(userBuckets([
taskOnProvider('task-a', 'lmstudio-tui'),
taskOnProvider('task-b', 'lmstudio-tui'),
]), capacity)).toHaveLength(2);
});
it('floors a 0/NaN limit at 1 rather than wedging the queue forever', () => {
const state = makeState({ maxConcurrentAgents: 5 });
const slots = createLocalEndpointSlotContext({ providers: ALL_PROVIDERS, activeProvider: CLOUD_PROVIDER, limit: 0 });
const capacity = createDequeueCapacity(state, {
localEndpointLimit: slots.limit,
resolveLocalEndpoint: slots.resolveLocalEndpoint,
});
expect(capacity.localEndpointLimit).toBe(1);
expect(priorityDequeue(userBuckets([
taskOnProvider('task-a', 'lmstudio-tui'),
taskOnProvider('task-b', 'lmstudio-tui'),
]), capacity).map(t => t.id)).toEqual(['task-a']);
});
});
describe('countRunningAgentsByLocalEndpoint (#4834)', () => {
const slots = createLocalEndpointSlotContext({ providers: ALL_PROVIDERS, activeProvider: CLOUD_PROVIDER });
it('tallies only RUNNING agents, only on local endpoints', () => {
const agents = {
a: makeRunningAgentOnProvider('lmstudio-tui'),
b: makeRunningAgentOnProvider('lmstudio-tui'),
c: makeRunningAgentOnProvider('ollama-local'),
d: makeRunningAgentOnProvider('anthropic'), // cloud → not counted
e: makeRunningAgentOnProvider('claude-cli'), // no endpoint → not counted
f: { status: 'completed', metadata: { providerId: 'lmstudio-tui' } },
};
expect(countRunningAgentsByLocalEndpoint(agents, slots.endpointForAgent)).toEqual({
[LOCAL_ENDPOINT]: 2,
[OTHER_LOCAL_ENDPOINT]: 1,
});
});
it('ignores agents with no provider stamp (pre-upgrade records)', () => {
const agents = { a: { status: 'running', metadata: {} }, b: { status: 'running' } };
expect(countRunningAgentsByLocalEndpoint(agents, slots.endpointForAgent)).toEqual({});
});
});
describe('localEndpointOfProvider (#4834)', () => {
it('resolves a local endpoint regardless of provider type', () => {
expect(localEndpointOfProvider({ type: 'tui', endpoint: 'http://localhost:1234/v1' })).toBe('localhost:1234');
expect(localEndpointOfProvider({ type: 'api', endpoint: 'http://127.0.0.1:11434' })).toBe('localhost:11434');
});
it('collapses every spelling of ONE local server onto a single slot key', () => {
// Host+port identifies the model server; scheme, path and host spelling do
// not. The shipped catalog already mixes spellings (`lmstudio` is seeded at
// localhost:1234, everything else at 127.0.0.1), so keying on the raw string
// would give one LM Studio process two independent caps — and let two agents
// onto the same GPU, the exact OOM this issue exists to prevent.
const spellings = [
'http://localhost:1234/v1',
'http://127.0.0.1:1234/v1',
'http://127.0.0.1:1234',
'https://localhost:1234/v1',
'localhost:1234',
' http://0.0.0.0:1234/v1 ',
];
for (const endpoint of spellings) {
expect(localEndpointOfProvider({ endpoint }), endpoint).toBe('localhost:1234');
}
});
it('keeps distinct local servers on distinct keys', () => {
expect(localEndpointOfProvider({ endpoint: 'http://127.0.0.1:1234/v1' }))
.not.toBe(localEndpointOfProvider({ endpoint: 'http://127.0.0.1:11434/v1' }));
});
it('returns null for a remote endpoint, a missing endpoint, or no provider', () => {
expect(localEndpointOfProvider({ type: 'api', endpoint: 'https://api.anthropic.com/v1' })).toBeNull();
expect(localEndpointOfProvider({ type: 'cli', endpoint: null })).toBeNull();
expect(localEndpointOfProvider({ type: 'tui' })).toBeNull();
expect(localEndpointOfProvider(null)).toBeNull();
});
it('never guesses from a model id — only the recorded endpoint counts', () => {
// The issue is explicit: a TUI provider whose endpoint isn't recorded stays
// ungated even when its model id names a local runtime.
expect(localEndpointOfProvider({ type: 'tui', defaultModel: 'mtplx/local-qwen-27b', endpoint: null })).toBeNull();
});
});
describe('cloudSwarmThreadCapacity', () => {
it('reserves one root thread in addition to every configured cloud worker', () => {
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, 6)).toBe(7);
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, 12)).toBe(13);
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, '12')).toBe(13);
});
it('does not lift the harness cap for a local inference endpoint', () => {
expect(cloudSwarmThreadCapacity(LOCAL_TUI_PROVIDER, 12)).toBeNull();
});
it('does not override the harness outside a valid multi-worker swarm', () => {
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, 1)).toBeNull();
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, 2.5)).toBeNull();
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, 13)).toBeNull();
expect(cloudSwarmThreadCapacity(CLOUD_PROVIDER, null)).toBeNull();
});
});
describe('resolveLocalEndpoint — unavailable providers are not gated (#4834)', () => {
// A saturated LOCAL provider that is currently unavailable (rate-limited,
// cooling down, down) is not where the task lands: resolveAgentProviderAndModel
// swaps it for a fallback, often a cloud one. Gating on it anyway would hold
// the task behind a GPU it never touches — and nothing about that busy GPU
// would ever clear the hold, so the task starves.
const withAvailability = (available) => createLocalEndpointSlotContext({
providers: ALL_PROVIDERS,
activeProvider: CLOUD_PROVIDER,
isAvailable: (id) => available.includes(id),
});
it('resolves to null when the pinned local provider is unavailable', () => {
const slots = withAvailability(['anthropic']);
expect(slots.resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui'))).toBeNull();
});
it('still gates the same provider once it is available again', () => {
const slots = withAvailability(['lmstudio-tui', 'anthropic']);
expect(slots.resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui'))).toBe(LOCAL_ENDPOINT);
});
it('resolves to null when the ACTIVE local provider is unavailable', () => {
const slots = createLocalEndpointSlotContext({
providers: ALL_PROVIDERS,
activeProvider: LOCAL_TUI_PROVIDER,
isAvailable: () => false,
});
expect(slots.resolveLocalEndpoint(taskOnProvider('t'))).toBeNull();
});
it('does not starve a queued task behind an unavailable local endpoint', () => {
// End-to-end through the real tracker: one agent is running on the local
// endpoint, but the provider has since gone unavailable, so the queued task
// must dispatch (onto its fallback) instead of waiting forever.
const state = makeState({
maxConcurrentAgents: 5,
runningAgents: [makeRunningAgentOnProvider('lmstudio-tui')],
});
const slots = withAvailability(['anthropic']);
const capacity = createDequeueCapacity(state, {
localEndpointCounts: countRunningAgentsByLocalEndpoint(state.agents, slots.endpointForAgent),
localEndpointLimit: slots.limit,
resolveLocalEndpoint: slots.resolveLocalEndpoint,
});
const spawned = priorityDequeue(userBuckets([taskOnProvider('task-local-1', 'lmstudio-tui')]), capacity);
expect(spawned.map(t => t.id)).toEqual(['task-local-1']);
});
it('leaves a task with no resolvable provider ungated', () => {
const slots = createLocalEndpointSlotContext({ providers: [], activeProvider: null });
expect(slots.resolveLocalEndpoint(taskOnProvider('t'))).toBeNull();
expect(slots.resolveLocalEndpoint(taskOnProvider('t', 'ghost'))).toBeNull();
});
});
describe('local-endpoint spawn reservations (#4834)', () => {
beforeEach(() => __resetLocalEndpointSpawnReservations());
it('counts a reserved-but-not-yet-running spawn against the endpoint', () => {
// The window between `task:ready` and the agent record reaching `running`
// is several awaits wide. Without the reservation, a second dispatch inside
// it reads a snapshot showing zero running agents and over-dispatches.
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(0);
const release = reserveLocalEndpointSpawn(LOCAL_ENDPOINT);
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(1);
release();
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(0);
});
it('is idempotent — a double release cannot free a slot twice', () => {
// The spawner releases in a `finally`, so a throw plus the finally can call
// it twice. A naive decrement would go negative and hand out a phantom slot.
const first = reserveLocalEndpointSpawn(LOCAL_ENDPOINT);
const second = reserveLocalEndpointSpawn(LOCAL_ENDPOINT);
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(2);
first();
first();
first();
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(1);
second();
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(0);
});
it('reserving a null endpoint is a no-op', () => {
const release = reserveLocalEndpointSpawn(null);
expect(pendingLocalEndpointSpawns(null)).toBe(0);
expect(() => release()).not.toThrow();
});
it('gives a direct cloud provider call a no-op shared-capacity release', async () => {
const claim = await acquireLocalEndpointProviderSlot(
{ id: 'cloud-api', endpoint: 'https://api.example.com/v1' },
{},
'persistent-mind-turn'
);
expect(claim.ok).toBe(true);
expect(() => claim.release()).not.toThrow();
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(0);
});
it('keeps reservations per endpoint', () => {
reserveLocalEndpointSpawn(LOCAL_ENDPOINT);
reserveLocalEndpointSpawn(OTHER_LOCAL_ENDPOINT);
expect(pendingLocalEndpointSpawns(LOCAL_ENDPOINT)).toBe(1);
expect(pendingLocalEndpointSpawns(OTHER_LOCAL_ENDPOINT)).toBe(1);
});
});
describe('endpointForAgent — stamped endpoint wins over the id lookup (#4834)', () => {
const slots = createLocalEndpointSlotContext({ providers: ALL_PROVIDERS, activeProvider: CLOUD_PROVIDER });
it('counts an agent whose provider record was deleted mid-run', () => {
// Only `providerId` was persisted pre-#4834, so a deleted provider made a
// still-running agent invisible to the cap — freeing a slot the GPU was
// still holding. The stamped endpoint survives the deletion.
const orphaned = { status: 'running', metadata: { providerId: 'deleted-provider', providerEndpoint: LOCAL_URL } };
expect(slots.endpointForAgent(orphaned)).toBe(LOCAL_ENDPOINT);
expect(countRunningAgentsByLocalEndpoint({ a: orphaned }, slots.endpointForAgent)).toEqual({ [LOCAL_ENDPOINT]: 1 });
});
it('prefers the stamp when the provider record was re-pointed mid-run', () => {
// The agent is still talking to the endpoint it started on, not the one the
// provider now names.
const agent = { status: 'running', metadata: { providerId: 'ollama-local', providerEndpoint: LOCAL_URL } };
expect(slots.endpointForAgent(agent)).toBe(LOCAL_ENDPOINT);
});
it('falls back to the id lookup for a pre-#4834 record with no stamp', () => {
expect(slots.endpointForAgent({ status: 'running', metadata: { providerId: 'lmstudio-tui' } })).toBe(LOCAL_ENDPOINT);
expect(slots.endpointForAgent({ status: 'running', metadata: { providerId: 'lmstudio-tui', providerEndpoint: null } })).toBe(LOCAL_ENDPOINT);
});
it('does NOT re-resolve when the stamp is REMOTE', () => {
// The agent is talking to the cloud. If its provider record is re-pointed at
// a local server mid-run, falling through to the id lookup would count this
// cloud agent against that GPU — saturating an endpoint with zero agents on
// it and holding every task behind it at the default limit of 1.
const cloudAgent = {
status: 'running',
metadata: { providerId: 'lmstudio-tui', providerEndpoint: 'https://api.anthropic.com/v1' },
};
expect(slots.endpointForAgent(cloudAgent)).toBeNull();
expect(countRunningAgentsByLocalEndpoint({ a: cloudAgent }, slots.endpointForAgent)).toEqual({});
});
});
describe('resolveLocalEndpoint — follows the fallback swap (#4834)', () => {
// An unavailable provider is not where the task lands, so the gate follows the
// SAME getFallbackProvider spawn uses. Both directions matter: a cloud
// fallback must ungate (or the task starves behind a GPU it never touches),
// and a fallback on the same local server must stay gated (or the cap
// disappears exactly when the endpoint is unhealthy — the shipped catalog has
// four providers on 127.0.0.1:18021).
const SAME_SERVER_SIBLING = { id: 'lmstudio-api', type: 'api', enabled: true, endpoint: 'http://127.0.0.1:1234' };
const withFallback = (fallbackProvider) => createLocalEndpointSlotContext({
providers: [...ALL_PROVIDERS, SAME_SERVER_SIBLING],
activeProvider: CLOUD_PROVIDER,
isAvailable: (id) => id !== 'lmstudio-tui',
resolveFallback: () => fallbackProvider,
});
it('stays gated when the fallback lands on the SAME local server', () => {
// Different provider record, different host spelling, same GPU.
expect(withFallback(SAME_SERVER_SIBLING).resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui')))
.toBe(LOCAL_ENDPOINT);
});
it('ungates when the fallback is a cloud provider', () => {
expect(withFallback(CLOUD_PROVIDER).resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui'))).toBeNull();
});
it('gates on the FALLBACK endpoint when it is a different local server', () => {
expect(withFallback(OTHER_LOCAL_PROVIDER).resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui')))
.toBe(OTHER_LOCAL_ENDPOINT);
});
it('ungates when no fallback resolves at all', () => {
expect(withFallback(null).resolveLocalEndpoint(taskOnProvider('t', 'lmstudio-tui'))).toBeNull();
});
it('passes the task through so a task-level fallback pin is honored', () => {
// getFallbackProvider's first tier reads metadata.fallbackProvider /
// metadata.fallbackModel off the task; the context must hand them over.
const seen = [];
const slots = createLocalEndpointSlotContext({
providers: ALL_PROVIDERS,
activeProvider: CLOUD_PROVIDER,
isAvailable: () => false,
resolveFallback: (primaryId, providersMap, task) => { seen.push({ primaryId, task }); return null; },
});
slots.resolveLocalEndpoint({ id: 't', metadata: { provider: 'lmstudio-tui', fallbackProvider: 'ollama-local' } });
expect(seen).toHaveLength(1);
expect(seen[0].primaryId).toBe('lmstudio-tui');
expect(seen[0].task.metadata.fallbackProvider).toBe('ollama-local');
});
});
describe('readEndpointCapacity (#4834)', () => {
beforeEach(() => __resetLocalEndpointSpawnReservations());
const slots = createLocalEndpointSlotContext({ providers: ALL_PROVIDERS, activeProvider: CLOUD_PROVIDER, limit: 1 });
const runningOn = (providerId, taskId) => ({ status: 'running', taskId, metadata: { providerId } });
it('counts a running agent against its endpoint', () => {
const capacity = readEndpointCapacity(LOCAL_ENDPOINT, { a: runningOn('lmstudio-tui', 'task-a') }, slots);
expect(capacity).toMatchObject({ inFlight: 1, limit: 1, atCapacity: true });
});
it('excludes the dispatching task\'s OWN agent so Run-now can supersede a zombie', () => {
// forceSpawnTask deliberately supersedes a `running` holder older than the
// spawn grace — that is the documented recovery for an agent whose PTY died
// without a close handler. Counting the zombie would make the one recovery
// the route exists to provide unreachable at a limit of 1.
const agents = { a: runningOn('lmstudio-tui', 'task-stuck') };
expect(readEndpointCapacity(LOCAL_ENDPOINT, agents, slots, { ignoreTaskId: 'task-stuck' }).atCapacity).toBe(false);
expect(readEndpointCapacity(LOCAL_ENDPOINT, agents, slots, { ignoreTaskId: 'other-task' }).atCapacity).toBe(true);
});
it('does not double-count a reservation whose agent already registered', () => {
// registerAgent flips the record to `running` well before spawnAgentForTask
// returns, so for the whole PTY-launch window the same agent is both in the
// running tally and holding its reservation.
reserveLocalEndpointSpawn(LOCAL_ENDPOINT, 'task-a');
const agents = { a: runningOn('lmstudio-tui', 'task-a') };
expect(readEndpointCapacity(LOCAL_ENDPOINT, agents, slots).inFlight).toBe(1);
});
it('still counts a reservation that has NOT registered yet', () => {
reserveLocalEndpointSpawn(LOCAL_ENDPOINT, 'task-b');
const agents = { a: runningOn('lmstudio-tui', 'task-a') };
expect(readEndpointCapacity(LOCAL_ENDPOINT, agents, slots).inFlight).toBe(2);
});
it('counts an anonymous reservation (no task id) unconditionally', () => {
reserveLocalEndpointSpawn(LOCAL_ENDPOINT, null);
expect(readEndpointCapacity(LOCAL_ENDPOINT, {}, slots).inFlight).toBe(1);
});
it('ignores agents on other endpoints and non-running agents', () => {
const agents = {
a: runningOn('ollama-local', 'task-a'),
b: runningOn('anthropic', 'task-b'),
c: { status: 'completed', taskId: 'task-c', metadata: { providerId: 'lmstudio-tui' } },
};
expect(readEndpointCapacity(LOCAL_ENDPOINT, agents, slots).inFlight).toBe(0);
});
});
describe('localEndpointOfProvider — Ollama-backed CLI/TUI providers (#4834)', () => {
// Four SHIPPED providers run against the local Ollama daemon with no
// `endpoint` field at all. They are the archetype of this issue — PortOS
// launches a vendor CLI that opens its own connection — so leaving them
// ungated would make the cap inconsistent across providers of the same shape.
it('reads the daemon from ANTHROPIC_BASE_URL when endpoint is unset', () => {
expect(localEndpointOfProvider({
id: 'claude-ollama-tui', type: 'tui', ollamaBacked: true,
envVars: { ANTHROPIC_BASE_URL: 'http://localhost:11434' },
})).toBe('localhost:11434');
});
it('falls back to the default daemon for a bare ollamaBacked marker', () => {
// opencode-ollama* keep their base inside an OPENCODE_CONFIG_CONTENT blob;
// the marker alone means the default daemon (what the toolkit's own
// ollamaBaseFromProvider does).
expect(localEndpointOfProvider({
id: 'opencode-ollama-tui', type: 'tui', ollamaBacked: true,
envVars: { OPENCODE_CONFIG_CONTENT: '{}' },
})).toBe('localhost:11434');
});
it('shares ONE slot with the api-type `ollama` provider on the same daemon', () => {
const cli = localEndpointOfProvider({ id: 'claude-ollama', ollamaBacked: true, envVars: { ANTHROPIC_BASE_URL: 'http://localhost:11434' } });
const api = localEndpointOfProvider({ id: 'ollama', type: 'api', endpoint: 'http://localhost:11434/v1' });
expect(cli).toBe(api);
});
it('does NOT localize a REMOTE Ollama daemon', () => {
// The recorded base wins over the local default — an Ollama on another host
// is not this machine's GPU.
expect(localEndpointOfProvider({ id: 'remote-ollama', type: 'api', endpoint: 'http://192.0.2.10:11434' })).toBeNull();
expect(localEndpointOfProvider({
id: 'remote-claude-ollama', ollamaBacked: true,
envVars: { ANTHROPIC_BASE_URL: 'http://192.0.2.10:11434' },
})).toBeNull();
});
});
describe('providerBaseUrl — the stamp source (#4834)', () => {
it('returns the REMOTE base of an Ollama-backed CLI that has no endpoint', () => {
// `localRuntimeForProvider` answers null for it (correctly — it is not this
// box), and it records its daemon ONLY in envVars. Returning null here would
// stamp an absent endpoint, and `endpointForAgent` reads absent as
// "re-resolve by provider id" — so re-pointing that provider at a local URL
// mid-run would start counting a remote agent against the local GPU.
const remote = { id: 'remote-ollama-cli', ollamaBacked: true, envVars: { ANTHROPIC_BASE_URL: 'http://192.0.2.10:11434' } };
expect(providerBaseUrl(remote)).toBe('http://192.0.2.10:11434');
expect(localEndpointOfProvider(remote)).toBeNull();
});
it('prefers the resolved local runtime endpoint over the raw record', () => {
const local = { id: 'claude-ollama', ollamaBacked: true, envVars: { ANTHROPIC_BASE_URL: 'http://localhost:11434' } };
expect(localEndpointOfProvider(local)).toBe('localhost:11434');
});
it('is null only when the record names no base at all', () => {
expect(providerBaseUrl({ id: 'claude-cli', type: 'cli', endpoint: null })).toBeNull();
expect(providerBaseUrl(null)).toBeNull();
});
it('keeps a cloud base so its agent is never re-resolved', () => {
expect(providerBaseUrl(CLOUD_PROVIDER)).toBe('https://api.anthropic.com/v1');
expect(localEndpointOfProvider(CLOUD_PROVIDER)).toBeNull();
});
});
// ─── Source-level regression guards ────────────────────────────────────────
//
// These pin two structural invariants of the production code that the
// inline-copy tests can't catch on their own. If a future refactor moves
// the early-return out of `dequeueNextTask` or shuffles the priority order,
// these assertions flip red.
/**
* Extract a function body from `src` starting at signature offset `fnStart`
* by scanning braces (depth-tracked) until the matching closing `}`. This is
* more robust than a fixed-length slice — large functions like
* `dequeueNextTask` (~250 LOC) can grow past any chosen window and silently
* drop priority markers, making ordering assertions pass on empty matches.
*
* Skips brace characters inside string literals (single/double quote AND
* template literals, including nested `${...}` interpolations), regex
* literals, and line/block comments so stray `{`/`}` characters don't
* unbalance the scanner. `evaluateTasks` and `dequeueNextTask` both contain
* template literals like `emitLog(`...${task.id}...`)` whose `${...}` braces
* would otherwise be counted as structural braces.
*
* Regex disambiguation uses a "previous significant token" heuristic — a `/`
* is a regex literal when the preceding non-whitespace token is not an
* identifier/number/closing-bracket. This handles the patterns used in cos.js
* (assignment, return, function-arg position) but isn't a full JS tokenizer;
* if a future refactor introduces edge cases the source-level assertions
* will fail loudly rather than silently miss matches.
*/
function extractFnBody(src, fnStart) {
// Skip the parameter list before locating the body brace: a destructured /
// defaulted param (e.g. `(state, data, { x = null } = {})`) contains `{`
// braces, so the body `{` is the first one AFTER the signature's closing `)`,
// not the first `{` after fnStart. Paren-match the signature first.
const parenIdx = src.indexOf('(', fnStart);
let searchFrom = fnStart;
if (parenIdx !== -1) {
let pdepth = 0;
for (let j = parenIdx; j < src.length; j++) {
if (src[j] === '(') pdepth++;
else if (src[j] === ')') { pdepth--; if (pdepth === 0) { searchFrom = j + 1; break; } }
}
}
const openIdx = src.indexOf('{', searchFrom);
if (openIdx === -1) return '';
let depth = 0;
let i = openIdx;
// Stack tracks nested template-literal `${...}` interpolation depth so the
// scanner returns to template-string mode after a `}` closes an expression.
const tplStack = [];
// Last significant (non-whitespace, non-comment) character — used to decide
// whether `/` starts a regex literal or is the division operator.
let lastSig = '';
const setLastSig = (c) => { if (!/\s/.test(c)) lastSig = c; };
while (i < src.length) {
const ch = src[i];
const next = src[i + 1];
// Line comment — skip to newline
if (ch === '/' && next === '/') {
const nl = src.indexOf('\n', i + 2);
i = nl === -1 ? src.length : nl + 1;
continue;
}
// Block comment — skip to closing */
if (ch === '/' && next === '*') {
const end = src.indexOf('*/', i + 2);
i = end === -1 ? src.length : end + 2;
continue;
}
// Regex literal — `/` is a regex start when not preceded by an
// identifier/number/closing-paren/closing-bracket (i.e. when it can't be
// the division operator). Skip to matching unescaped `/` (and flags).
if (ch === '/' && !/[\w)\]]/.test(lastSig)) {
let j = i + 1;
let inClass = false;
while (j < src.length) {
const c = src[j];
if (c === '\\') { j += 2; continue; }
if (c === '[') inClass = true;
else if (c === ']') inClass = false;
else if (c === '/' && !inClass) break;
else if (c === '\n') break; // unterminated regex — bail
j++;
}
// Skip trailing flags (g/i/m/s/u/y)
j++;
while (j < src.length && /[gimsuy]/.test(src[j])) j++;
i = j;
lastSig = '/';
continue;
}
// Single/double-quoted string — skip to matching unescaped quote
if (ch === '"' || ch === "'") {
let j = i + 1;
while (j < src.length) {
if (src[j] === '\\') { j += 2; continue; }
if (src[j] === ch) break;
if (src[j] === '\n') break; // unterminated — bail
j++;
}
i = j + 1;
lastSig = ch;
continue;
}
// Template literal — scan until backtick or `${`. On `${` push depth and
// resume normal scanning until matching `}` (tracked via tplStack).
if (ch === '`') {
let j = i + 1;
while (j < src.length) {
if (src[j] === '\\') { j += 2; continue; }
if (src[j] === '`') { j++; break; }
if (src[j] === '$' && src[j + 1] === '{') {
// Enter interpolation; resume outer loop, push template marker.
tplStack.push(depth);
i = j + 2;
depth++; // the `{` of ${
lastSig = '{';
break;
}
j++;
}
if (j >= i) { // either closed the template or entered interpolation
if (src[i] === undefined) break;
if (tplStack.length === 0 || tplStack[tplStack.length - 1] !== depth - 1) {
// We closed the template entirely (didn't enter interpolation).
i = j;
lastSig = '`';
}
}
continue;
}
if (ch === '{') { depth++; setLastSig(ch); i++; continue; }
if (ch === '}') {
depth--;
// If we just closed a template interpolation, resume template scan.
if (tplStack.length > 0 && tplStack[tplStack.length - 1] === depth) {
tplStack.pop();
// Resume template literal scan from i+1
let j = i + 1;
while (j < src.length) {
if (src[j] === '\\') { j += 2; continue; }
if (src[j] === '`') { j++; break; }
if (src[j] === '$' && src[j + 1] === '{') {
tplStack.push(depth);
j += 2;
depth++;
break;
}
j++;
}
i = j;
lastSig = '`';
continue;
}
if (depth === 0) return src.slice(fnStart, i + 1);
setLastSig(ch);
i++;
continue;
}
setLastSig(ch);
i++;
}
return src.slice(fnStart); // unbalanced — return rest of file
}
describe('cos.js source — priority + capacity invariants', () => {
it('dequeueNextTask early-returns when availableSlots <= 0', () => {
const fnStart = COS_SRC.indexOf('async function dequeueNextTask');
expect(fnStart, 'dequeueNextTask must exist').toBeGreaterThan(-1);
const fnBody = extractFnBody(COS_SRC, fnStart);
// `if (availableSlots <= 0) return;` (line 2332) is the cheap guard
// that prevents spawning when the global cap is at or beyond capacity.
// Regex tolerates optional braces, optional semicolon, and optional
// single-line block (`{ return; }`) so a formatting refactor doesn't
// trip this behavioral check.
expect(fnBody).toMatch(
/if\s*\(\s*availableSlots\s*<=\s*0\s*\)\s*(?:\{\s*)?return\s*;?\s*(?:\})?/
);
});
it('evaluateTasks short-circuits when availableSlots <= 0', () => {
const fnStart = GEN_SRC.indexOf('export async function evaluateTasks');
expect(fnStart, 'evaluateTasks must exist').toBeGreaterThan(-1);
const fnBody = extractFnBody(GEN_SRC, fnStart);
expect(fnBody).toMatch(/if\s*\(\s*availableSlots\s*<=\s*0\s*\)/);
});
// Parse a legacy row, write it back the way the USER queue writes it, and read
// the result — the approval flags a real row carries after one heal cycle.
const healedUserRow = (line) => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const parsed = parseTasksMarkdown(`# Tasks\n\n## Pending\n${line}\n`);
const [healed] = parseTasksMarkdown(generateTasksMarkdown(parsed, false));
warn.mockRestore();
return { approvalRequired: healed.approvalRequired, autoApproved: healed.autoApproved };
};
it('user tier withholds a recovered row, in BOTH spawn engines (#7300, #7367)', () => {
// A user row parses auto-approved unless the parser took its RECOVERY path,
// which cannot tell a genuine legacy row from a task-shaped sentence inside a
// legacy multi-line description body. This tier otherwise spawns every pending
// row, so without the predicate that sentence becomes an unattended agent run.
const state = makeState({ maxConcurrentAgents: 5 });
const capacity = makeCapacityTracker(state);
const buckets = {
onDemand: [],
user: [
{ ...task('task-note'), autoApproved: false },
// The same hold as it comes back OFF DISK. Round-tripped through the real
// writer and parser rather than hand-stamped, because the defect (#7367)
// was exactly there: the user file used to emit no flag, the recovered row
// healed into an ordinary strict row, and the next read spawned an agent
// from it. A hand-built fixture would have kept passing through all of it.
{ ...task('task-healed'), ...healedUserRow('- [ ] #task-healed | URGENT | legacy user row') },
{ ...task('task-real'), autoApproved: true },
task('task-fieldless'),
],
autoSystem: [],
idle: [],
};
// `undefined` is not a hold — a row that never carried the field still runs,
// so the guard narrows nothing that was already running.
expect(priorityDequeue(buckets, capacity).map(t => t.id)).toEqual(['task-real', 'task-fieldless']);
// Both engines used to run their own copy of this tier, verified only by
// grepping each body for the guard in source order — one is a fix, two is
// the fix. #7523 replaced the duplicated ladder with one shared pass
// (admitPendingUserTasks in cosTaskGenerator.js); now the only thing either
// engine's body needs to prove is that it DELEGATES there, and the ladder's
// own ordering (including this #7300 hold) is pinned once, behaviorally,
// against the shared pass in cosTaskGenerator.test.js's
// `describe('admitPendingUserTasks', …)` block.
const cosTier = extractFnBody(COS_SRC, COS_SRC.indexOf('async function spawnDequeuePriority1UserTasks'));
const genTier = extractFnBody(GEN_SRC, GEN_SRC.indexOf('async function spawnPriority1UserTasks'));
for (const [label, body] of [
['cos.js', cosTier],
['cosTaskGenerator.js', genTier],
]) {
expect(body, `${label} user tier must delegate to the shared admitPendingUserTasks pass`).toContain('admitPendingUserTasks(');
}
});
it('dequeueNextTask orchestrates the spawnDequeuePriority* tiers in priority order', () => {
// dequeueNextTask (cos.js) decomposes each priority tier into a named
// `spawnDequeuePriorityN(ctx)` helper (issue #2530), mirroring evaluateTasks.
// This pins that the orchestrator actually INVOKES each tier helper, in order
// — an actual reorder of the dequeue logic is the only thing that fails it.
//
// Priority 0 (onDemand) — spawnDequeuePriority0OnDemand(ctx)
// Priority 1 (user) — spawnDequeuePriority1UserTasks(ctx)
// Priority 2 (autoSystem) — spawnDequeuePriority2AutoApproved(ctx, { taskSchedule })
// Priority 3.6 (features) — spawnDequeuePriority36FeatureAgents(ctx, { ... })
// Priority 4 (idle) — spawnDequeuePriority4IdleReview(ctx, { ... })
const fnBody = extractFnBody(COS_SRC, COS_SRC.indexOf('async function dequeueNextTask'));
const onDemandIdx = fnBody.indexOf('spawnDequeuePriority0OnDemand(ctx)');
const userIdx = fnBody.indexOf('spawnDequeuePriority1UserTasks(ctx)');
const autoSysIdx = fnBody.indexOf('spawnDequeuePriority2AutoApproved(ctx, { taskSchedule })');
const featureIdx = fnBody.indexOf('spawnDequeuePriority36FeatureAgents(ctx, {');
const idleIdx = fnBody.indexOf('spawnDequeuePriority4IdleReview(ctx, {');
expect(onDemandIdx, 'spawnDequeuePriority0OnDemand must be invoked').toBeGreaterThan(-1);
expect(userIdx, 'spawnDequeuePriority1UserTasks must run after on-demand').toBeGreaterThan(onDemandIdx);
expect(autoSysIdx, 'spawnDequeuePriority2AutoApproved must run after user tasks').toBeGreaterThan(userIdx);
expect(featureIdx, 'spawnDequeuePriority36FeatureAgents must run after auto-approved').toBeGreaterThan(autoSysIdx);
expect(idleIdx, 'spawnDequeuePriority4IdleReview must run after feature agents').toBeGreaterThan(featureIdx);
});
it('evaluateTasks orchestrates the spawnPriority* tiers in priority order', () => {
// evaluateTasks (cosTaskGenerator.js) decomposes each priority tier into a
// named helper (issue #1082). This pins that the orchestrator actually
// INVOKES each tier helper, in order — so a helper carrying an autonomy/idle
// fence can't drift out of the spawn path while the broader, module-scoped
// gate guards below still match its (now-orphaned) fence text and pass green.
const fnBody = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function evaluateTasks'));
const onDemandIdx = fnBody.indexOf('spawnPriority0OnDemand(ctx)');
const userIdx = fnBody.indexOf('spawnPriority1UserTasks(ctx)');
const autoSysIdx = fnBody.indexOf('spawnPriority2AutoApproved(ctx,');
const queueIdx = fnBody.indexOf('maybeQueueImprovementTasks(ctx)');
const featureIdx = fnBody.indexOf('spawnPriority36FeatureAgents(ctx,');
const idleIdx = fnBody.indexOf('spawnPriority4IdleReview(ctx,');
expect(onDemandIdx, 'spawnPriority0OnDemand must be invoked').toBeGreaterThan(-1);
expect(userIdx, 'spawnPriority1UserTasks must run after on-demand').toBeGreaterThan(onDemandIdx);
expect(autoSysIdx, 'spawnPriority2AutoApproved must run after user tasks').toBeGreaterThan(userIdx);
expect(queueIdx, 'maybeQueueImprovementTasks must run after auto-approved').toBeGreaterThan(autoSysIdx);
expect(featureIdx, 'spawnPriority36FeatureAgents must run after improvement queueing').toBeGreaterThan(queueIdx);
expect(idleIdx, 'spawnPriority4IdleReview must run after feature agents').toBeGreaterThan(featureIdx);
});
it('on-demand (Priority 0) bypasses the global pause in BOTH engines', () => {
// A global pause stops scheduled/autonomous/user spawning, but an explicit
// user "Run" queues an on-demand request that must still fire. So in each
// engine the pause gate must sit AFTER Priority 0, not at the top — moving it
// back to the top is the regression this pins.
const dequeueFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function dequeueNextTask'));
const evalFn = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function evaluateTasks'));
// dequeueNextTask: the `if (paused) return` gate appears AFTER the on-demand
// tier (`spawnDequeuePriority0OnDemand`), and `paused` is NOT returned-on
// before it.
const dqOnDemandIdx = dequeueFn.indexOf('spawnDequeuePriority0OnDemand(ctx)');
const dqPauseGateIdx = dequeueFn.search(/if\s*\(\s*paused\s*\)\s*return/);
expect(dqOnDemandIdx, 'dequeueNextTask must invoke spawnDequeuePriority0OnDemand').toBeGreaterThan(-1);
expect(dqPauseGateIdx, 'dequeueNextTask must keep an `if (paused) return` gate').toBeGreaterThan(-1);
expect(dqPauseGateIdx, 'pause gate must come AFTER the on-demand tier').toBeGreaterThan(dqOnDemandIdx);
// evaluateTasks: Priority 0 runs unconditionally; Priorities 1+ are wrapped in
// an `if (!paused)` block that begins after spawnPriority0OnDemand.
//
// Anchor on the LAST `if (!paused)` preceding the user tier, not the first in
// the function: `evaluateTasks` legitimately carries other pause-gated work
// that runs before Priority 0 (the pending-merge sweep, which claims no agent
// lane and so must not sit behind the slot gate). A plain `.search()` matched
// that one instead and read as "the tier gate moved to the top" — a false
// positive on the exact regression this pins.
const evOnDemandIdx = evalFn.indexOf('spawnPriority0OnDemand(ctx)');
const evUserIdx = evalFn.indexOf('spawnPriority1UserTasks(ctx)');
const pauseGates = [...evalFn.matchAll(/if\s*\(\s*!\s*paused\s*\)/g)].map(m => m.index);
const evPauseGateIdx = pauseGates.filter(i => i < evUserIdx).pop() ?? -1;
expect(evOnDemandIdx, 'evaluateTasks must invoke spawnPriority0OnDemand').toBeGreaterThan(-1);
expect(evUserIdx, 'evaluateTasks must invoke spawnPriority1UserTasks').toBeGreaterThan(-1);
expect(evPauseGateIdx, 'evaluateTasks must gate the lower tiers on !paused').toBeGreaterThan(evOnDemandIdx);
expect(evUserIdx, 'user/autonomous tiers must sit inside the !paused gate').toBeGreaterThan(evPauseGateIdx);
});
it('pending-merge sweep is gated on CoS auto-run being in execute mode', () => {
// The sweep is the ONE tier in evaluateTasks that writes to a default branch
// (git.mergePR). It deliberately sits ABOVE the agent-slot gate — a merge
// claims no lane — which also puts it above `resolveAutonomyBudget`, so it
// must read the auto-run mode itself. It shipped gated on `!paused` alone,
// which meant `off` / `dry-run` still merged PRs, including on the boot-time
// `evaluateTasks({ initialStartup: true })`.
const evalFn = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function evaluateTasks'));
const sweepIdx = evalFn.indexOf('sweepPendingMergePrs()');
expect(sweepIdx, 'evaluateTasks must invoke sweepPendingMergePrs').toBeGreaterThan(-1);
// Nested recovery callbacks can have their own `if` before this call. Find
// the pause/execute gate itself and prove the merge call is inside its body,
// rather than treating the nearest textual `if` as the enclosing gate.
const gateIdx = evalFn.search(/if\s*\(\s*!\s*paused\s*&&\s*getDomainMode\(\s*state\.config\s*,\s*'cos'\s*\)\s*===\s*'execute'\s*\)/);
expect(gateIdx, 'the merge sweep must have a combined pause/execute gate').toBeGreaterThan(-1);
const gateBody = extractFnBody(evalFn, gateIdx);
expect(gateBody, 'the merge sweep must remain inside the pause/execute gate')
.toContain('sweepPendingMergePrs()');
// …and it must still run before the agent-slot early-return, or a full agent
// roster wedges the merge queue (the reason it is not folded into the tiers).
const slotGateIdx = evalFn.indexOf('if (availableSlots <= 0)');
expect(slotGateIdx, 'evaluateTasks must keep its agent-slot gate').toBeGreaterThan(-1);
expect(sweepIdx, 'the merge sweep must run before the agent-slot gate').toBeLessThan(slotGateIdx);
});
it('per-project cap defaults to global cap when unset', () => {
// The fallback `state.config.maxConcurrentAgentsPerProject || state.config.maxConcurrentAgents`
// is the safety net for older state.json files that pre-date the
// per-project cap. dequeueNextTask's capacity tracker was extracted to
// `createDequeueCapacity` in cosDequeue.js (issue #2530), so the dequeue-side
// fallback lives there now; evaluateTasks keeps its own inline copy.
const dequeueFn = extractFnBody(DEQ_SRC, DEQ_SRC.indexOf('export function createDequeueCapacity'));
const evalFn = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function evaluateTasks'));
const pattern = /maxConcurrentAgentsPerProject\s*\|\|\s*state\.config\.maxConcurrentAgents/;
expect(dequeueFn).toMatch(pattern);
expect(evalFn).toMatch(pattern);
});
it('dequeueNextTask threads the local-endpoint cap into its capacity tracker (#4834)', () => {
// The gate only works if the scheduler actually supplies the resolver and
// the running-agent tally — a refactor that drops either option silently
// reverts to unlimited local dispatch, which is what caused the accelerator
// OOM in the first place. Read from the real function body so a stray
// reference elsewhere in cos.js can't satisfy this.
const dequeueFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function dequeueNextTask'));
expect(dequeueFn).toMatch(/countRunningAgentsByLocalEndpoint\(/);
expect(dequeueFn).toMatch(/resolveLocalEndpoint:/);
expect(dequeueFn).toMatch(/localEndpointLimit:/);
});
it('tryImmediateSpawn does NOT re-implement the local-endpoint cap (#4834)', () => {
// Its task is already persisted by `addTask`, so emitting and letting the
// chokepoint hold produces exactly what an early return would. A local copy
// would be a weaker duplicate — it can only see a running-agent snapshot,
// not the in-flight reservations the authoritative gate also counts — so it
// could pass a task the chokepoint then holds, for an extra provider fetch.
const immediateFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function tryImmediateSpawn'));
expect(immediateFn).not.toMatch(/resolveLocalEndpoint\(/);
expect(immediateFn).not.toMatch(/countRunningAgentsByLocalEndpoint\(/);
});
it('subAgentSpawner holds at the chokepoint every task:ready emitter funnels through (#4834)', () => {
// dequeueNextTask is only ONE of the emitters — evaluateTasks,
// forceSpawnTask, the job scheduler and the Creative Director bridge all
// reach the spawner directly. If the gate ever moves back to the scheduler
// alone, those paths silently over-dispatch at the local GPU again.
const SPAWNER_SRC = readFileSync(join(__dirname, 'subAgentSpawner.js'), 'utf-8');
expect(SPAWNER_SRC, 'spawner must acquire a local-endpoint slot before spawning')
.toMatch(/acquireLocalEndpointSpawnSlot\(/);
// The reservation is only correct if it is released once the spawn settles;
// a missing `finally` leaks the slot and wedges the endpoint forever.
const listener = SPAWNER_SRC.slice(SPAWNER_SRC.indexOf('async function handleTaskReady'));
expect(listener, 'the acquired slot must be released in a finally')
.toMatch(/finally\s*\{\s*\n\s*localSlot\.release\(\);/);
expect(listener, 'a task at capacity must be HELD (left pending), not failed')
.toMatch(/holdTask\(task,\s*localSlot\.reason\)/);
});
it('agentLifecycle stamps the resolved endpoint onto the agent record (#4834)', () => {
// Counting a running agent by provider id alone breaks when the provider is
// edited or deleted while the agent still holds the GPU.
const DISPATCH_SRC = readFileSync(join(__dirname, 'agentSpawnDispatch.js'), 'utf-8');
expect(DISPATCH_SRC).toMatch(/providerEndpoint:\s*providerBaseUrl\(provider\)/);
});
it('forceSpawnTask refuses synchronously when the local endpoint is full (#4834)', () => {
// "Run now" returns before the spawn happens, so without its own check it
// would answer { success: true } and toast "Spawning" for a task the
// chokepoint immediately holds — the same lie the provider-resolution
// pre-check directly above it exists to prevent. It must run AFTER
// resolution so it reads the post-fallback provider.
const forceFn = extractFnBody(COS_SRC, COS_SRC.indexOf('export async function forceSpawnTask'));
expect(forceFn).toMatch(/localEndpointCapacityError\(resolution\.provider/);
expect(forceFn.indexOf('resolveAgentProviderAndModel'))
.toBeLessThan(forceFn.indexOf('localEndpointCapacityError'));
expect(forceFn.indexOf('localEndpointCapacityError'))
.toBeLessThan(forceFn.indexOf("cosEvents.emit('task:ready'"));
});
it('forceSpawnTask passes its task id so its own zombie agent is excluded (#4834)', () => {
// The route deliberately supersedes a stale `running` holder — counting that
// agent would make the recovery unreachable at a limit of 1. The exclusion
// itself is driven directly in the `readEndpointCapacity` block above; what
// that can't see is whether this caller opts into it.
const forceFn = extractFnBody(COS_SRC, COS_SRC.indexOf('export async function forceSpawnTask'));
expect(forceFn).toMatch(/localEndpointCapacityError\([^)]*taskId\)/);
});
it('the LIVE gate wires in the real availability + fallback resolvers (#4834)', () => {
// The branch logic itself is driven directly above (`resolveLocalEndpoint —
// follows the fallback swap`) through injected doubles. What no unit test
// can reach is whether the PRODUCTION context injects the real ones — if it
// ever passed its own approximation, the prediction would silently drift
// from where spawn actually sends the task.
const SLOTS_SRC = readFileSync(join(__dirname, 'cosLocalEndpointSlots.js'), 'utf-8');
expect(SLOTS_SRC, 'must use the real provider-status predicate')
.toMatch(/isAvailable:\s*isProviderAvailable/);
expect(SLOTS_SRC, 'and the real fallback resolver spawn uses')
.toMatch(/getFallbackProvider\(/);
});
it('the DESTRUCTIVE-denial tiers opt out of the local-endpoint cap (#4834)', () => {
// Priorities 0 and 3 each commit side effects before `canSpawn` and never
// persist the task, so a denial DISCARDS it rather than deferring it: the
// on-demand request is already cleared, the app-review marker is already
// bound. They emit and let the chokepoint hold.
// Priorities 1 and 2 read from persisted queues, so skipping there is a
// genuine defer — they keep the cap.
for (const tier of ['spawnDequeuePriority0OnDemand', 'spawnDequeuePriority4IdleReview']) {
const body = extractFnBody(COS_SRC, COS_SRC.indexOf(`async function ${tier}`));
expect(body, `${tier} must admit via canSpawnCommitted`).toMatch(/canSpawnCommitted\(/);
}
for (const tier of ['spawnDequeuePriority1UserTasks', 'spawnDequeuePriority2AutoApproved']) {
const body = extractFnBody(COS_SRC, COS_SRC.indexOf(`async function ${tier}`));
expect(body, `${tier} defers rather than discards — it must keep the cap`).not.toMatch(/canSpawnCommitted\(/);
}
});
it('idle generator is fenced by spawned===0 / tasksToSpawn.length===0', () => {
// Pin the strict-idle gate. If a refactor drops either fence, idle could
// spawn alongside autoSystem and double-load the agent pool.
// dequeueNextTask's idle tier (spawnDequeuePriority4IdleReview) now routes
// through the shared `isIdleTierEligible` predicate in cosDequeue.js
// (issue #2530), whose body carries the `spawned === 0` fence.
const idleTier = extractFnBody(COS_SRC, COS_SRC.indexOf('async function spawnDequeuePriority4IdleReview'));
const idlePred = extractFnBody(DEQ_SRC, DEQ_SRC.indexOf('export function isIdleTierEligible'));
// The generator engine's tiers are decomposed into named spawnPriority*
// helpers (issue #1082), so its gate lives in `spawnPriority4IdleReview`
// — scope to the whole cosTaskGenerator module (the engine).
const evalIdleTier = extractFnBody(GEN_SRC, GEN_SRC.indexOf('async function spawnPriority4IdleReview'));
expect(idleTier, 'dequeue idle tier must call the shared workflow').toMatch(/admitIdleReviewTask\(/);
expect(evalIdleTier, 'evaluate idle tier must call the shared workflow').toMatch(/admitIdleReviewTask\(/);
expect(idlePred, 'isIdleTierEligible must fence on spawned === 0 && idleReviewEnabled').toMatch(/spawned\s*===\s*0\s*&&\s*!!idleReviewEnabled/);
const idleWorkflow = extractFnBody(DEQ_SRC, DEQ_SRC.indexOf('export async function admitIdleReviewTask'));
expect(idleWorkflow).toMatch(/isIdleTierEligible\(/);
expect(idleWorkflow).toMatch(/idleReviewEnabled:\s*state\.config\.idleReviewEnabled/);
});
it('CoS auto-run domain gate (#711) fences autonomous spawns in BOTH engines', () => {
// Per-domain autonomy: the `cos` guardrail must gate every AUTOMATIC internal
// spawn path — not just the auto-approved loop. Both spawn engines
// (dequeueNextTask in cos.js, evaluateTasks in cosTaskGenerator.js) must read
// the cos mode and fence their idle / auto-approved blocks on it,
// or "off"/"dry-run" leaks autonomous agents through the un-gated engine.
// dequeueNextTask resolves the cos mode in spawnDequeuePriority2AutoApproved
// and fences its idle tier through the shared eligibility predicate
// (issue #2530) — both still live in the cos.js module, so scope to it.
const dequeueSrc = COS_SRC;
const dequeueP2 = extractFnBody(COS_SRC, COS_SRC.indexOf('async function spawnDequeuePriority2AutoApproved'));
const budgetResolver = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function resolveAutonomyBudget'));
// evaluateTasks resolves the mode in `resolveAutonomyBudget` and fences each
// autonomous tier inside its spawnPriority* helper (issue #1082) — both still
// live in the cosTaskGenerator module, so scope to the whole engine source.
const evalFn = GEN_SRC;
expect(dequeueP2, 'dequeue Priority 2 must call the shared budget resolver').toMatch(/resolveAutonomyBudget\(/);
expect(evalFn, 'evaluateTasks must call the shared budget resolver').toMatch(/resolveAutonomyBudget\(/);
expect(budgetResolver, 'the one budget resolver must read the CoS autonomy mode')
.toMatch(/getDomainMode\(state\.config, 'cos'\)/);
// evaluateTasks fences autonomous spawns inline on `cosAutonomyMode === 'execute'`.
expect(evalFn, `evaluateTasks must fence autonomous spawns on cosAutonomyMode === 'execute'`).toMatch(/cosAutonomyMode\s*===\s*['"]execute['"]/);
// Dequeue's idle tier gates through the shared predicate, and its
// auto-approved tier delegates to the same pass as evaluateTasks.
expect(dequeueSrc, `dequeueNextTask must delegate idle admission to the shared workflow`).toMatch(/admitIdleReviewTask\(/);
expect(dequeueP2, 'dequeue auto-approved tier must call the shared pass').toMatch(/admitAutoApprovedSystemTasks\(/);
expect(GEN_SRC, 'the shared pass must withhold spawns unless mode is execute').toMatch(/cosAutonomyMode\s*!==\s*['"]execute['"]/);
expect(DEQ_SRC, `cosDequeue predicates must enforce autonomyMode === 'execute'`).toMatch(/autonomyMode\s*===\s*['"]execute['"]/);
});
it('CoS auto-run domain gate (#711) covers the scheduled-job + improvement-check timers', () => {
// executeScheduledJob and the cos-improvement-check timer are a THIRD
// autonomous spawn path (outside dequeueNextTask / evaluateTasks). They must
// also respect the cos guardrail, or off/dry-run leaks scheduled-job agents
// and keeps mutating COS-TASKS.md via queueEligibleImprovementTasks.
const execFn = extractFnBody(SCHED_SRC, SCHED_SRC.indexOf('export async function executeScheduledJob'));
expect(execFn, 'executeScheduledJob must read the cos autonomy mode').toMatch(/getDomainMode\(\s*state\.config\s*,\s*['"]cos['"]\s*\)/);
expect(execFn, 'executeScheduledJob must fence on execute').toMatch(/cosAutonomyMode\s*!==\s*['"]execute['"]/);
// The autonomy-skip branch must record a gate-skip (advances lastRun) BEFORE
// re-registering — otherwise a past-due job re-registers with stale lastRun
// and refires every 1s while off/dry-run. Pin that the skip branch calls
// recordJobGateSkip ahead of registerSingleJobSchedule.
const skipBranch = execFn.slice(execFn.indexOf("cosAutonomyMode !== 'execute'"));
const recordIdx = skipBranch.indexOf('recordJobGateSkip');
const reregIdx = skipBranch.indexOf('registerSingleJobSchedule');
expect(recordIdx, 'autonomy-skip must call recordJobGateSkip').toBeGreaterThan(-1);
expect(recordIdx, 'recordJobGateSkip must precede re-registration (no 1s refire loop)').toBeLessThan(reregIdx);
// The improvement-check timer must gate its queueEligibleImprovementTasks
// call on the shared canQueueImprovementTasks predicate (idle-review +
// cos===execute), which encapsulates the auto-run domain gate.
expect(SCHED_SRC, 'improvement-check timer must gate queueing via canQueueImprovementTasks')
.toMatch(/if\s*\(\s*canQueueImprovementTasks\(\s*state\s*\)\s*\)/);
});
it('the on-demand marker discipline lives in the shared drain, not in either engine', () => {
// Per-app cooldown dedupe (one markAppReviewCooldown per cycle however many
// requests name the app) and the #978 deferred bind (bindAppReviewAgent only
// once a task exists) used to be duplicated in both Priority-0 engines and
// guarded by grepping each body. Both are pinned behaviorally in
// onDemandDrain.test.js now; what matters here is that neither engine has
// grown its own copy back.
for (const [engine, src] of [
['spawnPriority0OnDemand', GEN_SRC],
['spawnDequeuePriority0OnDemand', COS_SRC],
]) {
const fnBody = extractFnBody(src, src.indexOf(`async function ${engine}`));
expect(fnBody, `${engine} must delegate to the shared drain`).toContain('drainOnDemandRequests(');
for (const marker of ['reviewStartedApps', 'markAppReviewCooldown', 'bindAppReviewAgent']) {
expect(fnBody, `${engine} must not re-implement ${marker} — it belongs to onDemandDrain.js`)
.not.toContain(marker);
}
}
});
it('has NO handler-backed dispatch — every task type routes through the agent path', () => {
// #2322 follow-up: layered-intelligence migrated OFF the handler-backed path
// onto a normal agent task with programmatic-I/O hooks (taskTypeHooks.js). The
// queue path no longer special-cases any type: there is no in-process handler
// dispatch that bypasses the agent-spawn path, so a scheduled reasoning task is
// a visible, TUI-capable agent like everything else.
expect(GEN_SRC).not.toMatch(/dispatchHandlerBackedTask/);
expect(GEN_SRC).not.toMatch(/runHandlerBackedTaskForApp/);
expect(GEN_SRC).not.toMatch(/layeredIntelligenceHandler\.js/);
// The generator runs a task type's optional buildTaskInput hook before dispatch
// (the pre-agent programmatic slot LI's gather layer fills).
expect(GEN_SRC).toMatch(/getTaskInputHook/);
});
it('queueEligibleImprovementTasks routes through prepareManagedAppImprovementTask', () => {
// Regression guard: a 2026-05-21 incident saw two `plan-task` agents both
// open PRs for the same PLAN.md slug because the queue path was writing
// a one-line stub description with no `analysisType` / `planId`. The
// agent it dispatched got the Phase 1-7 prompt (with in-flight scan)
// stripped, picked the same slug as a sibling that already had an open
// `claim/<slug>` PR, and produced a duplicate. The fix routes the queue
// path through the shared generator so `applyPlanIdMetadata` runs and
// the full prompt + planId metadata land on the queued task.
const fnStart = GEN_SRC.indexOf('async function queueEligibleImprovementTasks');
expect(fnStart, 'queueEligibleImprovementTasks must exist').toBeGreaterThan(-1);
const fnBody = extractFnBody(GEN_SRC, fnStart);
expect(
fnBody,
'queue path must call prepareManagedAppImprovementTask so applyPlanIdMetadata runs + the full prompt is used'
).toMatch(/prepareTask\s*\(/);
expect(GEN_SRC).toContain('prepareTask = prepareManagedAppImprovementTask');
// Match the call shape, not the specific variable name — `task` could
// legitimately be renamed (e.g. `queuedTask`) in a behavior-preserving
// refactor. The contract being pinned is "raw:true addTask call to the
// internal lane," not the identifier. The options object may carry siblings
// beyond `raw:true` (e.g. `ignoreTaskId` for the perpetual refill), so don't
// require `}` immediately after `raw: true`.
expect(
fnBody,
'queue path must persist via addTask with raw:true so the enriched task object survives serialization'
).toMatch(/persistTask\s*\(\s*\w+\s*,\s*['"]internal['"]\s*,\s*\{\s*raw:\s*true\b/);
expect(GEN_SRC).toContain('persistTask = addTask');
// The old buggy path called `getTaskDescription` to build a one-line
// description and then passed app/context/approvalRequired fields to
// addTask's non-raw constructor. Pin both as absent so we can't regress.
expect(
fnBody,
'queue path must NOT use getTaskDescription (one-line stub bypasses prompt enrichment)'
).not.toMatch(/getTaskDescription\s*\(/);
// appActivity helpers must come from the file-level static import (line ~23),
// NOT a dynamic `await import('./appActivity.js')` *inside* the per-app
// loop. Dynamic imports are cached but still add an extra microtask + a
// promise allocation per iteration, and they hide the real dependency
// graph at file scope.
expect(
fnBody,
'queue path must not dynamically import ./appActivity.js inside the per-app loop'
).not.toMatch(/await\s+import\(['"]\.\/appActivity\.js['"]\)/);
// The cooldown check + lastImprovementType lookup both come from the
// same `data/app-activity.json` file. Before snapshotting, each app
// paid two separate disk reads per tick (one via `isAppOnCooldown`, one
// via `getAppActivityById`), so a 10-app install did 20 reads per
// scheduler tick. The queue path must (a) call `loadAppActivity()`
// exactly ONCE before the per-app loop and (b) drive the per-app
// cooldown gate via the pure `isAppActivityOnCooldown` predicate
// (which takes the per-app activity record from the snapshot), NOT
// the async `isAppOnCooldown` (which re-reads the file).
expect(
fnBody,
'queue path must hoist loadAppActivity() before the per-app loop'
).toMatch(/loadAppActivity\(\)/);
expect(
fnBody,
'queue path must gate cooldown via the pure isAppActivityOnCooldown predicate, not the disk-reading isAppOnCooldown'
).toMatch(/isAppActivityOnCooldown\(/);
expect(
fnBody,
'queue path must not call the disk-reading isAppOnCooldown per app'
).not.toMatch(/await\s+isAppOnCooldown\(/);
// Perpetual (drain-until-done) picks must BYPASS the per-app review cooldown
// — their work-detector park is the throttle, not the cooldown window. The
// spawn-time `markAppReviewCooldown` stamp (on-demand manual trigger +
// idle-review loop) writes `lastReviewedAt`, so without the bypass the
// back-to-back refill after a perpetual completion reads its own app as
// on-cooldown and stalls — a manually-triggered perpetual task then runs
// once instead of continuing the drain. The bypass is implemented by
// CONSTRAINING the pick to perpetual when the app is on cooldown: the
// cooldown state is computed first and passed to getNextTaskType as
// `perpetualOnly`, so in a MIXED schedule a due higher-priority cron/custom
// type can't mask the perpetual drain (which would strand the whole app for
// the window). Pin: (a) the cooldown is resolved BEFORE getNextTaskType, and
// (b) getNextTaskType is asked for a perpetual-only pick gated on cooldown.
const cooldownIdx = fnBody.indexOf('isAppActivityOnCooldown(');
const nextTypeIdx = fnBody.indexOf('getNextTaskType(');
expect(
cooldownIdx,
'queue path must compute cooldown via isAppActivityOnCooldown'
).toBeGreaterThan(-1);
expect(
cooldownIdx < nextTypeIdx,
'cooldown must be resolved BEFORE getNextTaskType so it can constrain the pick to perpetual'
).toBe(true);
expect(
fnBody,
'queue path must constrain the pick to perpetual when on cooldown (perpetualOnly gated on cooldown)'
).toMatch(/getNextTaskType\([^)]*\{\s*perpetualOnly:\s*onCooldown\s*[,}]/);
});
it('prepareManagedAppImprovementTask defers updateAppActivity until after gates', () => {
// Regression guard: the rotation pointer + "Generating improvement task"
// log must only advance when a real task is queued. The eager call at
// the top of the function was tolerable when only the on-demand path
// hit it (user explicitly picked the type), but now the per-tick queue
// path routes through it too — so every plan-task skip (no available
// slug), every precondition fail, and every reference-watch "no refs"
// exit would silently rotate the pick + emit a misleading log. Pin
// both the absence of the early call AND the presence of the gated
// late call so a future refactor can't accidentally restore the
// pre-gate ordering.
//
// Use sliceFn instead of extractFnBody because the function body
// contains a `for (...) { try { ... } catch }` block and the
// brace-balanced scanner doesn't always match the right closer when
// there are template-literal braces nested inside.
const fnStart = GEN_SRC.indexOf('async function prepareManagedAppImprovementTask');
expect(fnStart, 'prepareManagedAppImprovementTask must exist').toBeGreaterThan(-1);
const fnEnd = GEN_SRC.indexOf('\nasync function ', fnStart + 1);
const fnBody = GEN_SRC.slice(fnStart, fnEnd === -1 ? undefined : fnEnd);
// The updateAppActivity call must appear AFTER applyPlanIdMetadata —
// otherwise a `planMeta.skipReason` early-return still rotates the pointer.
const planMetaIdx = fnBody.indexOf('applyPlanIdMetadata(');
const updateActivityIdx = fnBody.indexOf('updateAppActivity(app.id,');
expect(planMetaIdx, 'applyPlanIdMetadata must appear in the function').toBeGreaterThan(-1);
expect(updateActivityIdx, 'updateAppActivity must appear in the function').toBeGreaterThan(-1);
expect(
updateActivityIdx,
'updateAppActivity must run after applyPlanIdMetadata so rotation only advances on a real queue'
).toBeGreaterThan(planMetaIdx);
// The "(on-demand)" suffix on the generation log was misleading once
// the queue path started routing through this function. Pin the suffix
// as absent.
expect(
fnBody,
'Generation log must not claim "(on-demand)" — function is shared by queue + on-demand callers'
).not.toMatch(/Generating improvement task[^`'"\n]*\(on-demand\)/);
});
it('applyPlanIdMetadata does NOT pre-stamp planId for self-claiming task types', () => {
// Regression guard: `plan-task` agents pick (and claim) their own slug at
// execution time, mirroring `/claim`. A dispatch-time pre-pick stamps a
// slug before the agent creates its `claim/<slug>` branch (the real lock),
// so two near-simultaneous dispatches both target the same first-available
// item — the exact race behind the 2026-05-21 duplicate-PR incident. The
// in-flight scan in applyPlanIdMetadata must stay (it gates dispatch), but
// the planId stamp must be fenced behind PLAN_SELF_CLAIM_TASK_TYPES.
expect(
GEN_SRC,
'plan-task must be registered as a self-claiming task type'
).toMatch(/PLAN_SELF_CLAIM_TASK_TYPES\s*=\s*new Set\(\[\s*'plan-task'\s*\]\)/);
const fnStart = GEN_SRC.indexOf('async function applyPlanIdMetadata');
expect(fnStart, 'applyPlanIdMetadata must exist').toBeGreaterThan(-1);
const fnBody = extractFnBody(GEN_SRC, fnStart);
// The planId stamp must be guarded so self-claiming types never pre-pick.
expect(
fnBody,
'metadata.planId stamp must be fenced behind a PLAN_SELF_CLAIM_TASK_TYPES check'
).toMatch(/if\s*\(\s*!PLAN_SELF_CLAIM_TASK_TYPES\.has\(taskType\)\s*\)\s*\{\s*metadata\.planId\s*=/);
// The gate (skipReason) machinery must still run — we only dropped the stamp.
expect(
fnBody,
'applyPlanIdMetadata must still scan in-flight slugs to gate dispatch'
).toMatch(/findInProgressIds\(/);
});
it('tasks:changed listener schedules dequeueNextTask before the user tryImmediateSpawn', () => {
// When task CRUD moved to cosTaskStore.js (issue-741), the addTask→
// tryImmediateSpawn and approveTask→dequeueNextTask direct calls were
// replaced by a `tasks:changed` listener here. The original sequence for a
// user-added task was: emit tasks:changed (which queued dequeueNextTask via
// this listener) FIRST, then addTask called setImmediate(tryImmediateSpawn).
// dequeue fills open slots in priority order before the just-added task's
// immediate-spawn attempt runs — so the order must stay dequeue-then-spawn.
const onIdx = COS_SRC.indexOf("cosEvents.on('tasks:changed'");
expect(onIdx, 'tasks:changed listener must exist').toBeGreaterThan(-1);
const handler = COS_SRC.slice(onIdx, COS_SRC.indexOf('});', onIdx) + 3);
// Scheduled through the shared `scheduleDequeue` wrapper (#5644) — the bare
// `setImmediate(() => dequeueNextTask())` it replaced left the rejection
// unguarded outside the request lifecycle.
const dequeueIdx = handler.indexOf('scheduleDequeue()');
const spawnIdx = handler.indexOf('tryImmediateSpawn(');
expect(dequeueIdx, 'listener must schedule dequeueNextTask').toBeGreaterThan(-1);
expect(spawnIdx, 'listener must schedule tryImmediateSpawn').toBeGreaterThan(-1);
expect(
dequeueIdx,
'dequeueNextTask must be scheduled before the user-task tryImmediateSpawn'
).toBeLessThan(spawnIdx);
// tryImmediateSpawn is user-task-only, matching the pre-extraction guard.
expect(handler).toMatch(/data\.type\s*===\s*'user'/);
});
it('tasks:changed listener leaves explicitly dispatched tasks to their caller', () => {
const onIdx = COS_SRC.indexOf("cosEvents.on('tasks:changed'");
const handler = COS_SRC.slice(onIdx, COS_SRC.indexOf('});', onIdx) + 3);
expect(handler).toMatch(/if\s*\(data\.suppressDequeue\)\s*return/);
});
// The retry-hold release (#3373) and the orphan sweep both requeue via an
// in_progress → pending flip, which cosTaskStore reports as 'requeued'. Without
// a wake here the released retry idles until an unrelated event or timer.
it('tasks:changed listener re-runs the dequeue on a requeued task', () => {
const onIdx = COS_SRC.indexOf("cosEvents.on('tasks:changed'");
const handler = COS_SRC.slice(onIdx, COS_SRC.indexOf('});', onIdx) + 3);
expect(handler).toMatch(/data\.action\s*===\s*'requeued'/);
});
// #5644 — every dequeue/immediate-spawn here is scheduled from a timer or
// setImmediate, i.e. outside the request lifecycle, where a rejection has
// nowhere to bubble: it escapes as an unhandled rejection, which
// setupProcessErrorHandlers classifies `critical` and broadcasts to every
// connected browser as `system:critical-error` — and the open agent slot the
// cycle was meant to fill stays empty until an unrelated event fires another
// one. There is no runtime seam that would catch a future contributor
// re-adding a bare `setImmediate(() => dequeueNextTask())`, so scan the source.
it('never floats a dequeueNextTask / tryImmediateSpawn schedule without a .catch', () => {
expect(
COS_SRC,
'schedule the dequeue through scheduleDequeue() so the rejection is caught'
).not.toMatch(/set(?:Immediate|Timeout)\(\(\) => dequeueNextTask\(/);
const lineStartOf = (idx) => COS_SRC.lastIndexOf('\n', idx) + 1;
const unguarded = [];
for (const name of ['dequeueNextTask', 'tryImmediateSpawn']) {
const re = new RegExp(`${name}\\(`, 'g');
let match;
while ((match = re.exec(COS_SRC)) !== null) {
const line = COS_SRC.slice(lineStartOf(match.index), COS_SRC.indexOf('\n', match.index));
if (/^\s*(?:\/\/|\*)/.test(line)) continue; // prose mention in a comment
const before = COS_SRC.slice(Math.max(0, match.index - 40), match.index);
if (/function\s+$/.test(before)) continue; // the declaration itself
if (/await\s+$/.test(before)) continue; // awaited by an async caller
// Otherwise the promise floats, so a `.catch(` must follow inside the
// same statement (before the terminating `;`).
const tail = COS_SRC.slice(match.index, match.index + 400);
if (/^[^;]*\.catch\(/s.test(tail)) continue;
unguarded.push(line.trim());
}
}
expect(unguarded, 'floated scheduler promises must be .catch-guarded').toEqual([]);
});
// A finished investigation is what releases the failure-blocked task(s) it was
// diagnosing. Without this branch the fix lands and the work it unblocked never
// runs — the task sits `blocked` until a human notices or the 14-day reaper
// quietly auto-expires it.
it('tasks:changed listener hands a completed task to the investigation auto-retry', () => {
const onIdx = COS_SRC.indexOf("cosEvents.on('tasks:changed'");
const handler = COS_SRC.slice(onIdx, COS_SRC.indexOf('});', onIdx) + 3);
expect(handler).toMatch(/data\.task\?\.status\s*===\s*'completed'/);
expect(handler).toMatch(/retryTasksResolvedByInvestigation\(data\.task\)/);
});
});
describe('resetOrphanedTasks — latest run outcome (#12057)', () => {
let taskStore;
let agentManagement;
const taskId = 'task-rerun';
const older = {
id: 'agent-older', taskId, status: 'completed', result: { success: true },
startedAt: '2026-01-01T00:00:00Z', completedAt: '2026-01-01T00:01:00Z',
};
const latest = {
id: 'agent-latest', taskId, status: 'completed', result: { success: false },
startedAt: '2026-01-01T01:00:00Z', completedAt: '2026-01-01T01:01:00Z',
metadata: { worktreePath: '/synthetic/resume-worktree', branch: 'resume-branch' },
};
beforeEach(async () => {
const state = await import('./cosState.js');
taskStore = await import('./cosTaskStore.js');
const identity = await import('./instanceIdentity.js');
agentManagement = await import('./agentManagement.js');
// Put the older run last in the map: chronology, not insertion order,
// determines which run can settle this task.
vi.spyOn(state, 'loadState').mockResolvedValue({ agents: { latest, older } });
vi.spyOn(identity, 'ensureInstanceId').mockResolvedValue('synthetic-instance');
vi.spyOn(taskStore, 'getAllTasks').mockResolvedValue({
user: { grouped: { in_progress: [{ id: taskId, status: 'in_progress', metadata: {} }] } },
cos: { grouped: {} },
});
vi.spyOn(taskStore, 'updateTask').mockResolvedValue({});
vi.spyOn(agentManagement, 'handleOrphanedTask').mockResolvedValue({});
vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-01-01T02:00:00Z'));
});
afterEach(() => vi.restoreAllMocks());
it.each([false, true])('leaves durable cleanup handoffs to verification during boot=%s', async bootRecovery => {
taskStore.getAllTasks.mockResolvedValue({ user: { grouped: { in_progress: [{ id: taskId,
status: 'in_progress', metadata: { deliveryRecovery: 'cleanup', deliveryRecoveryAgentId: latest.id } }] } }, cos: { grouped: {} } });
await resetOrphanedTasks({ bootRecovery });
expect(taskStore.updateTask).not.toHaveBeenCalled();
expect(agentManagement.handleOrphanedTask).not.toHaveBeenCalled();
});
it('recovers the latest failed rerun despite an older successful run', async () => {
await resetOrphanedTasks();
expect(taskStore.updateTask).not.toHaveBeenCalled();
expect(agentManagement.handleOrphanedTask).toHaveBeenCalledExactlyOnceWith(
taskId, latest.id, taskStore.getTaskById,
{ agentMetadata: latest.metadata, agentStartedAt: latest.startedAt }
);
});
it('completes a missed task update when the latest run succeeded', async () => {
const state = await import('./cosState.js');
state.loadState.mockResolvedValue({ agents: { latest: { ...latest, result: { success: true } }, older } });
await resetOrphanedTasks();
expect(taskStore.updateTask).toHaveBeenCalledExactlyOnceWith(taskId, { status: 'completed' }, 'user');
expect(agentManagement.handleOrphanedTask).not.toHaveBeenCalled();
});
});
// A failed run's retry is held non-spawnable (`in_progress` + marker) while its
// worktree cleanup resolves the resume pointer (#3373). The boot/health-check
// sweep walks in_progress tasks, so it must leave a LIVE hold alone — requeueing
// there would resolve the pointer against a branch mid-merge — and must hand a
// STALE one (the process that armed it died) to handleOrphanedTask, which
// finishes the transition.
describe('resetOrphanedTasks — retry holds (#3373)', () => {
const sweepFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function resetOrphanedTasks'));
it('skips a held task until its hold goes stale', () => {
expect(sweepFn, 'the sweep must consult the retry hold')
.toMatch(/const recoverHold = held && \(bootRecovery \|\| isStaleRetryHold\(task\.metadata\)\)/);
expect(sweepFn, 'a live hold must skip the task').toMatch(/if \(held && !recoverHold\)/);
const guardIdx = sweepFn.indexOf('const held = isRetryHeld(task.metadata)');
const handlerIdx = sweepFn.indexOf('handleOrphanedTask(');
expect(guardIdx, 'the hold guard must run before the orphan handler').toBeGreaterThan(-1);
expect(guardIdx, 'the hold guard must run before the orphan handler').toBeLessThan(handlerIdx);
});
// Nothing can be mid-cleanup on the startup pass, so a hold left by the process
// that died is recovered immediately rather than idling out its grace window.
it('recovers a held task immediately on the boot pass', () => {
expect(COS_SRC).toMatch(/resetOrphanedTasks\(\{\s*bootRecovery:\s*true\s*\}\)/);
expect(sweepFn).toMatch(/bootRecovery\s*=\s*false/);
});
// The hold is armed AFTER completeAgent, so a crash-restart inside the 60s
// recently-completed grace would otherwise skip exactly the task the boot pass
// exists to recover, stranding it until the 15-minute periodic sweep.
it('lets a recoverable hold bypass the recently-completed grace', () => {
const holdIdx = sweepFn.indexOf('const recoverHold =');
const graceIdx = sweepFn.indexOf('recentlyCompletedTaskIds.has(task.id)');
expect(holdIdx, 'the hold must be evaluated before the recently-completed grace').toBeLessThan(graceIdx);
expect(sweepFn).toMatch(/if \(!recoverHold && recentlyCompletedTaskIds\.has\(task\.id\)\)/);
});
});
describe('forceSpawnTask — pre-validate provider before task:ready', () => {
// The play button on a pending task calls forceSpawnTask, which emits
// `task:ready`; the actual spawn happens asynchronously in a listener. If
// provider/model resolution fails there (e.g. the task is pinned to an
// `api`-type provider with no file-writing harness), the spawn bails
// silently and the task stays `pending` — but the HTTP call had already
// returned `{ success: true }` and the UI toasted "Spawning". Pin that
// forceSpawnTask resolves the provider FIRST and returns the resolution
// error (so the route surfaces a truthful 400) instead of emitting
// `task:ready` on a doomed spawn.
const forceFn = extractFnBody(COS_SRC, COS_SRC.indexOf('export async function forceSpawnTask'));
it('calls resolveAgentProviderAndModel and returns its error', () => {
expect(forceFn, 'forceSpawnTask must pre-resolve the provider/model')
.toMatch(/resolveAgentProviderAndModel\(\s*task\s*\)/);
expect(forceFn, 'forceSpawnTask must return the resolution error on failure')
.toMatch(/if\s*\(\s*!\s*resolution\.ok\s*\)\s*\{\s*return\s*\{\s*error:\s*resolution\.error\s*\}/);
});
it('bails on a failed resolution BEFORE emitting task:ready', () => {
const resolveIdx = forceFn.indexOf('resolveAgentProviderAndModel');
const readyIdx = forceFn.indexOf("cosEvents.emit('task:ready'");
expect(resolveIdx, 'resolution must happen in forceSpawnTask').toBeGreaterThan(-1);
expect(readyIdx, 'forceSpawnTask must still emit task:ready on success').toBeGreaterThan(-1);
expect(resolveIdx, 'provider resolution must precede the task:ready emit')
.toBeLessThan(readyIdx);
});
// Same failure mode, two more sources of a doomed spawn. A stopped daemon was
// never checked at all (only `paused` was), and in runner mode the spawn path
// now HOLDS the task while the cos-runner app is down instead of failing it —
// right for the autonomous queue, wrong for an explicit "Run now", which would
// get `{ success: true }` and a "Spawning" toast for a task that quietly stays
// pending. Both must answer with an actionable error instead.
it('refuses to force-spawn while the daemon is stopped', () => {
const stoppedIdx = forceFn.indexOf('!isDaemonRunning()');
expect(stoppedIdx, 'forceSpawnTask must check that the daemon is running').toBeGreaterThan(-1);
expect(stoppedIdx, 'the stopped check must precede the task:ready emit')
.toBeLessThan(forceFn.indexOf("cosEvents.emit('task:ready'"));
});
it('refuses to force-spawn while the runner is holding', () => {
const holdIdx = forceFn.indexOf('isRunnerHolding');
expect(holdIdx, 'forceSpawnTask must consult the runner hold').toBeGreaterThan(-1);
expect(holdIdx, 'the runner check must precede the task:ready emit')
.toBeLessThan(forceFn.indexOf("cosEvents.emit('task:ready'"));
});
// spawnAgentForTask registers its agent as `running` BEFORE flipping the task
// off `pending`, so the `status !== 'pending'` check above still passes for the
// seconds between those two writes. Without a live-agent check, a "Run now"
// landing there answers `{ success: true }` and toasts "Spawning" for a second
// dispatch that withSpawnDedupGuard then silently drops.
it('refuses a task a running agent already holds', () => {
const holderIdx = forceFn.indexOf('spawningAgentForTask(taskId, runningAgents)');
expect(holderIdx, 'forceSpawnTask must reject a task a running agent holds')
.toBeGreaterThan(-1);
expect(forceFn, 'the refusal must name the agent that holds it')
.toContain('is already running this task');
expect(holderIdx, 'the live-agent check must precede the task:ready emit')
.toBeLessThan(forceFn.indexOf("cosEvents.emit('task:ready'"));
});
// ...but only while that agent is plausibly still mid-spawn. Outside the window,
// a `pending` task carrying a `running` agent is a zombie record — and this
// route never runs cleanupZombieAgents — so an unbounded refusal would turn the
// task's own recovery action into a permanent no-op.
it('bounds the refusal so a stale holder can still be superseded', () => {
// The bound now lives in lib/cosSpawnWindow.js, shared with the status
// counters and the task lists — so the pending LIST that renders the "Run
// now" button and the refusal behind it agree about which holders are stale.
expect(forceFn, 'the holder refusal must go through the age-bounded settlement')
.toMatch(/spawningAgentForTask\(taskId, runningAgents\)/);
expect(forceFn, 'a stale holder must fall through to the spawn, not return')
.toMatch(/const holder = runningAgents\.get\(taskId\);/);
expect(COS_SRC, 'the bound must come from the shared settlement, not a local copy')
.toMatch(/spawningAgentForTask[\s\S]*?from '\.\.\/lib\/cosSpawnWindow\.js'/);
expect(COS_SRC, 'no second grace window may be declared here')
.not.toMatch(/const SPAWN_CLAIM_GRACE_MS = /);
expect(SPAWN_WINDOW_SRC, 'the grace window must be defined')
.toMatch(/export const SPAWN_CLAIM_GRACE_MS = /);
});
});
describe('the runner-down hold — spawn-side gates', () => {
// Dispatch holds a task while the cos-runner app is down (the `task:ready`
// listener in subAgentSpawner.js, covered behaviorally in
// subAgentSpawner.runnerHold.test.js). The dequeue must ALSO bail before its
// priority tiers run: they drain on-demand requests, advance review cooldowns,
// bind the synthetic app-review marker, and spend `capacity` — side effects a
// downstream hold cannot take back.
const dequeueFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function dequeueNextTask'));
it('bails on the runner hold before doing any tier work', () => {
const holdIdx = dequeueFn.indexOf('isRunnerHolding');
expect(holdIdx, 'dequeueNextTask must consult the runner hold').toBeGreaterThan(-1);
expect(holdIdx, 'the hold must be checked before capacity is computed')
.toBeLessThan(dequeueFn.indexOf('createDequeueCapacity'));
});
it('gates the immediate user-task spawn on the same predicate', () => {
const immediateFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function tryImmediateSpawn'));
expect(immediateFn).toMatch(/isRunnerHolding/);
});
// Direct mode has no runner to be down; probing there would hold every spawn
// on an install that never runs the cos-runner app.
it('is a no-op in direct mode', () => {
const holdFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function isRunnerHolding'));
expect(holdFn).toMatch(/if\s*\(!useRunner\)\s*return false/);
});
});
describe('addTask — first-line dedup', () => {
it('returns the first non-empty trimmed line', () => {
expect(firstLine('hello\nworld')).toBe('hello');
expect(firstLine('\n\n first \nsecond')).toBe('first');
expect(firstLine('single')).toBe('single');
});
it('returns empty string for null/undefined/empty input', () => {
expect(firstLine(null)).toBe('');
expect(firstLine(undefined)).toBe('');
expect(firstLine('')).toBe('');
expect(firstLine('\n\n\n')).toBe('');
});
it('multi-line and single-line descriptions with the same first line collide', () => {
// Repro: handleOrphanedTask builds a multi-line description, but
// generateTasksMarkdown flattens it to one line. Without first-line
// normalization, addTask's dedup compares the full multi-line input to
// the stored single line and never matches — producing N duplicate
// [Auto-Fix] tasks, each spawning its own agent.
const multi = '[Auto-Fix] Investigate repeated agent orphaning for task X\n\n**Last Orphaned Agent**: agent-aaa';
const stored = '[Auto-Fix] Investigate repeated agent orphaning for task X';
expect(firstLine(multi).toLowerCase()).toBe(firstLine(stored).toLowerCase());
});
// The addTask source-level regression guards (firstLine dedup + per-app
// dedup scope) moved to cosTaskStore.test.js when addTask was extracted into
// cosTaskStore.js. The firstLine behavioral tests above stay here because
// cos.js still re-exports firstLine for backward compat.
});
// ─── Perpetual re-queue on completion (drain back-to-back) ─────────────────
//
// Perpetual schedules (e.g. claim-issue) are documented as "drain actionable
// work back-to-back (re-queue on completion)" (taskSchedule.js), but the only
// thing that queues them is the ~hourly cos-improvement-check timer — the
// agent:completed handler (dequeueNextTask) merely drains already-queued tasks
// and never regenerates perpetual work. A "ready" perpetual task doesn't even
// shorten that timer (cosJobScheduler only gates the delay on status:'scheduled'
// tasks), so when claim-issue is the only enabled schedule the next run waits up
// to MAX_CHECK_INTERVAL (1h) instead of spawning immediately after the prior one.
//
// `isPerpetualRefillCandidate` is the pure gate that lets the completion handler
// decide whether the just-finished agent belongs to a perpetual schedule that
// should be refilled right now.
describe('isPerpetualRefillCandidate — perpetual drain on completion', () => {
const schedule = {
tasks: {
'claim-issue': { type: 'on-demand', perpetual: true, enabled: true },
'claim-issue-disabled': { type: 'on-demand', perpetual: true, enabled: false },
// A cron cadence carrying the same flag drains identically — the lane is
// chosen by `perpetual`, never by the cadence type or the task's name.
'branch-reconcile': { type: 'cron', cronExpression: '0 3 * * *', perpetual: true, enabled: true },
'plan-task': { type: 'cron', cronExpression: '0 7 * * *', enabled: true },
},
};
const agentFor = (analysisType, key = 'taskAnalysisType') => ({
metadata: analysisType == null ? {} : { [key]: analysisType },
});
it('is true for an enabled perpetual type matching the agent task', () => {
expect(isPerpetualRefillCandidate(agentFor('claim-issue'), schedule)).toBe(true);
});
it('is false for a disabled perpetual type (toggled off after spawn)', () => {
expect(isPerpetualRefillCandidate(agentFor('claim-issue-disabled'), schedule)).toBe(false);
});
it('is false for a non-perpetual schedule type', () => {
expect(isPerpetualRefillCandidate(agentFor('plan-task'), schedule)).toBe(false);
});
it('is true for an enabled cron-scheduled perpetual drain', () => {
expect(isPerpetualRefillCandidate(agentFor('branch-reconcile'), schedule)).toBe(true);
});
it('is false for an unknown / unscheduled type', () => {
expect(isPerpetualRefillCandidate(agentFor('ghost-type'), schedule)).toBe(false);
});
it('reads the analysis type from metadata.analysisType and selfImprovementType fallbacks', () => {
expect(isPerpetualRefillCandidate(agentFor('claim-issue', 'analysisType'), schedule)).toBe(true);
expect(isPerpetualRefillCandidate(agentFor('claim-issue', 'selfImprovementType'), schedule)).toBe(true);
});
it('is false for missing agent / metadata / schedule (no throw)', () => {
expect(isPerpetualRefillCandidate(null, schedule)).toBe(false);
expect(isPerpetualRefillCandidate(agentFor(null), schedule)).toBe(false);
expect(isPerpetualRefillCandidate(agentFor('claim-issue'), null)).toBe(false);
expect(isPerpetualRefillCandidate(agentFor('claim-issue'), { tasks: null })).toBe(false);
});
});
// `perpetualRefillPlan` chooses which lane a completed perpetual run continues
// in. The load-bearing case: a MANUAL "Run Now" drain (metadata.taskOnDemand)
// must continue in the user-initiated on-demand lane — gated on the master
// Improve flag, NOT canQueueImprovementTasks — so it keeps draining even when
// CoS auto-run is off/dry-run or idle-review is off (the postures in which the
// user reaches for "Run Now" and the manual run is allowed to START but the
// auto-run-gated queue lane would otherwise stall the drain after one item).
describe('perpetualRefillPlan — manual vs scheduled drain lane', () => {
const schedule = {
tasks: {
'claim-issue': { type: 'on-demand', perpetual: true, enabled: true },
'claim-issue-disabled': { type: 'on-demand', perpetual: true, enabled: false },
// A cron cadence carrying the same flag drains identically — the lane is
// chosen by `perpetual`, never by the cadence type or the task's name.
'branch-reconcile': { type: 'cron', cronExpression: '0 3 * * *', perpetual: true, enabled: true },
'plan-task': { type: 'cron', cronExpression: '0 7 * * *', enabled: true },
},
};
const agent = (metadata) => ({ metadata });
it('routes a scheduled perpetual run to the auto-run-gated queue lane', () => {
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'claim-issue' }), schedule))
.toEqual({ lane: 'queue' });
});
it('routes a MANUAL (on-demand) perpetual run to the on-demand lane, carrying type + app', () => {
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true, taskApp: 'app-42' }),
schedule,
)).toEqual({ lane: 'onDemand', taskType: 'claim-issue', appId: 'app-42' });
});
it('does not refill an app-less branch-reconcile drain (its completion has no repository target)', () => {
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'branch-reconcile', taskOnDemand: true, taskApp: null }), schedule))
.toEqual({ lane: 'skip' });
});
it('routes a cron-scheduled perpetual drain to the on-demand lane when the run was manual', () => {
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'branch-reconcile', taskOnDemand: true, taskApp: 'app-1' }),
schedule,
)).toEqual({ lane: 'onDemand', taskType: 'branch-reconcile', appId: 'app-1' });
});
it('continues a manual branch sweep with recurring dispatch disabled, preserving other one-shot boundaries', () => {
const oneShot = { tasks: { 'branch-reconcile': { enabled: true, perpetual: false } } };
const manual = { taskAnalysisType: 'branch-reconcile', taskOnDemand: true, taskApp: 'app-1' };
for (const taskOnDemandOrigin of ['user', 'refill']) {
expect(perpetualRefillPlan(agent({ ...manual, taskOnDemandOrigin }), oneShot))
.toEqual({ lane: 'onDemand', taskType: 'branch-reconcile', appId: 'app-1' });
}
for (const taskOnDemandOrigin of ['quota-burn', 'unknown']) {
expect(perpetualRefillPlan(agent({ ...manual, taskOnDemandOrigin }), oneShot)).toEqual({ lane: 'skip' });
}
expect(perpetualRefillPlan(agent({ ...manual, taskOnDemand: false }), oneShot)).toEqual({ lane: 'skip' });
oneShot.tasks['branch-reconcile'].enabled = false;
expect(perpetualRefillPlan(agent(manual), oneShot)).toEqual({ lane: 'skip' });
});
it('a manual run with no app resolves appId to null (global on-demand re-issue)', () => {
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true }),
schedule,
)).toEqual({ lane: 'onDemand', taskType: 'claim-issue', appId: null });
});
it('does not refill a run that was narrowed to one pull request', () => {
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true, taskApp: 'app-42', taskTargetPullRequest: 17 }),
schedule,
)).toEqual({ lane: 'skip' });
});
it('does not refill a QUOTA BURN run — a burn invokes exactly one unit', () => {
// The burn has its own continuation (quotaBurnRunner#onBurnAgentCompleted)
// behind the window/reserve/cap ladder. Letting the perpetual drain refill
// too would walk the whole backlog outside every one of those gates, on the
// very subscription the plan was rationing.
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskApp: 'app-42', taskOnDemand: true, taskOnDemandOrigin: 'quota-burn' }),
schedule,
)).toEqual({ lane: 'skip' });
});
it('does not refill an UNKNOWN on-demand origin either — the lane allowlist fails closed', () => {
// The rule is an allowlist, not a list of exclusions: an automated origin
// added later must stop after one unit by default rather than silently
// acquiring a human Run's drain.
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true, taskOnDemandOrigin: 'some-future-automation' }),
schedule,
)).toEqual({ lane: 'skip' });
});
it('treats an unrecorded origin as a human Run (tasks queued before the field existed)', () => {
expect(perpetualRefillPlan(
agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true, taskApp: 'app-42' }),
schedule,
)).toEqual({ lane: 'onDemand', taskType: 'claim-issue', appId: 'app-42' });
});
it('skips a non-candidate even when it is marked on-demand (disabled / non-perpetual / unknown)', () => {
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'claim-issue-disabled', taskOnDemand: true }), schedule))
.toEqual({ lane: 'skip' });
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'plan-task', taskOnDemand: true }), schedule))
.toEqual({ lane: 'skip' });
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'ghost', taskOnDemand: true }), schedule))
.toEqual({ lane: 'skip' });
});
it('resolves the on-demand type from the analysisType / selfImprovementType fallbacks', () => {
expect(perpetualRefillPlan(agent({ analysisType: 'claim-issue', taskOnDemand: true }), schedule).lane)
.toBe('onDemand');
expect(perpetualRefillPlan(agent({ selfImprovementType: 'claim-issue', taskOnDemand: true }), schedule).lane)
.toBe('onDemand');
});
it('never throws on missing agent / metadata / schedule', () => {
expect(perpetualRefillPlan(null, schedule)).toEqual({ lane: 'skip' });
expect(perpetualRefillPlan(agent({}), schedule)).toEqual({ lane: 'skip' });
expect(perpetualRefillPlan(agent({ taskAnalysisType: 'claim-issue', taskOnDemand: true }), null))
.toEqual({ lane: 'skip' });
});
});
// Source-level guard: the agent:completed handler must wire the perpetual
// refill so completion drains back-to-back instead of waiting for the hourly
// improvement-check timer.
describe('cos.js source — agent:completed triggers perpetual refill', () => {
it("the agent:completed listener invokes the perpetual refill path", () => {
const onIdx = COS_SRC.indexOf("cosEvents.on('agent:completed'");
expect(onIdx, 'agent:completed listener must exist').toBeGreaterThan(-1);
const recoveryIdx = COS_SRC.indexOf('await settleRetirementReviewRun(agent)', onIdx);
expect(recoveryIdx).toBeGreaterThan(onIdx);
expect(recoveryIdx).toBeLessThan(COS_SRC.indexOf('refillPerpetualForCompletedAgent(agent)', onIdx));
const completionIdx = COS_SRC.indexOf('await settleBranchReconcileRun(agent)', onIdx);
expect(completionIdx).toBeGreaterThan(onIdx);
expect(completionIdx).toBeLessThan(COS_SRC.indexOf('refillPerpetualForCompletedAgent(agent)', onIdx));
const handlerSlice = COS_SRC.slice(onIdx, onIdx + 1600);
expect(
handlerSlice.includes('refillPerpetualForCompletedAgent'),
'agent:completed handler must call refillPerpetualForCompletedAgent'
).toBe(true);
});
it('the refill passes the completed task id as ignoreTaskId (avoids the completeAgent-before-updateTask dedup race)', () => {
// agent:completed fires before the completion flow's updateTask marks the task
// done, so the just-finished task can still read as in_progress — both in the
// snapshot AND on disk when queueEligible's addTask re-reads COS-TASKS.md. A
// perpetual schedule regenerates an identical first-line per app, so without
// excluding the completing task the refill is rejected as a duplicate and the
// drain stalls. Pin the ignoreTaskId thread so a refactor can't reintroduce it.
const fnIdx = COS_SRC.indexOf('async function refillPerpetualForCompletedAgent');
expect(fnIdx, 'refillPerpetualForCompletedAgent must exist').toBeGreaterThan(-1);
const fnSlice = COS_SRC.slice(fnIdx, COS_SRC.indexOf('\n}', fnIdx));
expect(
/queueEligibleImprovementTasks\(\s*state\s*,\s*cosTaskData\s*,\s*\{[\s\S]*?ignoreTaskId:\s*agent\?\.taskId[\s\S]*?\}\s*\)/.test(fnSlice),
'refill must forward ignoreTaskId: agent?.taskId to queueEligibleImprovementTasks'
).toBe(true);
});
it('a MANUAL (on-demand) drain continues via queuePerpetualRefill under isImprovementEnabled, returning before the auto-run queue lane', () => {
// The bug fixed here: a "Run Now" perpetual drain is allowed to START in a
// posture where canQueueImprovementTasks is false (auto-run off/dry-run or
// idle-review off), but the scheduled queue lane refuses to continue it —
// stalling the drain after one item. The manual lane must instead re-issue an
// on-demand request (scoped to the same type+app) under the same
// isImprovementEnabled gate the manual trigger used, and RETURN before the
// queueEligibleImprovementTasks path. Assert the ordering rather than the
// absence of a keyword in a comment (fragile): Improve gate → re-issue →
// return → (only then) the queue lane.
const fnIdx = COS_SRC.indexOf('async function refillPerpetualForCompletedAgent');
const fnSlice = COS_SRC.slice(fnIdx, COS_SRC.indexOf('\n}', fnIdx));
expect(
fnSlice.includes('const plan = perpetualRefillPlan(agent, schedule)'),
'refill must resolve the lane via perpetualRefillPlan'
).toBe(true);
expect(/plan\.lane === 'onDemand'/.test(fnSlice), 'refill must branch on the on-demand lane').toBe(true);
const improveGateIdx = fnSlice.indexOf("if (!isImprovementEnabled(state)) return interrupted('improvement-disabled');");
// queuePerpetualRefill owns the non-emitting REFILL pair so the on-demand
// engines do NOT clear the drain's park / convergence signature / dispatch
// counter on its behalf.
const triggerMatch = /queuePerpetualRefill\(plan\.taskType, plan\.appId\)/.exec(fnSlice);
const triggerIdx = triggerMatch ? triggerMatch.index : -1;
const queueIdx = fnSlice.indexOf('queueEligibleImprovementTasks(state, cosTaskData');
expect(improveGateIdx, 'manual lane must gate on isImprovementEnabled').toBeGreaterThan(-1);
expect(triggerIdx, 'manual lane must re-issue via queuePerpetualRefill(plan.taskType, plan.appId)').toBeGreaterThan(-1);
expect(queueIdx, 'scheduled queue lane must still exist').toBeGreaterThan(-1);
// Improve gate precedes the re-issue; the manual lane returns before the queue lane.
expect(improveGateIdx).toBeLessThan(triggerIdx);
expect(triggerIdx).toBeLessThan(queueIdx);
const returnAfterTrigger = fnSlice.indexOf('return;', triggerIdx);
expect(returnAfterTrigger, 'manual lane must return before falling through to the queue lane').toBeGreaterThan(-1);
expect(returnAfterTrigger).toBeLessThan(queueIdx);
});
it('the dequeue on-demand engine hands its ignoreTaskId to the shared drain', () => {
// The completion-triggered re-issue must be dedup-safe against the
// still-in_progress completing task, so the dequeue engine forwards its
// ignoreTaskId into the addTask options the shared drain applies. That
// forwarding is one of the three real differences between the engines, and
// both sides of it are pinned behaviorally in onDemandDrain.test.js.
const engIdx = COS_SRC.indexOf('async function spawnDequeuePriority0OnDemand');
expect(engIdx, 'spawnDequeuePriority0OnDemand must exist').toBeGreaterThan(-1);
const engBody = extractFnBody(COS_SRC, engIdx);
expect(
/addTaskOptions:\s*\{\s*ignoreTaskId\s*\}/.test(engBody),
'the dequeue engine must pass ignoreTaskId through addTaskOptions'
).toBe(true);
});
it('an unexpired park stops the refill BEFORE it re-issues the drain (#3848)', () => {
// The invariant that was missing: park elapse was read only by the SCHEDULED
// lane, so a drain that had just parked itself (idle detector / no-progress /
// drain cap) was still re-issued on the very next completion — the park meant
// nothing on the one lane that does the re-dispatching. A human "Run Now" is
// unaffected: applyOnDemandRunResets clears the park for a USER-origin request
// before this lane is ever reached.
const fnIdx = COS_SRC.indexOf('async function refillPerpetualForCompletedAgent');
const fnSlice = COS_SRC.slice(fnIdx, COS_SRC.indexOf('\n}', fnIdx));
const parkIdx = fnSlice.indexOf('isPerpetualParkActive(plan.taskType, plan.appId)');
const triggerIdx = fnSlice.indexOf('queuePerpetualRefill(plan.taskType, plan.appId');
expect(parkIdx, 'refill must consult the type+app park before re-issuing').toBeGreaterThan(-1);
expect(parkIdx).toBeLessThan(triggerIdx);
const returnAfterPark = fnSlice.indexOf('return;', parkIdx);
expect(returnAfterPark, 'a live park must return, not fall through to the re-issue').toBeLessThan(triggerIdx);
});
it('the refill only fires on a SUCCESSFUL completion (no back-to-back spin on failures)', () => {
// Perpetual completions skip the per-app cooldown, so refilling after a failed
// run would spin the daemon through repeated failures (the work-detector still
// sees the same issue as actionable). The refill must bail on a non-success
// result and let task-retry/backoff + the recheck cadence handle failures.
const fnIdx = COS_SRC.indexOf('async function refillPerpetualForCompletedAgent');
const fnSlice = COS_SRC.slice(fnIdx, COS_SRC.indexOf('\n}', fnIdx));
expect(
/if\s*\(\s*!agent\?\.result\?\.success\s*\)\s*return/.test(fnSlice),
'refill must early-return when the completed agent did not succeed'
).toBe(true);
});
it('refill is sequenced BEFORE dequeue in the handler (perpetual task queued before slots fill)', () => {
// If generic dequeue ran first (or concurrently), it could claim the just-
// freed slot with idle-review work before the perpetual task is queued,
// breaking the back-to-back drain. The handler must chain refill → dequeue.
const onIdx = COS_SRC.indexOf("cosEvents.on('agent:completed'");
const handlerSlice = COS_SRC.slice(onIdx, COS_SRC.indexOf('// Create notification when a daily briefing completes', onIdx));
expect(
/refillPerpetualForCompletedAgent\(agent\)[\s\S]*\.then\(\s*\(\)\s*=>\s*dequeueNextTask\(/.test(handlerSlice),
'handler must run dequeueNextTask in a .then() AFTER the refill resolves'
).toBe(true);
// Both generators on this continuation must skip the completing task, which
// still reads pending/in_progress until updateTask settles it (#3179): the
// refill excludes it via queueEligibleImprovementTasks, and the dequeue's
// idle-review tier via this argument.
expect(
/dequeueNextTask\(\{\s*ignoreTaskId:\s*agent\?\.taskId\s*\}\)/.test(handlerSlice),
'the post-refill dequeue must pass the completing task id as ignoreTaskId'
).toBe(true);
// The old standalone `setImmediate(() => dequeueNextTask())` must be gone —
// its presence would race the refill.
expect(
handlerSlice.includes('setImmediate(() => dequeueNextTask())'),
'the unconditional pre-refill dequeue must be removed'
).toBe(false);
});
});
// Shared autonomous-queuing gate (cosState.canQueueImprovementTasks). Extracted
// from three drift-prone copies (post-startup queue, improvement-check timer,
// perpetual drain refill). Queuing requires BOTH idle-review on AND the CoS
// auto-run domain in `execute`.
describe('canQueueImprovementTasks — autonomous queuing gate', () => {
const cfg = (idleReviewEnabled, cos) => ({
config: { idleReviewEnabled, domainAutonomy: { cos } },
});
it('is true only when idle-review is on AND cos auto-run is execute', () => {
expect(canQueueImprovementTasks(cfg(true, 'execute'))).toBe(true);
});
it('is false when cos auto-run is off or dry-run', () => {
expect(canQueueImprovementTasks(cfg(true, 'off'))).toBe(false);
expect(canQueueImprovementTasks(cfg(true, 'dry-run'))).toBe(false);
});
it('is false when idle-review is disabled, regardless of cos mode', () => {
expect(canQueueImprovementTasks(cfg(false, 'execute'))).toBe(false);
});
it('coerces a falsy/undefined idleReviewEnabled to a boolean false', () => {
expect(canQueueImprovementTasks(cfg(undefined, 'execute'))).toBe(false);
});
});
describe('persistent mind — default-off CoS state integration (#5064)', () => {
it('adds no cold-bootstrap provider work to a fresh CoS state', () => {
expect(DEFAULT_STATE.persistentMind).toMatchObject({
schemaVersion: PERSISTENT_MIND_SCHEMA_VERSION,
mindId: 'cos-persistent-mind',
enabled: false,
started: false,
status: 'disabled',
queuedMessages: [],
activeTurn: null,
});
});
it('suspends and re-arms the mind when the CoS autonomy mode changes', () => {
const updateFn = extractFnBody(COS_SRC, COS_SRC.indexOf('export async function updateConfig'));
expect(updateFn).toMatch(/mode === 'execute'[\s\S]*handlePersistentMindGlobalResume\(\)/);
expect(updateFn).toMatch(/handlePersistentMindGlobalPause\(`CoS autonomy changed to \$\{mode\}`\)/);
});
});
describe('pending-merge sweep — own timer, not the evaluation cadence (#3630)', () => {
// Evaluation is event-driven (cosState.js records that the periodic
// evaluateTasks timer was removed), so the drain inside evaluateTasks fires
// roughly once per restart. The cadence-bearing drain is a CoS interval job.
const sweepBlock = COS_SRC.slice(
COS_SRC.indexOf("id: 'cos-pending-merge-sweep'"),
COS_SRC.indexOf("id: 'cos-pending-merge-sweep'") + 1400
);
it('registers a cos-pending-merge-sweep interval job alongside the other CoS timers', () => {
expect(COS_SRC).toMatch(/id:\s*'cos-pending-merge-sweep'/);
expect(sweepBlock).toMatch(/type:\s*'interval'/);
expect(sweepBlock).toMatch(/sweepPendingMergePrs\(\)/);
});
it('drives the interval off PENDING_MERGE_SWEEP_INTERVAL_MS, not a local literal', () => {
expect(sweepBlock).toMatch(/intervalMs:\s*PENDING_MERGE_SWEEP_INTERVAL_MS/);
expect(COS_SRC).toMatch(/\{\s*PENDING_MERGE_SWEEP_INTERVAL_MS\b[^}]*\}\s*=\s*await import\('\.\/prWatcher\.js'\)/);
});
it('gates the sweep and the handoff follow-up poll on !paused AND cos auto-run === execute', () => {
expect(sweepBlock).toMatch(/if \(await pendingMergeSweepBlocked\(\)\) return;/);
expect(COS_SRC).toMatch(/setHandoffFollowUpGate\(pendingMergeSweepBlocked\)/);
const gateFn = extractFnBody(COS_SRC, COS_SRC.indexOf('async function pendingMergeSweepBlocked'));
expect(gateFn).toMatch(/!isDaemonRunning\(\)/);
expect(gateFn).toMatch(/s\.paused\)/);
expect(gateFn).toMatch(/getDomainMode\(s\.config,\s*'cos'\)\s*!==\s*'execute'/);
});
it('keeps the opportunistic drain in evaluateTasks so the call site cannot be deleted silently', () => {
const evalFn = extractFnBody(GEN_SRC, GEN_SRC.indexOf('export async function evaluateTasks'));
expect(evalFn).toMatch(/sweepPendingMergePrs\(\)/);
expect(evalFn).toMatch(/!paused && getDomainMode\(state\.config, 'cos'\) === 'execute'/);
});
it('does NOT re-couple the drain to the pr-watcher task type', () => {
const start = PRESTEP_SRC.indexOf('async function resolvePrWatcherBlock');
expect(start, 'resolvePrWatcherBlock must still be findable — a renamed/moved subject would silently pass').toBeGreaterThan(-1);
const watcherFn = extractFnBody(PRESTEP_SRC, start);
expect(watcherFn).not.toMatch(/sweepPendingMergePrs\(/);
});
it('maps MAX_PENDING_MERGE_TICKS back to wall-clock hours', () => {
const hours = (PENDING_MERGE_SWEEP_INTERVAL_MS * MAX_PENDING_MERGE_TICKS) / (60 * 60 * 1000);
expect(PENDING_MERGE_SWEEP_INTERVAL_MS).toBe(30 * 60 * 1000);
expect(hours).toBe(6);
});
});
describe('CoS startup — resume persisted running + mind recovery', () => {
// After a portos-server restart the in-memory daemon flag is false, but
// state.running may still be true on disk. initializePersistentMindSupervisor
// (orphan activeTurn recovery + watchdog) only runs inside start(), so boot
// must re-enter start() when the previous process left running=true — not
// only when alwaysOn/autoStart is set.
it('auto-starts on boot when state.running was persisted true', () => {
const initStart = COS_SRC.indexOf('export async function init(');
expect(initStart).toBeGreaterThan(-1);
const initFn = extractFnBody(COS_SRC, initStart);
expect(initFn).toMatch(/state\.config\.alwaysOn\s*\|\|\s*state\.config\.autoStart\s*\|\|\s*state\.running/);
expect(initFn).toMatch(/await start\(\)/);
});
});
describe('CoS startup — single-flight recovery', () => {
it('shares the full boot promise across concurrent start callers', () => {
expect(COS_SRC).toMatch(/let daemonStartPromise = null/);
expect(COS_SRC).toMatch(/daemonStartPromise = runStart\(\)\.finally\(\(\) => \{\s*daemonStartPromise = null;/);
expect(COS_SRC).toMatch(/export function start\(\) \{[\s\S]*?return daemonStartPromise;\s*\}/);
});
});
describe('cos-rehabilitation-check timer — failure observability (#7552)', () => {
// A rejecting checkAndRehabilitateSkippedTasks used to collapse to the same
// { count: 0 } a healthy no-op call produces, so a persistence failure in the
// ONLY path back from an auto-skipped task type went silent forever. This
// extracts and REALLY EXECUTES the shipped `.catch(err => {...})` handler
// (not a reimplementation) against a mocked emitLog, rather than mocking the
// full `runStart()` import graph — the file's own header explains why that
// full-mock approach is rejected here as "a brittle test of mocks".
const anchor = 'checkAndRehabilitateSkippedTasks(gracePeriodMs).catch(err => {';
const anchorStart = COS_SRC.indexOf(anchor);
it('is still the exact call site this test extracts its handler from', () => {
expect(anchorStart, 'the rehabilitation catch handler moved/changed shape — update this test\'s anchor').toBeGreaterThan(-1);
});
it('logs via emitLog(\'warn\', ...) with the stack, and still resolves the neutral fallback, when the rehabilitation call rejects', () => {
const bodyStart = anchorStart + anchor.length;
const bodyEnd = COS_SRC.indexOf('\n });', bodyStart);
const fnBody = COS_SRC.slice(bodyStart, bodyEnd);
const emitLog = vi.fn();
// eslint-disable-next-line no-new-func -- executes the real extracted source, not a rewritten copy
const catchHandler = new Function('emitLog', `return function(err) {${fnBody}}`)(emitLog);
const err = new Error('learning store unavailable');
const result = catchHandler(err);
expect(emitLog).toHaveBeenCalledWith(
'warn',
expect.stringContaining('checkAndRehabilitateSkippedTasks failed: learning store unavailable'),
expect.objectContaining({ stack: expect.any(String) })
);
expect(result).toEqual({ count: 0 });
});
});