Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

56.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

const now = Date.now();
const resetsAt = new Date(now + 2 * 3600_000).toISOString();

// Every task type and custom job the fixtures reference, so the availability
// resolver stamps a runnable step rather than 'unknown task'.
const taskCatalog = () => ({
  builtin: {
    ux: { enabled: true, eligible: true, appIds: ['app-1'] },
    docs: { enabled: true, eligible: true, appIds: ['app-1'] },
    'universe-bible-images': { enabled: true, eligible: true, appIds: [] },
  },
  custom: { 'job-a': { enabled: true, eligible: true, appId: 'app-1' } },
});

const state = {
  config: null,
  quotas: [],
  runs: [],
  dispatches: {},
  recorded: [],
  contexts: [],
  blocks: {},
  completions: {},
  completed: [],
  completionsUnreadable: false,
  settled: [],
  settleError: null,
  invokePending: {},
  invoked: [],
  invokeResult: undefined,
  catalog: taskCatalog(),
  catalogReads: 0,
  reservations: {},
  reserved: [],
  reserveOk: true,
  settlement: { accepted: 0, refused: 0 },
};

vi.mock('./cosTaskStore.js', () => ({ getAllTasks: vi.fn(async () => ({ cos: { tasks: state.sequenceTasks || [] } })) }));

vi.mock('./providerUsage.js', () => ({
  getProviderQuotas: vi.fn(async () => state.quotas),
}));

vi.mock('./quotaBurnStore.js', () => ({
  getQuotaBurnConfig: vi.fn(async () => state.config),
  getQuotaBurnRuns: vi.fn(async () => state.runs),
  recordQuotaBurnRun: vi.fn(async (entry) => { state.runs.unshift(entry); }),
  // `null` — not a throw — is the module's real "could not read" signal, so the
  // stub speaks the contract the runner is tested against.
  getQuotaBurnReservations: vi.fn(async () => state.reservations),
  quotaBurnReservationKey: (familyId, stepId) => `${familyId}::${stepId}`,
}));

// Settlement is doubled at the same altitude as the invocation path: this suite
// owns the runner's accounting CONTRACT — reserve an asynchronous acceptance,
// charge a synchronous one — while `quotaBurnAcceptance.test.js` owns what
// settling a reservation actually does.
vi.mock('./quotaBurnAcceptance.js', () => ({
  reconcileQuotaBurnReservations: vi.fn(async () => state.settlement),
  reserveQuotaBurnDispatch: vi.fn(async (record) => {
    state.reserved.push(record);
    return state.reserveOk;
  }),
}));

// The shared REFERENCE path. Doubled at the same altitude as the legacy
// registry above, so this suite keeps testing the runner's own contract — which
// lane a step takes, in what order, and what gets charged — rather than a second
// copy of the invocation logic (`quotaBurnInvoke.test.js` owns that).
vi.mock('./quotaBurnInvoke.js', () => ({
  getQuotaBurnTaskCatalog: vi.fn(async () => { state.catalogReads += 1; return state.catalog; }),
  // The sequence walker asks it whether a step still applies to its app.
  resolveQuotaBurnStep: vi.fn(async (job) => (state.notApplicable?.includes(job.id)
    ? { unavailable: { code: 'not-applicable', reason: 'does not apply' } } : {})),
  countQuotaBurnStepPending: vi.fn(async ({ step }) => state.invokePending[step.id] ?? { count: 0, detail: 'nothing' }),
  invokeQuotaBurnStep: vi.fn(async ({ step, family, candidate, context, force }) => {
    state.invoked.push({ stepId: step.id, familyId: family.id, charge: candidate.charge, force });
    state.contexts.push(context);
    return state.invokeResult ?? { dispatched: true, summary: `invoked ${step.id}` };
  }),
}));

// Only the two ledger functions are stubbed — `selectBurnCandidates` and
// `evaluateFamilies` stay REAL so this suite exercises the actual gate ladder
// rather than a second copy of it. Stubbing the ledger keeps the suite off the
// install's real `data/cos/` files.
vi.mock('./quotaBurn.js', async (importActual) => ({
  ...(await importActual()),
  getQuotaBurnDispatches: vi.fn(async () => state.dispatches),
  recordQuotaBurnDispatch: vi.fn(async (key) => { state.recorded.push(key); }),
}));

// Same posture as the dispatch ledger: the denial gate stays real (it lives in
// quotaBurn.js), only its storage is stubbed off the install's `data/cos/`.
// `recordBurnAgentCompletion` records into `state.settled` so the continuation's
// ordering — ledger first, THEN the next dispatch — is assertable.
vi.mock('./quotaBurnDenials.js', async (importActual) => ({
  ...(await importActual()),
  getActiveQuotaBurnBlocks: vi.fn(async () => state.blocks),
  recordBurnAgentCompletion: vi.fn(async (agent) => {
    state.settled.push(agent?.metadata?.taskQuotaBurnFamily ?? null);
    if (state.settleError) throw new Error(state.settleError);
    return null;
  }),
}));

// The `run once` ledger, stubbed off the install's `data/cos/` like the other
// two. `state.completed` records the writes so "a one-shot job marks itself
// spent" is assertable without a filesystem round trip.
vi.mock('./quotaBurnCompletions.js', () => ({
  // `null` — not a throw — is the module's real "could not read" signal, so the
  // stub speaks the same contract the runner is being tested against.
  getQuotaBurnCompletions: vi.fn(async () => (state.completionsUnreadable ? null : state.completions)),
  recordQuotaBurnJobCompletion: vi.fn(async (familyId, jobId) => {
    state.completed.push(`${familyId}:${jobId}`);
    state.completions = { ...state.completions, [`${familyId}:${jobId}`]: new Date(now).toISOString() };
    return state.completions;
  }),
}));

const { normalizeQuotaBurnConfig } = await import('../lib/quotaBurnConfig.js');
const { countQuotaBurnStepPending, invokeQuotaBurnStep } = await import('./quotaBurnInvoke.js');
const { getQuotaBurnStatus, runQuotaBurnCycle, rotatePlanAfter, __tickQuotaBurn, __onBurnAgentCompleted, __resetQuotaBurnRunner } = await import('./quotaBurnRunner.js');

const card = (family, percentRemaining = 50) => ({
  family, label: family, supported: true,
  limits: [{ key: 'week', scope: 'week', label: 'Weekly', resetsAt, percentRemaining }],
});

const plan = (overrides = {}) => normalizeQuotaBurnConfig({
  enabled: true,
  families: {
    grok: {
      enabled: true,
      resetWithinHours: 24,
      jobs: [
        { id: 'first', enabled: true, taskRef: { kind: 'builtin', taskType: 'universe-bible-images', appId: null } },
        { id: 'second', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      ],
    },
  },
  ...overrides,
});

beforeEach(() => {
  state.sequenceTasks = [];
  state.config = plan();
  state.quotas = [card('grok')];
  state.runs = [];
  state.contexts = [];
  state.dispatches = {};
  state.recorded = [];
  state.blocks = {};
  state.completions = {};
  state.completed = [];
  state.completionsUnreadable = false;
  state.settled = [];
  state.settleError = null;
  state.invokePending = {};
  state.invoked = [];
  state.invokeResult = undefined;
  state.reservations = {};
  state.reserved = [];
  state.reserveOk = true;
  state.settlement = { accepted: 0, refused: 0 };
  state.catalog = taskCatalog();
  state.catalogReads = 0;
  __resetQuotaBurnRunner();
});

afterEach(() => { vi.clearAllMocks(); });

describe('runQuotaBurnCycle', () => {
  it('stays silent when the master switch is off and the trigger is scheduled', async () => {
    state.config = plan({ enabled: false });
    await expect(runQuotaBurnCycle()).resolves.toEqual({ skipped: 'disabled' });
    expect(state.runs).toHaveLength(0);
    expect(state.invoked).toHaveLength(0);
  });

  it('never scrapes provider quota when no family could burn', async () => {
    // getProviderQuotas({ refresh: true }) spawns a multi-second TUI scrape per
    // enabled family. With nothing actionable configured it could not produce a
    // dispatch, and it would otherwise run on every tick forever.
    const { getProviderQuotas } = await import('./providerUsage.js');
    state.config = plan({ families: { grok: { enabled: true, jobs: [] } } });
    const result = await runQuotaBurnCycle();
    expect(getProviderQuotas).not.toHaveBeenCalled();
    expect(result).toMatchObject({ dispatched: false, reason: 'no families enabled' });
  });

  it('runs the FIRST job in the plan that has pending work', async () => {
    // Order is the whole point of the plan: "generate the missing bible images
    // first, then fall through to agent work" must not be reordered by the runner.
    state.invokePending = { first: { count: 0, detail: 'all rendered' }, second: { count: 1, detail: 'ready' } };
    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(true);
    expect(state.invoked).toEqual([{ stepId: 'second', familyId: 'grok', charge: true, force: false }]);
    expect(state.recorded).toEqual([result.dispatchKey]);
  });

  it('hands the probe\'s work to run() instead of making it recompute', async () => {
    // A universe-bible-images probe reads every bible to produce its count, and
    // run() needs the same scan to know what to render — without the passthrough
    // that multi-megabyte read happened twice per dispatch.
    const scan = { picked: ['batch'], total: 4 };
    state.invokePending = { first: { count: 4, context: scan } };
    await runQuotaBurnCycle();
    expect(state.contexts).toEqual([scan]);
  });

  it('prefers an earlier job when both have work', async () => {
    state.invokePending = { first: { count: 3 }, second: { count: 9 } };
    await runQuotaBurnCycle();
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first']);
  });

  it('logs why nothing burned instead of failing silently', async () => {
    state.invokePending = { first: { count: 0, detail: 'all rendered' }, second: { count: 0, detail: 'no app' } };
    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(false);
    // The per-job reasons are the actionable part — collapsing them to one
    // fixed string asserted something usually false.
    expect(result.reason).toMatch(/first: all rendered/);
    expect(result.reason).toMatch(/second: no app/);
    expect(state.runs[0]).toMatchObject({ trigger: 'scheduled', dispatched: false });
  });

  it('does not charge the window when the job declines', async () => {
    // A declined job spent no quota. Charging the cap for it would let a
    // repeatedly-misconfigured family exhaust its budget without doing work.
    state.invokePending = { first: { count: 1 } };
    state.invokeResult = { dispatched: false, reason: 'no managed app selected' };
    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(false);
    expect(state.recorded).toEqual([]);
  });

  it('explains a closed window in the run log', async () => {
    state.quotas = [card('grok', 100)];
    state.config = plan({ families: { grok: { enabled: true, resetWithinHours: 0, jobs: [{ id: 'first', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(false);
    expect(result.reason).toMatch(/no burnable window/);
  });

  it('force-runs one named job past the window gates without charging it', async () => {
    state.config = plan({ families: { grok: { enabled: true, resetWithinHours: 0, jobs: [{ id: 'second', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    state.invokePending = { second: { count: 1 } };
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'second', force: true });
    expect(result.dispatched).toBe(true);
    // A forced candidate still carries the family's REAL card and window — it is
    // only marked uncharged, so the run log and the agent brief stay truthful.
    expect(state.invoked).toEqual([{ stepId: 'second', familyId: 'grok', charge: false, force: true }]);
    expect(result.percentRemaining).toBe(50);
    expect(state.recorded).toEqual([]);
  });

  it('force-runs a family plan after its automatic window closes', async () => {
    state.config = plan({ families: { grok: { enabled: true, resetWithinHours: 0, jobs: [{ id: 'second', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    state.invokePending = { second: { count: 1 } };
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', force: true });
    expect(result.dispatched).toBe(true);
    expect(state.invoked).toEqual([{ stepId: 'second', familyId: 'grok', charge: false, force: true }]);
    expect(state.recorded).toEqual([]);
  });

  it('burns EVERY eligible family in one cycle, not just the soonest to reset', async () => {
    // Families don't share a budget — each draws down its own window against its
    // own reserve and cap. Stopping the cycle at the first dispatch meant the
    // soonest-resetting family took every tick and a longer-windowed one
    // (claude at 2h vs agy at 21h) never burned at all while claude was enabled.
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        claude: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'soon', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        agy: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'later', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
      },
    });
    state.quotas = [
      { family: 'claude', label: 'claude', supported: true, limits: [{ key: 'session', scope: 'session', resetsAt: new Date(now + 2 * 3600_000).toISOString(), percentRemaining: 90 }] },
      { family: 'agy', label: 'agy', supported: true, limits: [{ key: 'day', scope: 'day', resetsAt: new Date(now + 21 * 3600_000).toISOString(), percentRemaining: 93 }] },
    ];
    state.invokePending = { soon: { count: 1 }, later: { count: 1 } };

    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(true);
    expect(state.invoked.map((entry) => entry.familyId)).toEqual(['claude', 'agy']);
    // Both windows charged — each against its OWN dispatch key.
    expect(state.recorded).toHaveLength(2);
    expect(new Set(state.recorded).size).toBe(2);
    // One run-log row per dispatch, so neither family is hidden from the audit.
    expect(state.runs.filter((entry) => entry.dispatched)).toHaveLength(2);
    expect(result.dispatches).toHaveLength(2);
    expect(result.summary).toMatch(/agy/);
  });

  it('still dispatches the healthy family when another one\'s job declines', async () => {
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        claude: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'broken', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        agy: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'good', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
      },
    });
    state.quotas = [card('claude'), card('agy')];
    state.invokePending = { broken: { count: 1 }, good: { count: 1 } };
    invokeQuotaBurnStep.mockImplementationOnce(async () => ({ dispatched: false, reason: 'no managed app selected' }));

    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(true);
    expect(result.familyId).toBe('agy');
    // Only the family that actually started work is charged.
    expect(state.recorded).toHaveLength(1);
  });

  it('names the family in every skip reason when several plans were walked', async () => {
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        claude: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'a', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        agy: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'b', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
      },
    });
    state.quotas = [card('claude'), card('agy')];
    state.invokePending = { a: { count: 0, detail: 'no app' }, b: { count: 0, detail: 'no app' } };
    const result = await runQuotaBurnCycle();
    expect(result.reason).toMatch(/claude\/a: no app/);
    expect(result.reason).toMatch(/agy\/b: no app/);
  });

  it('releases the re-entrancy guard even when a cycle throws', async () => {
    // Without the finally, an ENOSPC on the ledger write (or any other throw)
    // would leave `running` stuck true and wedge the loop for the life of the
    // process — every later tick returning `already-running` forever.
    const { recordQuotaBurnRun } = await import('./quotaBurnStore.js');
    recordQuotaBurnRun.mockRejectedValueOnce(new Error('ENOSPC'));
    await expect(runQuotaBurnCycle()).rejects.toThrow('ENOSPC');

    recordQuotaBurnRun.mockImplementationOnce(async (entry) => { state.runs.unshift(entry); });
    await expect(runQuotaBurnCycle()).resolves.toMatchObject({ dispatched: false });
  });

  it('refuses to run two cycles at once', async () => {
    state.invokePending = { first: { count: 1 } };
    const [first, second] = await Promise.all([runQuotaBurnCycle(), runQuotaBurnCycle()]);
    expect([first.skipped, second.skipped].filter(Boolean)).toEqual(['already-running']);
  });
});

describe('getQuotaBurnStatus', () => {
  it('returns the config it loaded so the route need not re-read it', async () => {
    // Value, not identity: availability is stamped onto a COPY on the way out
    // (a fact about the catalog right now, never persisted). The contract is
    // that the route gets the plan back without a second file read.
    const { config } = await getQuotaBurnStatus();
    expect(config).toStrictEqual(state.config);
  });

  it('reports the live window and the reason a family would not burn', async () => {
    state.invokePending = { first: { count: 2, detail: '2 entries' }, second: { count: 0, detail: 'no app' } };
    const { status } = await getQuotaBurnStatus();
    const grok = status.families.find((family) => family.id === 'grok');
    expect(grok.willBurn).toBe(true);
    expect(grok.skipReason).toBeNull();
    expect(grok.jobs.map((job) => job.pending.count)).toEqual([2, 0]);

    const codex = status.families.find((family) => family.id === 'codex');
    expect(codex.willBurn).toBe(false);
    expect(codex.skipReason).toBe('disabled');
    // A disabled family's jobs are not probed — the counts would never be acted on.
    expect(codex.jobs.every((job) => job.pending === null)).toBe(true);
  });

  it('names WHICH window the percentage and countdown describe', async () => {
    // A family publishes a short rolling window and a weekly one; a bare
    // "50% left · resets in 2h" says nothing about which allowance that is.
    const { status } = await getQuotaBurnStatus();
    expect(status.families.find((family) => family.id === 'grok').windowLabel).toBe('Weekly');
  });

  it('surfaces an observed provider refusal on the family card', async () => {
    state.blocks = { grok: { at: now - 1000, until: now + 3_600_000, reason: 'Usage limit exceeded' } };
    const { status } = await getQuotaBurnStatus();
    const grok = status.families.find((family) => family.id === 'grok');
    expect(grok.willBurn).toBe(false);
    expect(grok.blockedUntil).toBe(new Date(now + 3_600_000).toISOString());
    expect(grok.blockedReason).toBe('Usage limit exceeded');
    expect(grok.skipReason).toMatch(/provider refused the last burn/);
  });
});

/**
 * The stop condition the whole denial ledger exists for: a plan spending a
 * weekly allowance exhausts the SHORT rolling window underneath it, and every
 * further dispatch fails instantly — while the weekly card it gates on still
 * reads "50% left, resets in 2h".
 */
describe('denial blocks in a cycle', () => {
  it('dispatches nothing while the family is blocked, and says why', async () => {
    state.invokePending = { first: { count: 1 } };
    state.blocks = { grok: { at: now - 1000, until: now + 3_600_000, reason: 'Usage limit exceeded' } };
    const entry = await runQuotaBurnCycle({ trigger: 'scheduled' });
    expect(entry.dispatched).toBe(false);
    expect(entry.reason).toMatch(/provider refused the last burn/);
    expect(state.invoked).toEqual([]);
  });

  it('resumes once the block lapses', async () => {
    state.invokePending = { first: { count: 1 } };
    state.blocks = { grok: { at: now - 7_200_000, until: now - 1000, reason: 'Usage limit exceeded' } };
    const entry = await runQuotaBurnCycle({ trigger: 'scheduled' });
    expect(entry.dispatched).toBe(true);
  });

  it('lets a forced run retry through a block', async () => {
    state.invokePending = { first: { count: 1 } };
    state.blocks = { grok: { at: now - 1000, until: now + 3_600_000, reason: 'Usage limit exceeded' } };
    const entry = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'first', force: true });
    expect(entry.dispatched).toBe(true);
  });
});

describe('run-now targeting', () => {
  it('force-runs a job whose enabled checkbox is off', async () => {
    // Clicking ▶ on a paused job is a more specific instruction than the
    // checkbox set earlier; filtering it out made the click a silent no-op
    // reported as "no pending work".
    state.config = plan({ families: { grok: { enabled: true, jobs: [{ id: 'paused', enabled: false, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    state.invokePending = { paused: { count: 1 } };
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'paused', force: true });
    expect(result.dispatched).toBe(true);
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['paused']);
  });

  it('still skips a disabled job on an ordinary scheduled cycle', async () => {
    state.config = plan({ families: { grok: { enabled: true, jobs: [{ id: 'paused', enabled: false, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    state.invokePending = { paused: { count: 1 } };
    // Nothing enabled to run ⇒ not actionable ⇒ no quota scrape at all.
    await expect(runQuotaBurnCycle()).resolves.toMatchObject({ dispatched: false });
    expect(state.invoked).toEqual([]);
  });

  it('force-runs a job in a family whose own checkbox is off', async () => {
    // Both 'switched off' gates govern the UNATTENDED loop; an explicit click on
    // one row outranks them, exactly as it outranks the window/reserve/cap gates.
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: { grok: { enabled: false, jobs: [{ id: 'j', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } },
    });
    state.invokePending = { j: { count: 1 } };
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'j', force: true });
    expect(result.dispatched).toBe(true);
    expect(state.recorded).toEqual([]);
  });

  it('reports the REQUESTED family\'s verdict, not another family\'s', async () => {
    // Reporting a different (enabled) family's verdict left the user with no
    // path to the control they actually needed.
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        grok: { enabled: true, jobs: [{ id: 'j', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        claude: { enabled: true, jobs: [{ id: 'k', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
      },
    });
    // grok has NO provider card — a fact about the world, so force can't pass it.
    state.quotas = [card('claude')];
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'j', force: true });
    expect(result.reason).toMatch(/grok: no enabled provider in this family/);
    expect(result.reason).not.toMatch(/claude/);
  });
});

describe('interval clock', () => {
  it('does not let a manual run defer the next scheduled cycle', async () => {
    // finish() used to stamp lastRunAt for every trigger, so one "Evaluate now"
    // pushed the automatic cycle a full interval out — on a 12-hour interval
    // that can skip the reset the feature exists to spend.
    state.invokePending = { first: { count: 1 } };
    await runQuotaBurnCycle({ trigger: 'manual' });
    const { getProviderQuotas } = await import('./providerUsage.js');
    getProviderQuotas.mockClear();
    // A scheduled tick immediately after must still be due.
    await runQuotaBurnCycle({ trigger: 'scheduled' });
    expect(getProviderQuotas).toHaveBeenCalled();
  });

  it('seeds the interval clock from the persisted run log after a restart', async () => {
    // lastRunAt is in-process; on a bare null the first tick after every boot is
    // "due", so a PM2 restart loop paces a 12-hourly plan into minutes — a full
    // TUI scrape per family ~60s after every boot.
    const { getProviderQuotas } = await import('./providerUsage.js');
    state.config = plan({ checkIntervalMinutes: 720 });
    state.runs = [{ at: new Date(Date.now() - 60_000).toISOString(), trigger: 'scheduled', dispatched: false }];
    await __tickQuotaBurn();
    expect(getProviderQuotas).not.toHaveBeenCalled();

    // A run log whose newest SCHEDULED entry is older than the interval is due.
    __resetQuotaBurnRunner();
    state.runs = [{ at: new Date(Date.now() - 13 * 3600_000).toISOString(), trigger: 'scheduled', dispatched: false }];
    state.invokePending = { first: { count: 1 } };
    await __tickQuotaBurn();
    expect(getProviderQuotas).toHaveBeenCalled();
  });

  it('ignores manual entries when seeding the clock', async () => {
    // Only a scheduled cycle advances the interval; a manual "Evaluate now"
    // recorded moments ago must not defer the automatic one across a restart.
    const { getProviderQuotas } = await import('./providerUsage.js');
    state.config = plan({ checkIntervalMinutes: 720 });
    state.runs = [{ at: new Date().toISOString(), trigger: 'manual', dispatched: false }];
    state.invokePending = { first: { count: 1 } };
    await __tickQuotaBurn();
    expect(getProviderQuotas).toHaveBeenCalled();
  });
});

describe('plan rotation', () => {
  it('resumes after the job the family last dispatched instead of restarting at the top', async () => {
    // `agent-prompt` always probes as "1 pending" (its probe only checks that an
    // app and a provider resolve), so an un-rotated walk re-ran job #1 on every
    // cycle forever and jobs 2..N in an ordered plan never ran once.
    state.invokePending = { first: { count: 1 }, second: { count: 1 } };
    await runQuotaBurnCycle({ trigger: 'manual' });
    await runQuotaBurnCycle({ trigger: 'manual' });
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first', 'second']);
  });

  it('keeps walking to the next job with work when the resume point has none', async () => {
    // Rotation moves where the walk STARTS; "first job with pending work wins"
    // still holds, which is what a probing job like universe-bible-images needs.
    state.invokePending = { first: { count: 1 }, second: { count: 0, detail: 'all rendered' } };
    state.runs = [{ at: new Date().toISOString(), dispatched: true, familyId: 'grok', jobId: 'first' }];
    const result = await runQuotaBurnCycle({ trigger: 'manual' });
    expect(result.dispatched).toBe(true);
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first']);
  });

  it('falls back to plan order for a cursor that is not in the plan', () => {
    // A job deleted from the plan, or one aged out of the capped run log.
    const jobs = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
    expect(rotatePlanAfter(jobs, 'gone').map((job) => job.id)).toEqual(['a', 'b', 'c']);
    expect(rotatePlanAfter(jobs, null).map((job) => job.id)).toEqual(['a', 'b', 'c']);
    expect(rotatePlanAfter(jobs, 'a').map((job) => job.id)).toEqual(['b', 'c', 'a']);
    expect(rotatePlanAfter(jobs, 'c').map((job) => job.id)).toEqual(['a', 'b', 'c']);
  });

  it('reads every family\'s cursor before any dispatch writes a new one', async () => {
    // Two families in one cycle must not see each other's fresh run-log rows.
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        claude: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'c1', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }, { id: 'c2', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        agy: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'a1', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }, { id: 'a2', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
      },
    });
    state.quotas = [card('claude'), card('agy')];
    state.invokePending = { c1: { count: 1 }, c2: { count: 1 }, a1: { count: 1 }, a2: { count: 1 } };
    state.runs = [{ at: new Date().toISOString(), dispatched: true, familyId: 'agy', jobId: 'a1' }];
    await runQuotaBurnCycle({ trigger: 'manual' });
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['c1', 'a2']);
  });
});

describe('completion continuation', () => {
  it('evaluates the family again when one of its burn agents finishes', async () => {
    // The interval only STARTS a burn — see the module header for why one
    // dispatch per `checkIntervalMinutes` cannot spend the window.
    state.invokePending = { first: { count: 1 }, second: { count: 1 } };
    await runQuotaBurnCycle({ trigger: 'manual' });
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    // The continuation advances the plan and is charged like any unforced burn.
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first', 'second']);
    expect(state.recorded).toHaveLength(2);
    expect(state.runs[0]).toMatchObject({ trigger: 'continuation', dispatched: true });
  });

  it('records a refusal BEFORE dispatching the next job', async () => {
    // The whole point of the ordering: this continuation dispatches the next job
    // the moment a burn agent finishes, so a block recorded after it runs (or
    // from a second `agent:completed` subscriber, whose ordering against this
    // one is not guaranteed) arrives one wasted agent too late, every time.
    state.invokePending = { first: { count: 1 } };
    // Whatever the ledger just learned is what selection reads on this very tick.
    state.blocks = { grok: { at: now - 1000, until: now + 3_600_000, reason: 'Usage limit exceeded' } };
    const entry = await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    expect(state.settled).toEqual(['grok']);
    expect(entry.dispatched).toBe(false);
    expect(entry.reason).toMatch(/provider refused the last burn/);
    expect(state.invoked).toEqual([]);
  });

  it('still continues when the denial ledger itself fails', async () => {
    // Telemetry must never be able to stall the plan.
    state.invokePending = { first: { count: 1 } };
    state.settleError = 'ENOSPC';
    const entry = await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    expect(entry.dispatched).toBe(true);
  });

  it('scrapes only the burning family\'s quota, not every enabled provider\'s', async () => {
    // WAIT.FRESH bypasses the cache by design, so each card costs its own
    // multi-second PTY spawn — and every card but this family's is discarded.
    // Unscoped, one burn chain would pay N scrapes per link instead of one.
    const { getProviderQuotas } = await import('./providerUsage.js');
    state.invokePending = { first: { count: 1 } };
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    expect(getProviderQuotas).toHaveBeenCalledWith(expect.objectContaining({ family: 'grok' }));
  });

  it('runs a continuation that arrived mid-cycle instead of dropping it', async () => {
    // Two burn agents finishing inside one cycle is ordinary. Dropping the
    // second on the re-entrancy guard stalls that family until the next interval
    // tick — most of a day at the 12-hour default.
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: {
        claude: { enabled: true, resetWithinHours: 24, jobs: [{ id: 'c1', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] },
        agy: { enabled: true, sequence: true, resetWithinHours: 24, jobs: [
          { id: 'a0', runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
          { id: 'a1', runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
        ] },
      },
    });
    state.quotas = [card('claude'), card('agy')];
    state.invokePending = { c1: { count: 1 }, a1: { count: 1 } };
    state.sequenceTasks = [{ id: 'agy-finishing', status: 'in_progress', metadata: { quotaBurnFamily: 'agy' } }];
    // agy's agent finishes while claude's cycle is still mid-dispatch.
    invokeQuotaBurnStep.mockImplementationOnce(async ({ step, family, candidate }) => {
      state.invoked.push({ stepId: step.id, familyId: family.id, charge: candidate.charge });
      await expect(__onBurnAgentCompleted({ taskId: 'agy-finishing', result: { success: true }, metadata: { taskQuotaBurnFamily: 'agy', taskQuotaBurnStepId: 'a0' } }))
        .resolves.toEqual({ skipped: 'already-running' });
      return { dispatched: true, summary: `ran ${step.id}` };
    });

    await runQuotaBurnCycle({ trigger: 'manual', familyId: 'claude' });
    expect(state.invoked.map((entry) => entry.familyId)).toEqual(['claude', 'agy']);
  });

  it('neither files a denial nor walks the plan when a burn agent is RELAUNCHED', async () => {
    // Relaunch retires the record with `success: false` and requeues the same
    // task on another provider — usually because the user is routing AROUND a
    // usage limit, not hitting one. Read as a completion, both halves misfire:
    // the ledger files "Relaunched by user on <provider>" as an observed refusal
    // and blocks the family on it, and the plan dispatches the next job while the
    // relaunched task is still being re-spawned, putting two burn agents in
    // flight against a chain whose whole safety argument is that it is serial.
    state.invokePending = { first: { count: 1 } };
    const relaunched = {
      taskId: 'burn-1',
      metadata: { taskQuotaBurnFamily: 'grok', taskQuotaBurnStepId: 'first' },
      result: { success: false, resumed: true, resumedTaskId: 'burn-1', error: 'Relaunched by user on codex' },
    };

    // Synchronous null, like the other "not mine" early returns: nothing is
    // even scheduled, so there is no promise to await.
    expect(__onBurnAgentCompleted(relaunched)).toBeNull();

    expect(state.settled).toEqual([]);
    expect(state.invoked).toEqual([]);
    expect(state.completed).toEqual([]);
    expect(state.runs).toEqual([]);
  });

  it('settles the ledger and walks the plan when a stranded pause is retired with no continuation queued (#7469)', async () => {
    // `retireStrandedPausedAgents` (server/services/agentManagement.js) stamps
    // `resumed: true` on a pause whose task was deleted or moved on — but with
    // no `resumedTaskId`, because nothing was requeued. Reading that as a
    // handoff (the bare `isAgentHandoff`) made `onBurnAgentCompleted` return
    // `null`: the denial ledger never ran and the next job in the plan never
    // dispatched, stalling the family until the 12-hour scheduled tick instead
    // of advancing immediately like any other completion.
    state.invokePending = { first: { count: 1 }, second: { count: 1 } };
    await runQuotaBurnCycle({ trigger: 'manual' });
    const stranded = {
      taskId: 'burn-1',
      metadata: { taskQuotaBurnFamily: 'grok', taskQuotaBurnStepId: 'first' },
      result: { success: false, resumed: true, error: 'Pause retired — its task task-9 no longer exists' },
    };

    await __onBurnAgentCompleted(stranded);

    expect(state.settled).toEqual(['grok']);
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first', 'second']);
  });

  it('ignores an agent that was not a quota burn', async () => {
    state.invokePending = { first: { count: 1 } };
    await __onBurnAgentCompleted({ metadata: { taskType: 'user' } });
    await __onBurnAgentCompleted(null);
    expect(state.invoked).toEqual([]);
  });

  it('credits the agent of a manual maintenance run to the denial ledger but never walks the plan on it', async () => {
    // The Schedule tab's "Run maintenance now" spends this family's window
    // (so a refusal is still the family's), but its ladder is its own — the
    // plan must not dispatch, and no plan step may be marked spent, because a
    // manual run finished a task.
    state.invokePending = { first: { count: 1 } };
    const agent = { taskId: 'manual-1', result: { success: true }, metadata: { taskQuotaBurnFamily: 'grok', taskQuotaBurnStepId: 'first', taskQuotaBurnMaintenanceRunId: 'maint-1' } };
    await expect(__onBurnAgentCompleted(agent)).resolves.toEqual({ skipped: 'maintenance-run' });
    expect(state.settled).toEqual(['grok']);
    expect(state.invoked).toEqual([]);
    expect(state.completed).toEqual([]);
    expect(state.runs).toEqual([]);
  });

  it('stops when the master switch is off', async () => {
    // A continuation is unattended spending — switching the feature off must end
    // the chain, not leave it running until the window cap happens to close it.
    state.config = plan({ enabled: false });
    state.invokePending = { first: { count: 1 } };
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    expect(state.invoked).toEqual([]);
    expect(state.runs).toEqual([]);
  });

  it('stops once the window has no quota left to spend', async () => {
    // The chain is bounded by the same gate ladder every other cycle runs — here
    // the reserve, which the run log records so the stop is auditable.
    state.quotas = [card('grok', 10)];
    state.config = plan({ families: { grok: { enabled: true, resetWithinHours: 24, reservePercent: 40, jobs: [{ id: 'first', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }] } } });
    state.invokePending = { first: { count: 1 } };
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    expect(state.invoked).toEqual([]);
    expect(state.runs).toHaveLength(1);
    expect(state.runs[0]).toMatchObject({ trigger: 'continuation', dispatched: false });
    expect(state.runs[0].reason).toMatch(/reserve/);
  });
});

describe('forced run bypasses the pending probe', () => {
  it('calls the job directly instead of letting its own probe veto the click', async () => {
    // The probe exists to PICK a job. When the user already picked one, letting
    // it veto reproduces the silent no-op the force path exists to fix, one
    // gate later — it bites hardest on universe-bible-images, whose 6h
    // in-flight cooldown reports zero for entries that are merely queued.
    state.invokePending = { second: { count: 0, detail: 'already queued' } };
    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'second', force: true });
    expect(countQuotaBurnStepPending).not.toHaveBeenCalled();
    expect(result.dispatched).toBe(true);
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['second']);
  });

  it('still probes on an unforced cycle', async () => {
    state.invokePending = { first: { count: 1 } };
    await runQuotaBurnCycle();
    expect(countQuotaBurnStepPending).toHaveBeenCalled();
  });
});

/**
 * `run once` — the per-step choice between one-shot and standing work.
 *
 * A plan is a rotation the runner walks lap after lap while the window still has
 * quota. That is right for a standing audit and wrong for work that only needs
 * doing once, which was simply re-done every lap.
 */
describe('run-once jobs', () => {
  const oneShotPlan = (jobs) => plan({
    families: { grok: { enabled: true, resetWithinHours: 24, jobs } },
  });

  it('marks a run-once job spent when it dispatches, and skips it next cycle', async () => {
    state.config = oneShotPlan([
      { id: 'once', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      { id: 'standing', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
    ]);
    state.invokePending = { once: { count: 1 }, standing: { count: 1 } };

    await runQuotaBurnCycle();
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['once']);
    expect(state.completed).toEqual(['grok:once']);

    // The plan's next lap must reach `standing` and never return to `once`.
    await runQuotaBurnCycle();
    await runQuotaBurnCycle();
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['once', 'standing', 'standing']);
  });

  it('leaves a repeating job in the rotation and records nothing', async () => {
    state.invokePending = { first: { count: 1 }, second: { count: 1 } };
    await runQuotaBurnCycle();
    await runQuotaBurnCycle();
    await runQuotaBurnCycle();
    // Regression guard for the default: absent `runOnce` must keep repeating.
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['first', 'second', 'first']);
    expect(state.completed).toEqual([]);
  });

  it('stops scraping provider quota once every step of a one-shot plan has run', async () => {
    // The whole point of threading completions into `familyHasRunnableJobs`: a
    // finished plan would otherwise pay for a multi-second TUI scrape every
    // interval, forever, to be told there is nothing to dispatch.
    const { getProviderQuotas } = await import('./providerUsage.js');
    state.config = oneShotPlan([{ id: 'once', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.invokePending = { once: { count: 1 } };
    await runQuotaBurnCycle();
    getProviderQuotas.mockClear();

    const result = await runQuotaBurnCycle();
    expect(getProviderQuotas).not.toHaveBeenCalled();
    expect(result).toMatchObject({ dispatched: false });
    // Distinct from "no families enabled": a finished plan wants Re-arm, an
    // unset one wants a job added.
    expect(result.reason).toMatch(/already run once/);
  });

  it('lets a forced run re-run a spent job, and re-stamps it', async () => {
    state.config = oneShotPlan([{ id: 'once', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.completions = { 'grok:once': new Date(now - 86_400_000).toISOString() };

    const result = await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'once', force: true });
    expect(result.dispatched).toBe(true);
    // Uncharged against the window's automatic budget, but still recorded — the
    // two ledgers answer different questions, and the work just happened.
    expect(state.invoked).toEqual([{ stepId: 'once', familyId: 'grok', charge: false, force: true }]);
    expect(state.recorded).toEqual([]);
    expect(state.completed).toEqual(['grok:once']);
  });

  it('does not record a completion for a job that declined to dispatch', async () => {
    state.config = oneShotPlan([{ id: 'once', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.invokePending = { once: { count: 1 } };
    state.invokeResult = { dispatched: false, reason: 'no managed app selected' };
    await runQuotaBurnCycle();
    // A misconfigured step must stay retryable — burning its one run on a
    // decline would strand it behind a Re-arm click for work that never ran.
    expect(state.completed).toEqual([]);
  });

  it('skips the cycle rather than re-running one-shot work when the ledger is unreadable', async () => {
    // Fails CLOSED: an unreadable ledger reads as "nothing has run", which would
    // re-dispatch every run-once job on the plan.
    state.completionsUnreadable = true;
    const result = await runQuotaBurnCycle();
    expect(result).toMatchObject({ dispatched: false, reason: 'run-once ledger unreadable' });
    expect(state.invoked).toEqual([]);
  });

  it('walks a whole one-shot series through the completion continuation', async () => {
    // The "run the series once" case: each finished burn agent advances the
    // plan, and the series stops of its own accord instead of looping.
    state.config = oneShotPlan([
      { id: 's1', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      { id: 's2', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
    ]);
    state.invokePending = { s1: { count: 1 }, s2: { count: 1 } };

    await runQuotaBurnCycle();
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });
    await __onBurnAgentCompleted({ metadata: { taskQuotaBurnFamily: 'grok' } });

    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['s1', 's2']);
    expect(state.completed).toEqual(['grok:s1', 'grok:s2']);
  });

  it('reports a spent step as ran rather than probing it', async () => {
    const ranAt = new Date(now - 3_600_000).toISOString();
    state.config = oneShotPlan([{ id: 'once', enabled: true, runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.completions = { 'grok:once': ranAt };

    const { status } = await getQuotaBurnStatus();
    const grok = status.families.find((family) => family.id === 'grok');
    expect(grok.jobs).toEqual([{ id: 'once', ranAt, pending: null }]);
    expect(countQuotaBurnStepPending).not.toHaveBeenCalled();
    expect(grok.skipReason).toBe('every enabled job has already run once');
  });
});

// #6381 retired the quota-only `JOB_MODULES` registry and its direct
// `agentPrompt` executor, so there is now exactly ONE invocation path. These
// cover what that leaves the runner responsible for: sending every step down the
// shared path, reading the scheduled-task catalog once per cycle, and refusing —
// not dispatching — a step that still carries a legacy `jobType` and therefore
// has no reference to run.
describe('every step routes through the shared invocation path', () => {
  const refPlan = (jobs) => normalizeQuotaBurnConfig({
    enabled: true,
    families: { grok: { enabled: true, resetWithinHours: 24, jobs } },
  });
  const legacyPlan = () => refPlan([{ id: 'legacy', enabled: true, jobType: 'agent-prompt', params: { appId: 'app-1', prompt: 'x' } }]);

  it('probes and runs a taskRef step through quotaBurnInvoke', async () => {
    state.config = refPlan([{ id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.invokePending = { ref: { count: 1, detail: 'ready' } };

    const result = await runQuotaBurnCycle();

    expect(result.dispatched).toBe(true);
    expect(state.invoked).toEqual([{ stepId: 'ref', familyId: 'grok', charge: true, force: false }]);
  });

  it('sends an un-migrated legacy step down the SAME path rather than a second lane', async () => {
    // The registry that used to execute it is gone. The step is not dropped and
    // not re-interpreted: it goes to the shared path, which resolves it as
    // `legacy-unmigrated` and reports the migration reason. Dispatching it any
    // other way would be the parallel execution path #6381 removed.
    state.config = legacyPlan();
    state.invokePending = { legacy: { count: 0, detail: 'legacy "agent-prompt" step is waiting to be migrated' } };

    const result = await runQuotaBurnCycle();

    expect(countQuotaBurnStepPending).toHaveBeenCalledWith(expect.objectContaining({ step: expect.objectContaining({ id: 'legacy', jobType: 'agent-prompt' }) }));
    expect(result.dispatched).toBe(false);
    expect(state.invoked).toHaveLength(0);
  });

  it('walks past a step with no pending work to the next one', async () => {
    state.config = refPlan([
      { id: 'idle', enabled: true, taskRef: { kind: 'builtin', taskType: 'docs', appId: 'app-1' } },
      { id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
    ]);
    state.invokePending = { idle: { count: 0, detail: 'no pending work' }, ref: { count: 1, detail: 'ready' } };

    const result = await runQuotaBurnCycle();
    expect(result.jobId).toBe('ref');
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['ref']);
  });

  it('reads the scheduled-task catalog once per cycle, and not at all for a legacy-only plan', async () => {
    state.config = refPlan([
      { id: 'a', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      { id: 'b', enabled: true, taskRef: { kind: 'custom', jobId: 'job-a' } },
    ]);
    await runQuotaBurnCycle();
    expect(state.catalogReads).toBe(1);

    state.catalogReads = 0;
    state.config = legacyPlan();
    await runQuotaBurnCycle();
    expect(state.catalogReads).toBe(0);
  });

  it('threads force through to the reference path so a targeted run skips the probe', async () => {
    state.config = refPlan([{ id: 'ref', enabled: false, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    await runQuotaBurnCycle({ trigger: 'manual', familyId: 'grok', jobId: 'ref', force: true });
    expect(state.invoked).toEqual([{ stepId: 'ref', familyId: 'grok', charge: false, force: true }]);
    // A forced run of a NAMED step bypasses the probe entirely — the click IS the
    // selection — and comes back uncharged.
    expect(state.recorded).toHaveLength(0);
  });

  it('does not charge the window when the reference path declines', async () => {
    state.config = refPlan([{ id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.invokePending = { ref: { count: 1 } };
    state.invokeResult = { dispatched: false, reason: 'scheduled task "ux" is disabled' };

    const result = await runQuotaBurnCycle();
    expect(result.dispatched).toBe(false);
    expect(result.reason).toContain('is disabled');
    expect(state.recorded).toHaveLength(0);
  });

  it('probes reference steps for the status page through the same path', async () => {
    state.config = refPlan([{ id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } }]);
    state.invokePending = { ref: { count: 1, detail: 'ready to run scheduled task "ux"' } };

    const { status } = await getQuotaBurnStatus();
    const grok = status.families.find((family) => family.id === 'grok');
    expect(grok.jobs).toEqual([{ id: 'ref', ranAt: null, pending: { count: 1, detail: 'ready to run scheduled task "ux"' } }]);
    expect(countQuotaBurnStepPending).toHaveBeenCalledWith(expect.objectContaining({ step: expect.objectContaining({ id: 'ref' }) }));
  });
});

// #6379. A reference step's work is not accepted when the request is recorded —
// an on-demand engine may still refuse it — so the runner must reserve rather
// than charge, and the cap must keep counting the reservation until
// `quotaBurnAcceptance.js` settles it. Charging at the request is the #3179
// undercount one hop earlier: the ledger says "spent" for work that never ran,
// and a `runOnce` step retires without having done anything.
describe('charging the cap and the run-once ledger exactly once', () => {
  const refPlan = (jobs) => normalizeQuotaBurnConfig({
    enabled: true,
    families: { grok: { enabled: true, resetWithinHours: 24, jobs } },
  });
  const asyncStep = (overrides = {}) => refPlan([
    { id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' }, ...overrides },
  ]);
  const held = (overrides = {}) => ({
    'grok::ref': {
      familyId: 'grok', stepId: 'ref', dispatchKey: 'grok:1', charge: true, runOnce: false,
      requestId: 'demand-1', at: now, chargedAt: null, ...overrides,
    },
  });
  // The key the ladder will actually gate on for this card's window — a
  // reservation only holds a cap slot when it names the same one.
  const liveWindowKey = async () =>
    (await import('./quotaBurn.js')).windowKey('grok', { resetsAt }, { now });

  beforeEach(() => {
    state.invokePending = { ref: { count: 1, detail: 'ready' } };
    state.invokeResult = { dispatched: true, summary: 'Requested "ux"', awaiting: { requestId: 'demand-1' } };
  });

  it('reserves an asynchronous acceptance instead of charging it', async () => {
    state.config = asyncStep({ runOnce: true });

    const result = await runQuotaBurnCycle();

    expect(result.dispatched).toBe(true);
    expect(state.reserved).toEqual([{
      familyId: 'grok', stepId: 'ref', dispatchKey: expect.any(String), charge: true, runOnce: true, requestId: 'demand-1',
    }]);
    // Neither ledger moves until the request is joined to a real task.
    expect(state.recorded).toHaveLength(0);
    expect(state.completed).toHaveLength(0);
    expect(state.runs[0]).toMatchObject({ requestId: 'demand-1', pending: true, charged: false, taskId: null });
  });

  it('charges a synchronous acceptance directly and records the task it queued', async () => {
    state.config = asyncStep({ runOnce: true });
    // The custom-job and programmatic lanes queue (or perform) the work inside
    // the call, so there is no request to wait on — and no reservation to take.
    state.invokeResult = { dispatched: true, summary: 'Queued "job"', detail: { taskId: 'cos-5' } };

    await runQuotaBurnCycle();

    expect(state.reserved).toHaveLength(0);
    expect(state.recorded).toHaveLength(1);
    expect(state.completed).toEqual(['grok:ref']);
    expect(state.runs[0]).toMatchObject({ pending: false, charged: true, taskId: 'cos-5' });
  });

  it('skips a step whose earlier burn is still awaiting acceptance', async () => {
    state.config = refPlan([
      { id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      { id: 'other', enabled: true, taskRef: { kind: 'builtin', taskType: 'docs', appId: 'app-1' } },
    ]);
    state.invokePending = { ref: { count: 1 }, other: { count: 1 } };
    state.reservations = held();

    const result = await runQuotaBurnCycle();

    // The reserved step is passed over — no second request, no second charge —
    // and the walk moves on to the next step in the plan.
    expect(state.invoked.map((entry) => entry.stepId)).toEqual(['other']);
    expect(result.jobId).toBe('other');
  });

  it('counts a reservation against the window cap while it is in flight', async () => {
    state.config = normalizeQuotaBurnConfig({
      enabled: true,
      families: { grok: { enabled: true, resetWithinHours: 24, maxDispatchesPerWindow: 1, jobs: [
        { id: 'ref', enabled: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
      ] } },
    });
    // Reserved against the window this cycle would select, but not yet charged.
    // Reading the cap off the charged ledger alone would let this cycle dispatch
    // a second burn the plan had already committed.
    state.reservations = { 'grok::other': { ...held()['grok::ref'], stepId: 'other', dispatchKey: await liveWindowKey() } };

    const result = await runQuotaBurnCycle();

    expect(result.dispatched).toBe(false);
    expect(result.reason).toContain('dispatch cap reached (1/1)');
  });

  it('refuses to run a cycle it cannot read the reservations for', async () => {
    state.config = asyncStep();
    state.reservations = null;

    const result = await runQuotaBurnCycle();

    // Same posture as the dispatch ledger: reading an unreadable file as "nothing
    // pending" would re-queue a step already in flight and re-open its cap slot.
    expect(result).toMatchObject({ dispatched: false, reason: 'pending reservations read failed' });
    expect(state.invoked).toHaveLength(0);
  });

  it('settles nothing when the page reads status', async () => {
    const { reconcileQuotaBurnReservations } = await import('./quotaBurnAcceptance.js');
    state.config = asyncStep();
    state.reservations = held({ dispatchKey: await liveWindowKey() });

    const { status } = await getQuotaBurnStatus();

    // A probe read must perform no ledger write — opening the page is not a spend.
    expect(reconcileQuotaBurnReservations).not.toHaveBeenCalled();
    expect(state.recorded).toHaveLength(0);
    expect(state.completed).toHaveLength(0);
    // It still SHOWS the reserved burn as used, because it is committed already.
    expect(status.families.find((family) => family.id === 'grok').dispatchesUsed).toBe(1);
  });
});

it('holds a strict sequence until acceptance and successful completion, then advances despite the rotation cursor', async () => {
  state.config = plan({ families: { grok: { enabled: true, sequence: true, jobs: [
    { id: 'audit', runOnce: true, taskRef: { kind: 'builtin', taskType: 'ux', appId: 'app-1' } },
    { id: 'docs', runOnce: true, taskRef: { kind: 'builtin', taskType: 'docs', appId: 'app-1' } },
  ] } } });
  state.invokePending = { audit: { count: 1 }, docs: { count: 1 } };
  state.invokeResult = { dispatched: true, awaiting: { requestId: 'demand-sequence' }, summary: 'Requested audit' };
  expect((await runQuotaBurnCycle()).jobId).toBe('audit');
  expect(state.reserved[0].runOnce).toBe(false);
  expect(state.completed).toHaveLength(0);
  state.reservations = { 'grok::audit': { familyId: 'grok', stepId: 'audit' } };
  expect((await runQuotaBurnCycle()).dispatched).toBe(false);
  state.reservations = {};
  state.sequenceTasks = [{ id: 'task-audit', status: 'in_progress', metadata: { quotaBurnFamily: 'grok' } }];
  expect((await runQuotaBurnCycle()).dispatched).toBe(false);
  const outcome = await __onBurnAgentCompleted({ taskId: 'task-audit', result: { success: true }, metadata: { taskQuotaBurnFamily: 'grok', taskQuotaBurnStepId: 'audit' } });
  expect(state.completions['grok:audit']).toBeTruthy();
  expect(outcome.jobId).toBe('docs');
});