onbuzz 4.0.2 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/scripts/audit-report.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * audit-report.js — run `npm audit --json` against each workspace, classify
+ * the findings via src/utilities/auditReport.js, and write a markdown report.
+ *
+ * Usage:
+ *   node scripts/audit-report.js                       # default: root + web-ui, stdout markdown
+ *   node scripts/audit-report.js --out=FILE.md         # also write to file
+ *   node scripts/audit-report.js --scope=root          # only root
+ *   node scripts/audit-report.js --scope=web-ui        # only web-ui
+ *   node scripts/audit-report.js --fail-on=high        # exit 1 when high+critical remain
+ *   node scripts/audit-report.js --fail-on=none        # never fail (informational)
+ *   node scripts/audit-report.js --silent              # no stdout (use with --out)
+ *
+ * Exit codes:
+ *   0 — no findings at or above --fail-on severity (default: high)
+ *   1 — findings at or above --fail-on severity
+ *   2 — something went wrong invoking `npm audit`
+ */
+
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  classifyAudit,
+  renderMarkdown,
+  shouldFail,
+} from '../src/utilities/auditReport.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// ────────────────────────────────────────────────────────────────────────
+// CLI arg parsing — intentionally minimal, no deps.
+// ────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const opts = {
+    scope: 'all',          // 'root' | 'web-ui' | 'all'
+    out: null,             // optional output file path
+    failOn: 'high',        // 'critical' | 'high' | 'moderate' | 'low' | 'none'
+    silent: false,
+  };
+  for (const arg of argv.slice(2)) {
+    const [key, val] = arg.split('=');
+    switch (key) {
+      case '--scope':   opts.scope  = val || 'all'; break;
+      case '--out':     opts.out    = val || null;  break;
+      case '--fail-on': opts.failOn = val || 'high'; break;
+      case '--silent':  opts.silent = true;         break;
+      case '--help':
+      case '-h':
+        console.log(fs.readFileSync(__filename, 'utf-8')
+          .split('\n').slice(2, 18).map(s => s.replace(/^ \* ?/, '')).join('\n'));
+        process.exit(0);
+      default:
+        if (arg.startsWith('--')) {
+          console.error(`Unknown flag: ${arg}`);
+          process.exit(2);
+        }
+    }
+  }
+  return opts;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Run `npm audit --json` in a directory and parse.
+// Returns { ok: true, data } on success, { ok: false, error } on failure.
+// `npm audit` exits non-zero when vulns exist — that's NOT a failure here;
+// we still want to parse the JSON output and classify. Only actual spawn
+// errors or malformed JSON are treated as failures.
+// ────────────────────────────────────────────────────────────────────────
+
+function runAudit(cwd) {
+  // Windows: `npm` resolves to `npm.cmd` which requires shell=true on Node
+  // 20+ (CVE-2024-27980 hardening). POSIX is fine without a shell — cheaper
+  // spawn and avoids shell-escaping surprises.
+  const isWin = process.platform === 'win32';
+  const res = spawnSync(isWin ? 'npm.cmd' : 'npm', ['audit', '--json'], {
+    cwd,
+    encoding: 'utf-8',
+    maxBuffer: 32 * 1024 * 1024,  // 32 MB — big trees can produce long JSON
+    shell: isWin,
+  });
+  if (res.error) {
+    return { ok: false, error: `spawn failed: ${res.error.message}` };
+  }
+  const stdout = res.stdout || '';
+  if (!stdout.trim()) {
+    return { ok: false, error: `empty output from npm audit (exit ${res.status})` };
+  }
+  try {
+    return { ok: true, data: JSON.parse(stdout) };
+  } catch (err) {
+    return { ok: false, error: `failed to parse npm audit JSON: ${err.message}` };
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Workspace resolution
+// ────────────────────────────────────────────────────────────────────────
+
+function resolveWorkspaces(scope) {
+  const root   = { label: 'root',   cwd: REPO_ROOT };
+  const webUi  = { label: 'web-ui', cwd: path.join(REPO_ROOT, 'web-ui') };
+  const list = [];
+  if (scope === 'root' || scope === 'all') list.push(root);
+  if (scope === 'web-ui' || scope === 'all') list.push(webUi);
+  return list.filter(ws => {
+    if (!fs.existsSync(path.join(ws.cwd, 'package.json'))) {
+      console.error(`[audit-report] skipping ${ws.label} — no package.json at ${ws.cwd}`);
+      return false;
+    }
+    return true;
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Main
+// ────────────────────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const workspaces = resolveWorkspaces(opts.scope);
+  if (workspaces.length === 0) {
+    console.error('[audit-report] no workspaces to scan');
+    process.exit(2);
+  }
+
+  const sections = [];
+  let anyFailed = false;
+
+  for (const ws of workspaces) {
+    if (!opts.silent) console.error(`[audit-report] scanning ${ws.label}…`);
+    const result = runAudit(ws.cwd);
+    if (!result.ok) {
+      console.error(`[audit-report] ${ws.label}: ${result.error}`);
+      process.exit(2);
+    }
+    const classified = classifyAudit(result.data);
+    const md = renderMarkdown(classified, { workspace: ws.label });
+    sections.push(md);
+
+    if (shouldFail(classified, opts.failOn)) anyFailed = true;
+  }
+
+  const fullReport = sections.join('\n\n---\n\n');
+
+  if (opts.out) {
+    fs.writeFileSync(path.resolve(opts.out), fullReport, 'utf-8');
+    if (!opts.silent) console.error(`[audit-report] wrote ${opts.out}`);
+  }
+
+  if (!opts.silent) {
+    // Print markdown to stdout for piping / direct viewing.
+    process.stdout.write(fullReport + '\n');
+  }
+
+  process.exit(anyFailed ? 1 : 0);
+}
+
+main();

package/src/core/__tests__/agentScheduler.emptyResponseDiagnostics.test.js

@@ -0,0 +1,191 @@
+/**
+ * Tests for empty-response diagnostic capture.
+ *
+ * When an AI response lands and our accumulator classifies it as "empty"
+ * (no content and no tool calls), the scheduler records a SHAPE SNAPSHOT
+ * of that response onto `_emptyResponseTracker[agentId].samples`. The
+ * /scheduler visualizer surfaces the last snapshot's `hint` as a subline
+ * under the Empties chip so an operator can tell WHY it was empty:
+ * tool-call-only turn (bridge bug), reasoning-only turn (streaming never
+ * reached text), content-filter, length, etc.
+ *
+ * These tests cover the classifier's hint logic and the per-agent
+ * ring-buffer (cap 3 samples) behavior. They do not exercise the full
+ * stall path — agentScheduler.test.js handles that.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+// Silence activity service
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+
+function makeScheduler() {
+  const logger = createMockLogger();
+  const agentPool = {
+    getAgent: jest.fn().mockResolvedValue(null),
+    getAllAgents: jest.fn().mockResolvedValue([]),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    getCompactionMetadata: jest.fn().mockResolvedValue(null),
+    getMessagesForAI: jest.fn().mockResolvedValue([]),
+  };
+  const messageProcessor = {};
+  const aiService = { abortRequest: jest.fn().mockReturnValue(false), getActiveRequest: () => null };
+  const scheduler = new AgentScheduler(agentPool, messageProcessor, aiService, logger);
+  return { scheduler, agentPool };
+}
+
+describe('_snapshotResponseShape', () => {
+  let scheduler;
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ scheduler } = makeScheduler());
+  });
+
+  test('null / undefined response produces a null-content snapshot with a clear hint', () => {
+    const s = scheduler._snapshotResponseShape(null);
+    expect(s.contentType).toBe('null');
+    expect(s.contentLength).toBe(0);
+    expect(s.hint).toMatch(/null\/undefined/);
+  });
+
+  test('string content measures length correctly', () => {
+    const s = scheduler._snapshotResponseShape({ content: 'hello world' });
+    expect(s.contentType).toBe('string');
+    expect(s.contentLength).toBe(11);
+  });
+
+  test('array content (Responses API shape) sums text-part lengths', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: [{ type: 'text', text: 'hi ' }, { type: 'text', text: 'there' }],
+    });
+    expect(s.contentType).toBe('array');
+    expect(s.contentLength).toBe(8);
+  });
+
+  test('tool-call-only turn (content null + toolCalls present) → bridge-gap hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: null,
+      toolCalls: [{ id: 'call_1', function: { name: 'x', arguments: '{}' } }],
+    });
+    expect(s.hasToolCalls).toBe(true);
+    expect(s.toolCallCount).toBe(1);
+    expect(s.hint).toMatch(/Tool-call-only turn/);
+    expect(s.hint).toMatch(/Chat Completions bridge gap/);
+  });
+
+  test('snake_case tool_calls also detected (OpenAI raw shape)', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      tool_calls: [{ id: 'a' }, { id: 'b' }],
+    });
+    expect(s.hasToolCalls).toBe(true);
+    expect(s.toolCallCount).toBe(2);
+  });
+
+  test('reasoning-only turn (empty content + reasoning field) → reasoning-only hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      reasoning: 'long chain of thought...',
+    });
+    expect(s.hasReasoning).toBe(true);
+    expect(s.hint).toMatch(/Reasoning-only turn/);
+    expect(s.hint).toMatch(/output_text/);
+  });
+
+  test('reasoning detected when content is an array with a reasoning part', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: [{ type: 'reasoning', text: '…' }],
+    });
+    expect(s.hasReasoning).toBe(true);
+  });
+
+  test('finish_reason content_filter → safety-filter hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finish_reason: 'content_filter',
+    });
+    expect(s.hint).toMatch(/content filter/i);
+  });
+
+  test('finish_reason length → max_tokens hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finishReason: 'length',
+    });
+    expect(s.hint).toMatch(/max_tokens/);
+  });
+
+  test('clean stop with empty content → silent-rejection hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finishReason: 'stop',
+    });
+    expect(s.hint).toMatch(/silent prompt-rejection|context-limit|upstream timeout/);
+  });
+
+  test('unknown-shape fallback hint is present', () => {
+    const s = scheduler._snapshotResponseShape({ content: '' });
+    expect(s.hint).toMatch(/unclear|inspect raw/);
+  });
+
+  test('does not leak content body — only metadata', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: 'a very secret payload that must not appear in /scheduler or logs',
+    });
+    expect(JSON.stringify(s)).not.toContain('secret payload');
+  });
+});
+
+describe('_trackEmptyResponse + samples ring buffer', () => {
+  let scheduler, agentPool;
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ scheduler, agentPool } = makeScheduler());
+    const agent = { id: 'a1', name: 'A', mode: 'agent', conversations: { full: { messages: [] } } };
+    agentPool.getAgent.mockResolvedValue(agent);
+  });
+
+  test('records a sample snapshot on each empty-response cycle', async () => {
+    await scheduler._trackEmptyResponse('a1', { content: '' });
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.samples).toHaveLength(1);
+    expect(entry.samples[0].contentType).toBe('string');
+    expect(entry.samples[0].hint).toBeDefined();
+  });
+
+  test('samples ring buffer caps at 3 entries', async () => {
+    for (let i = 0; i < 5; i++) {
+      await scheduler._trackEmptyResponse('a1', { content: `sample-${i}` });
+    }
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    // Note: threshold may have fired and cleared the tracker — we only get
+    // here if the tracker survives. Either way, the ring buffer's cap is
+    // the contract we want to lock.
+    if (entry) expect(entry.samples.length).toBeLessThanOrEqual(3);
+  });
+
+  test('missing aiResponse is tolerated (null-safe snapshot)', async () => {
+    await scheduler._trackEmptyResponse('a1', null);
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.samples[0].contentType).toBe('null');
+  });
+
+  test('samples carry over from previous cycles on same agent', async () => {
+    await scheduler._trackEmptyResponse('a1', { content: '' });
+    await scheduler._trackEmptyResponse('a1', { content: null, toolCalls: [{ id: 'x' }] });
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.count).toBe(2);
+    expect(entry.samples).toHaveLength(2);
+    expect(entry.samples[1].hasToolCalls).toBe(true);
+  });
+});

package/src/core/__tests__/agentScheduler.modeTransitions.test.js

@@ -0,0 +1,233 @@
+/**
+ * Tests for the mode-transition history surface on AgentScheduler.
+ *
+ * The scheduler owns the ring buffer (`_modeTransitionHistory`) and exposes
+ * two entry points:
+ *
+ *   - `recordModeTransition(agentId, from, to, reasonCode, detail)`
+ *     Bookkeeping only — no mutation, no persist, no broadcast. Called by
+ *     agentPool.updateAgent when an external flip happens (UI toggle, etc.).
+ *
+ *   - `_transitionMode(agentId, to, reasonCode, detail)`
+ *     End-to-end — mutates agent.mode, pushes transcript message (if any),
+ *     persists via agentPool, broadcasts two events. Used by the scheduler's
+ *     own protective flips (user stop, AI timeout, empty stall, loop).
+ *
+ * Tests exercise both without a real agent pool — a minimal mock pool is
+ * plenty to lock the contract. The point here is "bookkeeping correctness
+ * and broadcast shape", not agent lifecycle.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+import AgentScheduler from '../agentScheduler.js';
+import { AGENT_MODES } from '../../utilities/constants.js';
+
+function makeScheduler(opts = {}) {
+  const broadcastToSession = jest.fn();
+  const webSocketManager = { broadcastToSession };
+  const persistAgentState = jest.fn().mockResolvedValue(undefined);
+  const broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  const agent = opts.agent || {
+    id: 'a1', name: 'A', mode: AGENT_MODES.AGENT,
+    sessionId: 's1', conversations: { full: { messages: [] } },
+  };
+  const agentPool = {
+    getAgent: jest.fn().mockImplementation(id => Promise.resolve(id === agent.id ? agent : null)),
+    getAllAgents: jest.fn().mockResolvedValue([agent]),
+    persistAgentState,
+    getCompactionMetadata: jest.fn().mockResolvedValue(null),
+    getMessagesForAI: jest.fn().mockResolvedValue([]),
+  };
+  const messageProcessor = {
+    extractAndExecuteTools: jest.fn().mockResolvedValue([]),
+    extractToolCommands: jest.fn().mockResolvedValue([]),
+  };
+  const aiService = {
+    sendMessage: jest.fn().mockResolvedValue({ content: 'x', tokenUsage: {} }),
+    abortRequest: jest.fn().mockReturnValue(false),
+    getActiveRequest: jest.fn().mockReturnValue(null),
+  };
+  // Actual constructor signature: (agentPool, messageProcessor, aiService, logger, webSocketManager, ...)
+  const scheduler = new AgentScheduler(agentPool, messageProcessor, aiService,
+    createMockLogger(), webSocketManager);
+  // broadcastAgentStateUpdate is a real method on the scheduler that does UI
+  // broadcasts — stub it so tests can focus on the agent_mode_changed event
+  // shape without caring about the canonical-state event's wiring.
+  scheduler.broadcastAgentStateUpdate = broadcastAgentStateUpdate;
+  // Pretend we have a session map so the broadcast finds a target.
+  scheduler.registerAgentSession(agent.id, agent.sessionId);
+  return { scheduler, agent, agentPool, webSocketManager, broadcastToSession,
+           persistAgentState, broadcastAgentStateUpdate };
+}
+
+describe('AgentScheduler.recordModeTransition', () => {
+  test('appends an entry with timestamp + human reason', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'user-stop');
+
+    const history = scheduler._modeTransitionHistory.get('a1');
+    expect(history).toHaveLength(1);
+    expect(history[0]).toMatchObject({
+      from: 'agent',
+      to: 'chat',
+      reasonCode: 'user-stop',
+      humanReason: 'Stopped by user.',
+    });
+    expect(new Date(history[0].at).getTime()).not.toBeNaN();
+  });
+
+  test('interpolates detail into the human reason', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'empty-response-stall',
+      { count: 5, elapsedSec: 57 });
+
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.humanReason).toBe(
+      'The model returned 5 empty responses in a row over 57s — likely rate-limited, misconfigured, or rejecting the conversation. Switched to Guided Chat.'
+    );
+    expect(entry.detail).toEqual({ count: 5, elapsedSec: 57 });
+  });
+
+  test('no-op when from === to (prevents phantom same-mode entries)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'chat', 'chat', 'user-toggle');
+    expect(scheduler._modeTransitionHistory.get('a1')).toBeUndefined();
+  });
+
+  test('no-op when agentId is missing', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('', 'agent', 'chat', 'user-stop');
+    scheduler.recordModeTransition(null, 'agent', 'chat', 'user-stop');
+    expect(scheduler._modeTransitionHistory.size).toBe(0);
+  });
+
+  test('ring buffer trims to MAX_PER_AGENT', () => {
+    const { scheduler } = makeScheduler();
+    const MAX = scheduler._MODE_TRANSITION_HISTORY_MAX_PER_AGENT;
+    for (let i = 0; i < MAX + 10; i++) {
+      // Alternate direction so from !== to every time.
+      scheduler.recordModeTransition('a1',
+        i % 2 === 0 ? 'agent' : 'chat',
+        i % 2 === 0 ? 'chat' : 'agent',
+        'user-toggle');
+    }
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(MAX);
+  });
+
+  test('stores null detail when none provided (avoids empty-object noise)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'user-stop');
+    expect(scheduler._modeTransitionHistory.get('a1')[0].detail).toBeNull();
+  });
+
+  test('unknown reason codes still produce a readable humanReason (no bare symbol)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'some-future-code');
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.humanReason).toBe('Mode change (some future code).');
+  });
+});
+
+describe('AgentScheduler._transitionMode', () => {
+  test('mutates agent.mode, records transition, persists, and broadcasts', async () => {
+    const { scheduler, agent, persistAgentState, broadcastToSession,
+            broadcastAgentStateUpdate } = makeScheduler();
+
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'user-stop');
+
+    expect(changed).toBe(true);
+    expect(agent.mode).toBe(AGENT_MODES.CHAT);
+    expect(persistAgentState).toHaveBeenCalledWith('a1');
+    expect(broadcastAgentStateUpdate).toHaveBeenCalledWith('a1', 'user-stop');
+
+    // Find the agent_mode_changed broadcast
+    const modeEvent = broadcastToSession.mock.calls
+      .find(c => c[1].type === 'agent_mode_changed');
+    expect(modeEvent).toBeDefined();
+    expect(modeEvent[1].data).toMatchObject({
+      agentId: 'a1',
+      mode: AGENT_MODES.CHAT,
+      reason: 'user-stop',                      // back-compat symbolic
+      humanReason: 'Stopped by user.',          // new natural-language field
+    });
+
+    // Ring buffer records the flip
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(1);
+  });
+
+  test('transcriptMessage is pushed into conversations.full and broadcast as message_added', async () => {
+    const { scheduler, agent, broadcastToSession } = makeScheduler();
+
+    const msg = {
+      id: 'm-1', role: 'assistant', content: 'Stalled.',
+      timestamp: new Date().toISOString(),
+    };
+    await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'empty-response-stall',
+      { count: 5, elapsedSec: 57, transcriptMessage: msg });
+
+    // Conversation got the bubble
+    expect(agent.conversations.full.messages).toHaveLength(1);
+    expect(agent.conversations.full.messages[0].id).toBe('m-1');
+
+    // transcriptMessage was excluded from the saved detail
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.detail).toEqual({ count: 5, elapsedSec: 57 });
+    expect(entry.detail.transcriptMessage).toBeUndefined();
+
+    // message_added broadcast fired
+    const msgEvent = broadcastToSession.mock.calls
+      .find(c => c[1].type === 'message_added');
+    expect(msgEvent).toBeDefined();
+    expect(msgEvent[1].data.message.id).toBe('m-1');
+    expect(msgEvent[1].data.type).toBe('empty-response-stall');
+  });
+
+  test('no-op (returns false) when agent is already in the target mode', async () => {
+    const { scheduler, persistAgentState } = makeScheduler();
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.AGENT, 'user-toggle');
+    expect(changed).toBe(false);
+    expect(persistAgentState).not.toHaveBeenCalled();
+    expect(scheduler._modeTransitionHistory.size).toBe(0);
+  });
+
+  test('returns false when agent does not exist', async () => {
+    const { scheduler, persistAgentState } = makeScheduler();
+    const changed = await scheduler._transitionMode('nonexistent', AGENT_MODES.CHAT, 'user-stop');
+    expect(changed).toBe(false);
+    expect(persistAgentState).not.toHaveBeenCalled();
+  });
+
+  test('persistence failure does NOT crash the flip (mode still mutated)', async () => {
+    const { scheduler, agent, persistAgentState } = makeScheduler();
+    persistAgentState.mockRejectedValueOnce(new Error('disk full'));
+
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'user-stop');
+    expect(changed).toBe(true);
+    expect(agent.mode).toBe(AGENT_MODES.CHAT);
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(1);
+  });
+});
+
+describe('AgentScheduler.getState — surfaces modeTransitions per agent', () => {
+  test('agent row includes the last N transitions', async () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'empty-response-stall',
+      { count: 5, elapsedSec: 57 });
+    scheduler.recordModeTransition('a1', 'chat', 'agent', 'user-toggle');
+
+    const state = await scheduler.getState();
+    expect(state.agents).toHaveLength(1);
+    expect(state.agents[0].modeTransitions).toHaveLength(2);
+    expect(state.agents[0].modeTransitions[0].reasonCode).toBe('empty-response-stall');
+    expect(state.agents[0].modeTransitions[1].reasonCode).toBe('user-toggle');
+    // humanReason is already interpolated — the frontend can render verbatim
+    expect(state.agents[0].modeTransitions[0].humanReason).toContain('5 empty responses');
+  });
+
+  test('agent with no transitions reports an empty array (not undefined)', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state.agents[0].modeTransitions).toEqual([]);
+  });
+});

package/src/core/__tests__/agentScheduler.taskLifecycleInstruction.test.js

@@ -0,0 +1,78 @@
+/**
+ * Contract test for the AGENT-mode TaskManager instruction that
+ * agentScheduler injects into every system prompt on an agent-mode turn.
+ *
+ * The instruction and the tool's getDescription() (see
+ * tools/__tests__/taskManagerTool.lifecycleGuidance.test.js) must agree
+ * on the lifecycle — if they drift, the agent gets conflicting guidance
+ * and reverts to whichever one the model's attention happens to anchor
+ * on, which in practice is the older, shorter one. Both tripwires
+ * together lock the contract end-to-end.
+ *
+ * The assertions are keyword-level and case-insensitive so wording can
+ * evolve without breaking the test — but the underlying concepts
+ * (sync-first, in_progress → completed, jobdone at the end) must stay
+ * named.
+ */
+
+import { jest, describe, test, expect } from '@jest/globals';
+
+// Read the scheduler source file directly and grep for the instruction
+// string. Importing the class would drag the whole compaction / AI /
+// websocket stack along for a plain-text check, which is wasteful.
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEDULER_SRC = readFileSync(
+  join(__dirname, '../agentScheduler.js'),
+  'utf-8'
+);
+
+describe('agentScheduler AGENT-mode TaskManager instruction — lifecycle contract', () => {
+  // Locate the instruction literal. It starts with "IMPORTANT: You are in
+  // AGENT mode" and is followed by the lifecycle guidance block.
+  const startIdx = SCHEDULER_SRC.indexOf('IMPORTANT: You are in AGENT mode');
+  const endIdx = SCHEDULER_SRC.indexOf('enhancedSystemPrompt = (agent.systemPrompt',
+    startIdx + 1);
+  const instruction = SCHEDULER_SRC.slice(startIdx, endIdx);
+
+  const has = (needle) => expect(instruction).toMatch(new RegExp(needle, 'i'));
+
+  test('the instruction block was located in the source', () => {
+    expect(startIdx).toBeGreaterThan(-1);
+    expect(instruction.length).toBeGreaterThan(100);
+  });
+
+  test('names TASK LIFECYCLE up front', () => {
+    has('TASK LIFECYCLE');
+  });
+
+  test('first call must be sync, not per-task create', () => {
+    has('FIRST TaskManager call must be');
+    has('sync');
+    has("Don't `create` tasks one at a time");
+  });
+
+  test('per-step pattern: in_progress → do work → completed', () => {
+    has('in_progress');
+    has('completed');
+    has('one at a time');
+  });
+
+  test('mid-flight refinement allowed via create or sync', () => {
+    has('`create`');
+    has('`sync`');
+    has("Don't `sync` every turn");
+  });
+
+  test('jobdone is the terminal action', () => {
+    has('jobdone');
+  });
+
+  test('preserves the agent-mode behavioral constraints (no thank-yous, etc.)', () => {
+    has("no thank-you");
+    has('no self-commentary');
+  });
+});