Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { EventEmitter } from 'events';
import { join } from 'path';
// This suite doubles fs.existsSync for spawn branches; it must not invent a database fence.
vi.mock('../lib/databaseMaintenanceJournal.js', () => ({ assertDatabaseAdmission() {} }));
// Heavy modules needed only by spawnDirectly — mock them all before importing.
vi.mock('./cosEvents.js', () => ({ cosEvents: { emit: vi.fn() }, emitLog: vi.fn() }));
vi.mock('./cosAgentLifecycle.js', () => {
const appendAgentOutput = vi.fn().mockResolvedValue(undefined);
const appendAgentOutputLines = vi.fn().mockResolvedValue(undefined);
// Faithful stand-in for the real debounced batcher: accumulates pushed lines
// and, on flush(), routes them through the mocked appendAgentOutputLines while
// swallowing+logging failures (mirrors the real createAgentOutputBatcher in
// cosAgentLifecycle.js — whose error handling is unit-tested in cosAgentLifecycle.test.js).
const createAgentOutputBatcher = vi.fn((agentId, { flushBatch } = {}) => {
let pending = [];
return {
push(lineOrLines) {
if (Array.isArray(lineOrLines)) pending.push(...lineOrLines);
else pending.push(lineOrLines);
},
async flush() {
if (pending.length === 0) return;
const batch = pending;
pending = [];
await (flushBatch ? flushBatch(batch) : appendAgentOutputLines(agentId, batch)).catch((err) =>
console.error(`❌ agent ${agentId} output batch flush failed: ${err.message}`));
},
};
});
return {
updateAgent: vi.fn().mockResolvedValue(undefined),
completeAgent: vi.fn().mockResolvedValue(undefined),
appendAgentOutput,
appendAgentOutputLines,
createAgentOutputBatcher,
};
});
vi.mock('./executionLanes.js', () => ({ release: vi.fn() }));
vi.mock('./toolStateMachine.js', () => ({
completeExecution: vi.fn(),
errorExecution: vi.fn(),
}));
vi.mock('./agentErrorAnalysis.js', () => ({ analyzeAgentFailure: vi.fn().mockResolvedValue(null) }));
// The lifecycle ledger is a real file writer (data/cos/run-events.jsonl) — mocked
// so first-output telemetry lands in a spy rather than the developing install's
// ledger, and because this suite's fileUtils mock carries no PATHS.cos (#4540).
const { appendRunEvent } = vi.hoisted(() => ({ appendRunEvent: vi.fn(async () => ({ appended: true })) }));
vi.mock('./agentRunEventLog.js', () => ({ appendRunEvent }));
vi.mock('./agentRunTracking.js', () => ({ completeAgentRun: vi.fn().mockResolvedValue(undefined) }));
// Mock forgeAuth.js directly so spawnDirectly's GH_TOKEN pinning is exercised without
// pulling in the real worktreeManager → instances module graph. Default: no
// owner-matched account → empty overlay (ambient gh auth untouched).
vi.mock('./forgeAuth.js', () => ({ resolveForgeTokenEnv: vi.fn().mockResolvedValue({}) }));
// The loopback PortOS API token the agent's own `curl`s spend — mocked for the
// same reason: the real one reads settings.json to learn whether this install
// has an instance password.
vi.mock('./agentApiAuth.js', () => ({ resolveAgentApiEnv: vi.fn().mockResolvedValue({}) }));
vi.mock('./agentFinalization.js', () => ({
finalizeAgent: vi.fn().mockResolvedValue(undefined),
releaseAgentLane: vi.fn(),
}));
// The close handler hands the run to the shared completion dispatch (pipeline
// progression → worktree cleanup with the PR disposition → retry-hold release).
// Doubled at that boundary: what this suite owns is that the direct-CLI path
// dispatches with the right verdict and PR ownership, and only when it should —
// the dispatch's own sequence is pinned in agentCompletionCleanup.test.js.
// Mocking it also keeps the real cleanup graph (cos.js, git.js, worktreeManager)
// out of this suite.
vi.mock('./agentCompletionCleanup.js', () => ({
runSpawnerCompletionCleanup: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./agentState.js', () => ({
activeAgents: new Map(),
userTerminatedAgents: new Set(),
pausedAgents: new Map(),
consumePausedAgentExit: vi.fn(),
registerSpawnedAgent: vi.fn(),
unregisterSpawnedAgent: vi.fn(),
metaStringOr: (value, fallback) => (typeof value === 'string' && value) ? value : fallback,
}));
vi.mock('../lib/fileUtils.js', () => ({
tryReadFile: vi.fn().mockResolvedValue(null),
safeJSONParse: (str, fallback) => { try { return JSON.parse(str); } catch { return fallback; } },
// agentSentinel builds the per-agent sentinel filename with this — a mock
// missing it makes doneSentinelPath throw inside the close handler.
sanitizeFilename: (name) => String(name).replace(/[^a-zA-Z0-9._-]/g, '_'),
writeFileGuarded: vi.fn().mockResolvedValue(undefined),
PATHS: { root: '/tmp', cosAgents: '/tmp/agents', data: '/tmp/data' },
}));
vi.mock('../lib/codexCliOutput.js', () => ({ createCodexStderrFormatter: vi.fn() }));
vi.mock('fs/promises', () => ({
readFile: vi.fn().mockResolvedValue('{}'),
writeFile: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('fs', () => ({ existsSync: vi.fn().mockReturnValue(false) }));
// Default passthrough for the Windows resolve+wrap helper (#2243) — POSIX
// behavior. A specific test overrides it with mockReturnValueOnce to assert the
// spawn wiring uses whatever prepareCliSpawn returns.
// Only the two spawn-shaping helpers are stubbed. `guardChildStdin` stays REAL
// so the stdin-EPIPE containment test below pins the production listener rather
// than a test double of it.
vi.mock('../lib/bufferedSpawn.js', async (importActual) => ({
...(await importActual()),
prepareCliSpawn: vi.fn((command, args) => ({ command, args })),
killProcessTree: vi.fn(),
}));
// Mock child_process.spawn to return a controllable fake process
let fakeProcess;
vi.mock('../lib/childProcess.js', () => ({
spawn: vi.fn(() => fakeProcess),
// `execFile` is pulled in transitively by codeReview.js → lmStudioManager
// (via `resolveReviewLoopOptions`'s dependency graph), even though this
// test never spawns one directly.
execFile: vi.fn(),
}));
vi.mock('./ollamaAgentContext.js', () => ({
ensureOllamaAgentContext: vi.fn(async () => ({ skipped: true })),
}));
vi.mock('./providers.js', () => ({
isOllamaBackedProvider: vi.fn(() => false),
}));
vi.mock('../lib/privateSecuritySandbox.js', () => ({
preparePrivateSecuritySpawn: vi.fn(),
}));
// Real publication admission fsyncs a directory on every flush. A byte-volume
// test with hundreds of flushes opts out so disk latency under load cannot eat
// its timeout; the admission contract keeps its own real-boundary test.
const publicationAdmission = vi.hoisted(() => ({ bypass: false }));
vi.mock('../lib/backupSnapshotBoundary.js', async (importActual) => {
const actual = await importActual();
return {
...actual,
withBackupAssetPublication: (work, options) =>
publicationAdmission.bypass ? work() : actual.withBackupAssetPublication(work, options),
};
});
import { buildCliSpawnConfig, spawnDirectly } from './agentCliSpawning.js';
import { promptOpensOwnPr } from './promptSections/completion.js';
import { runSpawnerCompletionCleanup } from './agentCompletionCleanup.js';
import { ensureOllamaAgentContext } from './ollamaAgentContext.js';
import { isOllamaBackedProvider } from './providers.js';
// Real module — the flag is a plain process-local boolean, so driving it
// directly exercises the same code path production does.
import { markHostShuttingDown, resetHostShutdownFlagForTests } from '../lib/hostShutdown.js';
import { emitLog } from './cosEvents.js';
import { existsSync } from 'fs';
import { spawn } from '../lib/childProcess.js';
import { prepareCliSpawn, killProcessTree } from '../lib/bufferedSpawn.js';
// Windows takes killProcessTree's tree-wide `taskkill /T` branch instead, so
// `needsProcessGroup` is false there and these sites spawn attached. The policy
// itself is pinned with an injected platform in credentialBootstrap.test.js;
// these assert only that each site plumbs the decision through.
const EXPECT_GROUP = process.platform !== 'win32';
describe('buildCliSpawnConfig', () => {
it('omits --model for Codex configured-default sentinel but bypasses sandbox/approvals', () => {
const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'codex-configured-default');
// The bypass flag is the Codex equivalent of Claude/Antigravity's
// --dangerously-skip-permissions. Without it, codex exec runs sandboxed (no network → `gh`
// can't reach api.github.com) and non-interactive approval prompts get cancelled.
expect(config.args).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox', '-c', 'check_for_update_on_startup=false']);
});
it('passes explicit Codex model selections through alongside the sandbox bypass', () => {
const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4');
expect(config.args).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox', '-c', 'check_for_update_on_startup=false', '--model', 'gpt-5.4']);
});
it('gives a cloud Codex swarm enough threads for its root plus every worker', () => {
const config = buildCliSpawnConfig(
{ id: 'codex', command: 'codex' },
'gpt-5.4',
{},
{ maxConcurrentThreads: 7 },
);
expect(config.args).toContain('agents.max_concurrent_threads_per_session=7');
});
it('disables the codex update check unconditionally on the headless agent path (ignores provider.args)', () => {
// This builder constructs codex argv from scratch and never forwards
// provider.args, so a provider.args pin is NOT honored here — a headless CoS
// agent can never dismiss the update modal, so the check is always forced off.
const config = buildCliSpawnConfig(
{ id: 'codex', command: 'codex', args: ['-c', 'check_for_update_on_startup=true'] },
'gpt-5.4',
);
expect(config.args).toContain('check_for_update_on_startup=false');
});
it('uses agy print mode for Antigravity without model flags on the configured-default sentinel', () => {
const config = buildCliSpawnConfig({ id: 'antigravity-cli', command: 'agy', args: [] }, 'antigravity-configured-default');
expect(config.command).toBe('agy');
expect(config.args).toEqual(['--dangerously-skip-permissions', '--print']);
});
// agy takes the prompt as the trailing --print VALUE, so every injected flag
// must land before it or agy reads the flag name as its task.
it('threads the per-task model and effort into agy ahead of --print', () => {
const config = buildCliSpawnConfig(
{ id: 'antigravity-cli', command: 'agy', args: [] },
'claude-sonnet-4-6',
{},
{ effort: 'medium' },
);
expect(config.command).toBe('agy');
expect(config.args).toEqual([
'--model', 'claude-sonnet-4-6',
'--effort', 'medium',
'--dangerously-skip-permissions',
'--print',
]);
expect(config.args[config.args.length - 1]).toBe('--print');
});
// The trailing `--agent build` on every OpenCode argv below pins the
// tool-enabled agent: OpenCode's role is argv state, so an un-pinned
// invocation opens in whatever agent the install defaults to (#7405). See
// ensureOpencodeAgent in lib/providerVendors.js.
it('runs `opencode run -m ollama/<model>` for a headless OpenCode Ollama agent', () => {
const config = buildCliSpawnConfig(
{ id: 'opencode-ollama', command: 'opencode', args: ['run'], ollamaBacked: true },
'qwen2.5:7b',
);
expect(config.command).toBe('opencode');
expect(config.args).toEqual(['run', '-m', 'ollama/qwen2.5:7b', '--agent', 'build']);
expect(config.stdinMode).toBe('prompt');
// OpenCode emits plain text, so no stream-json format is requested.
expect(config.streamFormat).toBeUndefined();
});
it('runs `opencode run -m mtplx/<model>` for a headless OpenCode MTPLX agent', () => {
const config = buildCliSpawnConfig(
{ id: 'opencode-mtplx', command: 'opencode', args: ['run'], mtplxBacked: true },
'mtplx',
);
expect(config.command).toBe('opencode');
expect(config.args).toEqual(['run', '-m', 'mtplx/mtplx', '--agent', 'build']);
expect(config.stdinMode).toBe('prompt');
});
it('prepends the run subcommand for OpenCode even if saved args dropped it', () => {
const config = buildCliSpawnConfig({ id: 'opencode-ollama', command: 'opencode', args: [], ollamaBacked: true }, 'qwen2.5:7b');
expect(config.args).toEqual(['run', '-m', 'ollama/qwen2.5:7b', '--agent', 'build']);
});
it('respects a user-baked -m pin on an OpenCode provider and does not duplicate it', () => {
const config = buildCliSpawnConfig(
{ id: 'opencode-ollama', command: 'opencode', args: ['run', '-m', 'ollama/custom'], ollamaBacked: true },
'qwen2.5:7b',
);
expect(config.args).toEqual(['run', '-m', 'ollama/custom', '--agent', 'build']);
});
it('runs `grok` headless with plain output, permission bypass, and stdin prompt file (no --model for configured-default)', () => {
const config = buildCliSpawnConfig({ id: 'grok-cli', command: 'grok', args: [] }, 'grok-configured-default');
expect(config.command).toBe('grok');
expect(config.stdinMode).toBe('prompt');
expect(config.args).toEqual([
'--output-format', 'plain',
'--permission-mode', 'bypassPermissions',
'--prompt-file', '/dev/stdin',
]);
expect(config.args).not.toContain('--model');
// Grok is non-Claude, so no claude-only flags leak in.
expect(config.args).not.toContain('--dangerously-skip-permissions');
expect(config.args).not.toContain('--print');
expect(config.args).not.toContain('--append-system-prompt-file');
});
it('runs `kimi` headless with --print, no --model for the configured-default sentinel', () => {
const config = buildCliSpawnConfig({ id: 'kimi-cli', command: 'kimi', args: ['--print'] }, 'kimi-configured-default');
expect(config.command).toBe('kimi');
expect(config.stdinMode).toBe('prompt');
expect(config.args).toEqual(['--print']);
expect(config.args).not.toContain('--model');
// Kimi is non-Claude, so no claude-only flags leak in.
expect(config.args).not.toContain('--dangerously-skip-permissions');
expect(config.args).not.toContain('--append-system-prompt-file');
});
it('injects --model for a concrete kimi model id', () => {
const config = buildCliSpawnConfig({ id: 'kimi-cli', command: 'kimi', args: ['--print'] }, 'kimi-k2');
expect(config.command).toBe('kimi');
expect(config.args).toEqual(['--print', '--model', 'kimi-k2']);
});
it('runs `cursor-agent` headless with --print --force and the model on stdin', () => {
const config = buildCliSpawnConfig({ id: 'cursor-cli', command: 'cursor-agent', args: ['--print', '--force'] }, 'auto');
expect(config.command).toBe('cursor-agent');
expect(config.stdinMode).toBe('prompt');
expect(config.args).toEqual(['--print', '--force', '--model', 'auto']);
// Cursor is non-Claude, so no claude-only flags leak in.
expect(config.args).not.toContain('--dangerously-skip-permissions');
expect(config.args).not.toContain('--append-system-prompt-file');
// Plain text output — no stream-json parser is claimed for cursor (see cursor.js).
expect(config.streamFormat).toBeUndefined();
});
it('adds --force to a cursor provider whose saved args dropped it (trust gate is fatal without it)', () => {
const config = buildCliSpawnConfig({ id: 'cursor-cli', command: 'cursor-agent', args: [] }, null);
expect(config.args).toEqual(['--print', '--force']);
});
it('does not Bedrock-map a cursor model id that merely contains "claude"', () => {
const config = buildCliSpawnConfig(
{ id: 'cursor-cli', command: 'cursor-agent', args: ['--print', '--force'] },
'claude-opus-5-thinking-high',
{ CLAUDE_CODE_USE_BEDROCK: '1' },
);
expect(config.args).toEqual(['--print', '--force', '--model', 'claude-opus-5-thinking-high']);
expect(config.args.join(' ')).not.toContain('anthropic.');
});
it('adds lean-mode flags and the system-prompt file for an Ollama-backed claude CLI', () => {
const config = buildCliSpawnConfig(
{ id: 'claude-ollama', command: 'claude', ollamaBacked: true },
'qwen3.6:35b',
{},
{ systemPromptFile: '/data/cos/agents/agent-1/system-prompt.md' },
);
expect(config.args).toContain('--bare');
expect(config.args).toContain('--strict-mcp-config');
const idx = config.args.indexOf('--append-system-prompt-file');
expect(config.args[idx + 1]).toBe('/data/cos/agents/agent-1/system-prompt.md');
// Lean flags must not disturb the model injection.
expect(config.args[config.args.indexOf('--model') + 1]).toBe('qwen3.6:35b');
});
it('does NOT add lean flags to the standard claude CLI provider', () => {
const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8');
expect(config.args).not.toContain('--bare');
expect(config.args).not.toContain('--strict-mcp-config');
expect(config.args).not.toContain('--append-system-prompt-file');
});
it('adds the system-prompt file to a STANDARD claude CLI WITHOUT lean flags', () => {
const config = buildCliSpawnConfig(
{ id: 'claude-code', command: 'claude' },
'claude-opus-4-8',
{},
{ systemPromptFile: '/data/cos/agents/agent-2/system-prompt.md' },
);
expect(config.args).not.toContain('--bare');
const idx = config.args.indexOf('--append-system-prompt-file');
expect(config.args[idx + 1]).toBe('/data/cos/agents/agent-2/system-prompt.md');
});
describe('reasoning-effort override', () => {
it('adds a -c model_reasoning_effort pair for codex', () => {
const config = buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4', {}, { effort: 'xhigh' });
expect(config.args).toContain('model_reasoning_effort=xhigh');
});
it('passes Ultra to supported Codex models and clamps it elsewhere', () => {
const codex = { id: 'codex', command: 'codex' };
const maxConfig = buildCliSpawnConfig(codex, 'gpt-5.4', {}, { effort: 'max' });
expect(maxConfig.args).toContain('model_reasoning_effort=max');
const ultraConfig = buildCliSpawnConfig(codex, 'gpt-5.6-sol', {}, { effort: 'ultra' });
expect(ultraConfig.args).toContain('model_reasoning_effort=ultra');
const clampedConfig = buildCliSpawnConfig(codex, 'gpt-5.4', {}, { effort: 'ultra' });
expect(clampedConfig.args).toContain('model_reasoning_effort=max');
});
it('adds --effort for claude', () => {
const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8', {}, { effort: 'high' });
expect(config.args[config.args.indexOf('--effort') + 1]).toBe('high');
});
it('clamps codex-only values on a claude provider', () => {
const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, null, {}, { effort: 'ultra' });
expect(config.args[config.args.indexOf('--effort') + 1]).toBe('max');
});
it('omits the flag entirely when no effort is set or the provider has no effort control', () => {
// Codex always carries `-c check_for_update_on_startup=false`, so assert the
// absence of the EFFORT config pair specifically, not any `-c`.
expect(buildCliSpawnConfig({ id: 'codex', command: 'codex' }, 'gpt-5.4').args.join(' ')).not.toContain('model_reasoning_effort');
expect(buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, null).args).not.toContain('--effort');
const grok = buildCliSpawnConfig({ id: 'grok-cli', command: 'grok', args: [] }, null, {}, { effort: 'high' });
expect(grok.args.join(' ')).not.toContain('effort');
});
it('keys effort on the RESOLVED command, so a blank-command claude provider still qualifies', () => {
// id gives no claude-code* hint and command is blank; the builder resolves
// the launch command to `claude`, so the effort pin must apply — matching
// the TUI builder's re-keying (same pin, same behavior per execution mode).
const config = buildCliSpawnConfig({ id: 'whatever' }, null, {}, { effort: 'high' });
expect(config.args[config.args.indexOf('--effort') + 1]).toBe('high');
});
it('routes a renamed codex provider through the codex recipe, effort shape included', () => {
// The vendor registry used to match codex by provider ID alone, so any
// record but the shipped `codex` fell through to claude's
// unconditionally-true row — claude-shaped argv on the codex binary, with
// only the effort pair keyed off the command. Now the whole recipe follows
// the binary (#6305, which needed a SECOND codex record to build codex argv).
const config = buildCliSpawnConfig(
{ id: 'my-codex', command: '/opt/tools/codex' },
null,
{},
{ effort: 'xhigh' },
);
expect(config.args[0]).toBe('exec');
expect(config.args).not.toContain('--effort');
expect(config.args.join(' ')).toContain('-c model_reasoning_effort=xhigh');
});
it('respects a user-baked --effort pin in provider args (mirrors the --model rule)', () => {
const config = buildCliSpawnConfig(
{ id: 'claude-code', command: 'claude', args: ['--effort', 'low'] },
null,
{},
{ effort: 'max' },
);
const effortArgs = config.args.filter(a => a === '--effort');
expect(effortArgs).toHaveLength(1);
expect(config.args[config.args.indexOf('--effort') + 1]).toBe('low');
});
});
describe('Bedrock model-id mapping', () => {
// buildCliSpawnConfig reads process.env for the Bedrock signal; isolate the
// tests from whatever the host/CI environment happens to set.
let savedBedrock;
beforeEach(() => {
savedBedrock = process.env.CLAUDE_CODE_USE_BEDROCK;
delete process.env.CLAUDE_CODE_USE_BEDROCK;
});
afterEach(() => {
if (savedBedrock === undefined) delete process.env.CLAUDE_CODE_USE_BEDROCK;
else process.env.CLAUDE_CODE_USE_BEDROCK = savedBedrock;
});
const modelOf = (args) => args[args.indexOf('--model') + 1];
it('passes a bare Claude model through unchanged when Bedrock mode is off', () => {
const config = buildCliSpawnConfig({ id: 'claude-code', command: 'claude' }, 'claude-opus-4-8');
expect(modelOf(config.args)).toBe('claude-opus-4-8');
});
it('maps a bare Claude model when Bedrock comes ONLY from settings.json env (regression: #1521 blocking)', () => {
const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
// provider.envVars empty (plain claude-code), Bedrock supplied via the
// ~/.claude/settings.json env block — the case the original fix missed.
const config = buildCliSpawnConfig(
{ id: 'claude-code', command: 'claude', envVars: {} },
'claude-opus-4-8',
{ CLAUDE_CODE_USE_BEDROCK: '1' },
);
expect(modelOf(config.args)).toBe('global.anthropic.claude-opus-4-8');
spy.mockRestore();
});
it('maps a bare Claude model when Bedrock comes from provider.envVars', () => {
const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
const config = buildCliSpawnConfig(
{ id: 'claude-code', command: 'claude', envVars: { CLAUDE_CODE_USE_BEDROCK: '1' } },
'claude-opus-4-8',
);
expect(modelOf(config.args)).toBe('global.anthropic.claude-opus-4-8');
spy.mockRestore();
});
});
});
describe('stream error containment', () => {
// Build a minimal fake process with stdin/stdout/stderr EventEmitters.
function makeFakeProcess({ failWith = null, noStdin = false } = {}) {
const proc = new EventEmitter();
if (!noStdin) {
proc.pid = 12345;
// A real ChildProcess stdin is a stream, so the fake is one too — otherwise
// the production `guardChildStdin` listener has nothing to attach to and the
// stdin-EPIPE path below would be tested against a shape that can't occur.
proc.stdin = Object.assign(new EventEmitter(), { write: vi.fn(), end: vi.fn() });
}
proc.stdout = new EventEmitter();
proc.stderr = new EventEmitter();
if (failWith) setImmediate(() => proc.emit('error', failWith));
return proc;
}
// The stamp `agentLifecycle` writes for a run, derived through the REAL
// predicate instead of hand-written — a literal here is what let the suite
// pin an ownership value the spawn path never produces for a Claude host
// (#6869). `minimalArgs.provider` is the slashdo-capable `claude-code` CLI.
const stampPrOpenedBy = (task, provider = minimalArgs.provider) => promptOpensOwnPr(task, {
providerType: provider.type,
providerId: provider.id,
providerCommand: provider.command,
leanMode: false,
worktreeInfo: { branchName: 'agent/t', worktreePath: '/tmp/wt', baseBranch: 'main' },
});
const minimalArgs = {
agentId: 'agent-test',
task: { id: 'task-1', description: 'do stuff' },
prompt: 'Hello',
workspacePath: '/tmp',
model: 'claude-3',
provider: { id: 'claude-code', type: 'cli', command: 'claude', args: [], envVars: {} },
runId: 'run-1',
cliConfig: {
command: 'claude',
args: ['--dangerously-skip-permissions', '--print', '--output-format', 'stream-json', '--verbose', '--include-partial-messages'],
stdinMode: 'prompt',
streamFormat: 'stream-json',
},
agentDir: '/tmp',
executionId: null,
laneName: null,
};
// Re-import the mocked cosAgentLifecycle module reference once — mocking is module-scoped.
let agentStateMocks;
beforeEach(async () => {
fakeProcess = makeFakeProcess();
// Fresh mocked module reference for each test so mockRejectedValueOnce is clean.
agentStateMocks = await import('./cosAgentLifecycle.js');
// Reset all implementations to their default "resolve" state before each test.
agentStateMocks.updateAgent.mockResolvedValue(undefined);
agentStateMocks.completeAgent.mockResolvedValue(undefined);
agentStateMocks.appendAgentOutput.mockResolvedValue(undefined);
agentStateMocks.appendAgentOutputLines.mockResolvedValue(undefined);
(await import('./agentRunTracking.js')).completeAgentRun.mockResolvedValue(undefined);
(await import('./agentFinalization.js')).finalizeAgent.mockResolvedValue(undefined);
// Completion waits must observe this test, not a previous cleanup call.
runSpawnerCompletionCleanup.mockClear();
runSpawnerCompletionCleanup.mockResolvedValue(undefined);
vi.mocked(existsSync).mockReturnValue(false);
vi.mocked(isOllamaBackedProvider).mockReturnValue(false);
vi.mocked(ensureOllamaAgentContext).mockResolvedValue({ skipped: true });
// Reset the resolve+wrap helper to its POSIX passthrough before each test
// (afterEach's restoreAllMocks can clear the factory implementation).
vi.mocked(prepareCliSpawn).mockImplementation((command, args) => ({ command, args }));
});
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
});
describe('spawn failure containment', () => {
it('settles private sandbox preparation failure without spawning an uncontained child', async () => {
const { preparePrivateSecuritySpawn } = await import('../lib/privateSecuritySandbox.js');
const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');
const { spawn } = await import('../lib/childProcess.js');
spawn.mockClear();
finalizeAgent.mockClear();
releaseAgentLane.mockClear();
preparePrivateSecuritySpawn.mockRejectedValueOnce(new Error('synthetic sandbox unavailable'));
const task = { id: 'private-task', taskType: 'internal', metadata: { analysisType: 'private-security-assessment' } };
await expect(spawnDirectly({ ...minimalArgs, task })).resolves.toBeNull();
expect(spawn).not.toHaveBeenCalled();
expect(releaseAgentLane).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'agent-test', success: false }));
expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
task, success: false, exitCode: 1, completionReason: 'spawn-error', outputBuffer: '',
}));
});
const failedSpawn = () => makeFakeProcess({
noStdin: true,
failWith: Object.assign(new Error('spawn claude ENOENT'), { code: 'ENOENT' }),
});
const waitForSpawnFailure = async () => {
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
};
it('the failing fake really has no stdin (bypass probe)', () => {
expect(makeFakeProcess({ noStdin: true }).stdin).toBeUndefined();
});
it('settles with a startup failure when the provider CLI is missing', async () => {
fakeProcess = failedSpawn();
await expect(spawnDirectly(minimalArgs)).resolves.toBe('agent-test');
await waitForSpawnFailure();
expect(agentStateMocks.completeAgent).toHaveBeenCalledWith(
'agent-test',
expect.objectContaining({ success: false, error: expect.stringContaining('ENOENT') }),
);
});
it('does not leave the agent registered in activeAgents after a failed spawn', async () => {
const { activeAgents, registerSpawnedAgent } = await import('./agentState.js');
activeAgents.clear();
registerSpawnedAgent.mockClear();
agentStateMocks.updateAgent.mockClear();
fakeProcess = failedSpawn();
await spawnDirectly(minimalArgs);
await waitForSpawnFailure();
expect(activeAgents.has('agent-test')).toBe(false);
expect(registerSpawnedAgent).not.toHaveBeenCalled();
expect(agentStateMocks.updateAgent).not.toHaveBeenCalled();
});
it('surfaces the spawn error message to the run log', async () => {
agentStateMocks.appendAgentOutputLines.mockClear();
fakeProcess = failedSpawn();
await spawnDirectly(minimalArgs);
await waitForSpawnFailure();
const lines = agentStateMocks.appendAgentOutputLines.mock.calls.flatMap(([, batch]) => batch);
expect(lines.some((line) => line.includes('ENOENT'))).toBe(true);
});
it('contains an EPIPE on stdin from a child that died before reading the prompt', async () => {
// Two hazards in one shape, both fatal to the WHOLE server process because
// this runs outside the Express request lifecycle (no next(err) to bubble to):
// 1. a synchronous throw from stdin.write on an already-destroyed pipe, and
// 2. an 'error' emitted on the stdin stream with no listener, which Node re-throws.
// Regression guard for the listener drifting back below the write.
const epipe = () => Object.assign(new Error('write EPIPE'), { code: 'EPIPE' });
fakeProcess = makeFakeProcess();
// Captured INSIDE write so the assertion is about ordering, not just
// eventual presence — a guard moved below the write would read 0 here.
let listenersAtWriteTime = null;
fakeProcess.stdin = Object.assign(new EventEmitter(), {
write: vi.fn(function () {
listenersAtWriteTime = fakeProcess.stdin.listenerCount('error');
throw epipe();
}),
end: vi.fn(),
destroy: vi.fn(),
});
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
// The guard was already in place when the write ran…
expect(listenersAtWriteTime).toBe(1);
// …so a late pipe error is swallowed instead of thrown.
expect(() => fakeProcess.stdin.emit('error', epipe())).not.toThrow();
// …and the pipe was closed anyway, so a child still reading stdin sees EOF.
expect(fakeProcess.stdin.destroy).toHaveBeenCalled();
fakeProcess.emit('close', 0);
// The synchronous write throw did not escape as a rejected spawn either.
await expect(spawnPromise).resolves.toBe('agent-test');
});
});
// ─── Fast-exiting child: events emitted during the post-spawn await (#5791) ─
it('does not drop stdout or close emitted while the post-spawn await is still yielding', async () => {
// The child's whole life cycle can land between spawn() and the point where
// the real stdout/stderr/close handler bodies are installed: the
// `updateAgent(agentId, { pid })` in between is real state-file I/O, so it
// yields for a macrotask, not just a microtask. A CLI that dies instantly
// (bad flag, instant auth refusal) exits inside that window — before the fix
// its output was lost and its `close` landed on nothing, leaving the run
// record, the execution lane and the activeAgents entry non-terminal until
// the orphan reaper eventually noticed.
const { activeAgents } = await import('./agentState.js');
const { finalizeAgent } = await import('./agentFinalization.js');
activeAgents.clear();
finalizeAgent.mockClear();
agentStateMocks.updateAgent.mockImplementationOnce(async () => {
// Emit from inside the same macrotask yield the real updateAgent creates.
await new Promise((r) => setImmediate(r));
fakeProcess.stdout.emit('data', Buffer.from(
'{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"unknown flag --nope\\n"}}}\n'
));
fakeProcess.emit('close', 2);
});
await expect(spawnDirectly(minimalArgs)).resolves.toBe('agent-test');
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });
expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
agentId: 'agent-test',
exitCode: 2,
success: false,
// The output the child managed to write before exiting is exactly what
// explains the failure, so it has to survive the buffering too.
outputBuffer: expect.stringContaining('unknown flag --nope'),
}));
expect(activeAgents.has('agent-test')).toBe(false);
});
// ─── Lifecycle ledger — the first-output boundary (#4540) ─────────────────
it('records ONE run.output on the first real byte, and never again', async () => {
// Bounded on purpose: a per-chunk event would make the ledger a copy of the
// output it deliberately redacts. What one event buys is time-to-first-output
// — the only thing that separates a run that stalled after speaking from one
// that never spoke at all.
appendRunEvent.mockClear();
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('{\"type\":\"result\",\"result\":\"one\"}\n'));
fakeProcess.stdout.emit('data', Buffer.from('{\"type\":\"result\",\"result\":\"two\"}\n'));
await new Promise((r) => setTimeout(r, 20));
const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
expect(outputs).toHaveLength(1);
expect(outputs[0]).toMatchObject({ runId: 'run-1', agentId: 'agent-test', taskId: 'task-1', data: { source: 'cli-stdout' } });
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('counts stderr-only output too — several providers say everything there', async () => {
// codex's entire progress feed is stderr and lands in the same transcript.
// A stdout-only recorder would file those runs as having produced nothing.
appendRunEvent.mockClear();
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stderr.emit('data', Buffer.from('thinking...\n'));
await new Promise((r) => setTimeout(r, 20));
const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
expect(outputs).toHaveLength(1);
expect(outputs[0].data).toMatchObject({ source: 'cli-stderr' });
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('records no run.output for a run that never produced any', async () => {
// The 3s initialization timer flips the record to "working" with nothing
// behind it, which is exactly the run this boundary must NOT vouch for.
appendRunEvent.mockClear();
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
fakeProcess.emit('close', 1);
await spawnPromise.catch(() => {});
expect(appendRunEvent.mock.calls.map(([e]) => e.kind)).not.toContain('run.output');
});
it.each([
['final result', { type: 'result', result: 'Saved a partial checkpoint.' }, 'Saved a partial checkpoint.'],
['missing result', null, ''],
['malformed result', { type: 'result', result: { text: 'invalid' } }, null],
])('passes only an explicit completion through finalization: %s', async (_label, result, expected) => {
const { finalizeAgent } = await import('./agentFinalization.js');
finalizeAgent.mockClear();
await spawnDirectly(minimalArgs);
const events = [
{ type: 'assistant', message: { content: [{ type: 'text', text: 'Thinking about files.' }] } },
{ type: 'assistant', message: { content: [{ type: 'text', text: 'Running another command.' }] } },
...(result ? [result] : []),
];
fakeProcess.stdout.emit('data', Buffer.from(events.map(event => JSON.stringify(event)).join('\n') + '\n'));
fakeProcess.stderr.emit('data', Buffer.from('trailing runner diagnostics\n'));
fakeProcess.emit('close', 0);
await vi.waitFor(() => expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({ finalSummary: expected })));
});
it('drains stdout output on close and a failed batch flush is logged, not leaked as an unhandled rejection', async () => {
// stdout output is now batched: the data handler pushes lines to the output
// batcher and the close handler drains it. Make the drain's state write fail
// and assert the batcher swallows+logs it with a ❌ prefix — no escape.
agentStateMocks.appendAgentOutputLines.mockRejectedValueOnce(new Error('db write failed'));
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const unhandledRejections = [];
const onUnhandled = (reason) => unhandledRejections.push(reason);
process.on('unhandledRejection', onUnhandled);
// Act: start spawnDirectly. Note: spawnDirectly awaits getClaudeSettingsEnv()
// before registering stdout/stderr listeners, so we must yield before emitting.
const spawnPromise = spawnDirectly(minimalArgs);
// Yield to let the await inside spawnDirectly resolve so listeners are registered.
await new Promise((r) => setTimeout(r, 10));
// Emit a stream-json text delta on stdout so the parser yields a line the
// handler enqueues into the batcher.
fakeProcess.stdout.emit('data', Buffer.from(
'{"type":"stream_event","event":{"type":"content_block_delta","delta":{"type":"text_delta","text":"hello\\n"}}}\n'
));
// Give the microtask queue a chance to drain so the async handler runs.
await new Promise((r) => setTimeout(r, 50));
// Trigger close so the batcher drains and spawnDirectly resolves.
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
process.off('unhandledRejection', onUnhandled);
// Assert: error was swallowed into console.error, not an unhandled rejection
expect(unhandledRejections).toHaveLength(0);
const logged = consoleSpy.mock.calls.some(
(args) => typeof args[0] === 'string' && args[0].startsWith('❌ agent agent-test state write failed')
);
expect(logged).toBe(true);
});
it('prepares the configured Ollama context before a direct CLI agent spawns', async () => {
vi.mocked(spawn).mockClear();
vi.mocked(ensureOllamaAgentContext).mockClear();
vi.mocked(isOllamaBackedProvider).mockReturnValue(true);
vi.mocked(ensureOllamaAgentContext).mockResolvedValue({
skipped: false,
applied: true,
contextLength: 131072,
warning: '⚠️ Example context warning',
});
const spawnPromise = spawnDirectly({
...minimalArgs,
provider: { ...minimalArgs.provider, id: 'claude-ollama', ollamaBacked: true },
});
await new Promise((r) => setTimeout(r, 10));
expect(ensureOllamaAgentContext).toHaveBeenCalledWith(
expect.objectContaining({ id: 'claude-ollama' }),
{ model: 'claude-3' },
);
expect(ensureOllamaAgentContext.mock.invocationCallOrder[0]).toBeLessThan(spawn.mock.invocationCallOrder[0]);
fakeProcess.emit('close', 0);
await spawnPromise;
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });
expect(agentStateMocks.appendAgentOutputLines).toHaveBeenCalledWith('agent-test', [
'⚠️ Example context warning',
'🪟 Reloaded Ollama at a 131072-token context window',
]);
});
it('drains stderr output on close and a failed batch flush is logged, not leaked as an unhandled rejection', async () => {
agentStateMocks.appendAgentOutputLines.mockRejectedValueOnce(new Error('stderr db write failed'));
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const unhandledRejections = [];
const onUnhandled = (reason) => unhandledRejections.push(reason);
process.on('unhandledRejection', onUnhandled);
const spawnPromise = spawnDirectly(minimalArgs);
// Yield to let the await inside spawnDirectly resolve so listeners are registered.
await new Promise((r) => setTimeout(r, 10));
// Emit data on stderr to enqueue a batched `[stderr] …` line.
fakeProcess.stderr.emit('data', Buffer.from('some stderr output\n'));
await new Promise((r) => setTimeout(r, 50));
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
process.off('unhandledRejection', onUnhandled);
expect(unhandledRejections).toHaveLength(0);
const logged = consoleSpy.mock.calls.some(
(args) => typeof args[0] === 'string' && args[0].startsWith('❌ agent agent-test state write failed')
);
expect(logged).toBe(true);
});
it('publishes a CLI transcript flush with its state batch before admitting a snapshot', async () => {
const fs = await vi.importActual('node:fs/promises');
const { tmpdir } = await import('node:os');
const { writeFileGuarded } = await import('../lib/fileUtils.js');
const { activeAgents } = await import('./agentState.js');
const { acquireBackupSnapshotCut } = await import('../lib/backupSnapshotBoundary.js');
const dir = await fs.mkdtemp(join(tmpdir(), 'cli-publication-'));
let reached; let finish;
const reachedPromise = new Promise(resolve => { reached = resolve; });
const finishPromise = new Promise(resolve => { finish = resolve; });
writeFileGuarded.mockImplementation((path, bytes, options) => fs.writeFile(path, bytes, options));
const persistedLines = [];
agentStateMocks.appendAgentOutputLines.mockImplementation(async (_id, batch) => {
reached(); await finishPromise;
persistedLines.push(...batch);
await fs.writeFile(join(dir, 'state.json'), JSON.stringify({ lines: persistedLines }));
});
try {
await spawnDirectly({ ...minimalArgs, agentDir: dir,
cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
fakeProcess.stdout.emit('data', Buffer.from('complete batch\n'));
const flushing = activeAgents.get('agent-test').flushOutput();
await reachedPromise;
// A later chunk must not change either member of the in-flight batch.
fakeProcess.stdout.emit('data', Buffer.from('later batch\n'));
await new Promise(resolve => setImmediate(resolve));
let acquired = false;
const cut = acquireBackupSnapshotCut().then(release => { acquired = true; return release; });
try { await new Promise(resolve => setImmediate(resolve)); expect(acquired).toBe(false); }
finally { finish(); }
await flushing;
const release = await cut;
try {
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete batch\n');
expect(JSON.parse(await fs.readFile(join(dir, 'state.json'), 'utf8')).lines).toEqual(['complete batch\n']);
} finally { release(); }
await activeAgents.get('agent-test').flushOutput();
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete batch\nlater batch\n');
expect(JSON.parse(await fs.readFile(join(dir, 'state.json'), 'utf8')).lines)
.toEqual(['complete batch\n', 'later batch\n']);
fakeProcess.emit('close', 0);
// Completion runs after the in-flight transcript write lands, and since
// #12025 every atomicWrite fsyncs: the Windows runner needs more than
// vi.waitFor's 1s default (observed 1045ms) while a never-called cleanup
// still fails within the budget.
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { timeout: 10_000 });
} finally {
finish();
writeFileGuarded.mockResolvedValue(undefined);
agentStateMocks.appendAgentOutputLines.mockResolvedValue(undefined);
await fs.rm(dir, { recursive: true, force: true });
}
});
describe('incremental transcript persistence', () => {
let fs;
let dir;
let writeFileGuarded;
let activeAgents;
beforeEach(async () => {
fs = await vi.importActual('node:fs/promises');
const { tmpdir } = await import('node:os');
({ writeFileGuarded } = await import('../lib/fileUtils.js'));
({ activeAgents } = await import('./agentState.js'));
dir = await fs.mkdtemp(join(tmpdir(), 'cli-transcript-'));
writeFileGuarded.mockReset();
writeFileGuarded.mockImplementation((path, bytes, options) => fs.writeFile(path, bytes, options));
});
afterEach(async () => {
publicationAdmission.bypass = false;
writeFileGuarded.mockResolvedValue(undefined);
await fs.rm(dir, { recursive: true, force: true });
});
const finish = async () => {
fakeProcess.emit('close', 0);
// Completion runs after the in-flight transcript write lands, and since
// #12025 every atomicWrite fsyncs: the Windows runner needs more than
// vi.waitFor's 1s default (observed 1045ms) while a never-called cleanup
// still fails within the budget.
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { timeout: 10_000 });
};
const emitTextAndFlush = async text => {
fakeProcess.stdout.emit('data', Buffer.from(text));
await activeAgents.get('agent-test').flushOutput();
};
it('writes a growing transcript once per byte plus the terminal rewrite, preserving mixed UTF-8 output', async () => {
// Each flush is a real file write, so wall time scales with the flush count and
// timed out at 240 under loaded pregate workers. The once-per-byte contract does
// not depend on cadence: full-prefix writes would submit O(n^2) bytes here
// (~9.6M for 393,216 bytes of output) versus the 786,432 that deltas plus the
// final rewrite need.
publicationAdmission.bypass = true;
await fs.writeFile(join(dir, 'output.txt'), 'stale previous transcript');
await spawnDirectly({ ...minimalArgs, agentDir: dir,
cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
const FLUSHES = 48;
const chunk = `é${'x'.repeat(8189)}\n`;
for (let i = 0; i < FLUSHES; i++) await emitTextAndFlush(chunk);
fakeProcess.stderr.emit('data', Buffer.from('尾\n'));
await activeAgents.get('agent-test').flushOutput();
const expected = `${chunk.repeat(FLUSHES)}[stderr] 尾\n`;
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe(expected);
await finish();
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe(expected);
const submittedBytes = writeFileGuarded.mock.calls.reduce((sum, [, bytes]) => sum + Buffer.byteLength(bytes), 0);
expect(submittedBytes).toBe(Buffer.byteLength(expected) * 2);
});
it('rewrites after an uncertain partial append instead of duplicating or dropping its bytes', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {});
await spawnDirectly({ ...minimalArgs, agentDir: dir,
cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
await emitTextAndFlush('first\n');
writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
await fs.writeFile(path, bytes.slice(0, 3), options);
throw Object.assign(new Error('synthetic partial write'), { code: 'EIO' });
});
await emitTextAndFlush('second\n');
await emitTextAndFlush('third\n');
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('first\nsecond\nthird\n');
expect(agentStateMocks.updateAgent).toHaveBeenCalledWith('agent-test', {
metadata: { transcriptWriteFailed: { file: 'output.txt', code: 'EIO' } },
});
await finish();
});
it('waits for an already draining transcript before a second manual drain can finish', async () => {
await spawnDirectly({ ...minimalArgs, agentDir: dir,
cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' } });
let reached;
let release;
const reachedPromise = new Promise(resolve => { reached = resolve; });
const blocked = new Promise(resolve => { release = resolve; });
writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
reached();
await blocked;
await fs.writeFile(path, bytes, options);
});
const first = emitTextAndFlush('complete before termination\n');
await reachedPromise;
let drained = false;
const second = activeAgents.get('agent-test').flushOutput().then(() => { drained = true; });
try {
await new Promise(resolve => setImmediate(resolve));
expect(drained).toBe(false);
} finally { release(); }
await Promise.all([first, second]);
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8')).toBe('complete before termination\n');
await finish();
});
it('replaces streamed progress with the authoritative result when close overlaps a write', async () => {
await spawnDirectly({ ...minimalArgs, agentDir: dir });
const delta = text => JSON.stringify({ type: 'stream_event', event: {
type: 'content_block_delta', delta: { type: 'text_delta', text },
} }) + '\n';
await emitTextAndFlush(delta('initial progress\n'));
let reached;
let release;
const reachedPromise = new Promise(resolve => { reached = resolve; });
const blocked = new Promise(resolve => { release = resolve; });
writeFileGuarded.mockImplementationOnce(async (path, bytes, options) => {
reached();
await blocked;
await fs.writeFile(path, bytes, options);
});
const flushing = emitTextAndFlush(delta('later progress\n'));
await reachedPromise;
fakeProcess.stdout.emit('data', Buffer.from(delta('last fragment') + JSON.stringify({
type: 'result', result: 'Final result that differs from the streamed progress.',
}) + '\n'));
const finishing = finish();
release();
await Promise.all([flushing, finishing]);
expect(await fs.readFile(join(dir, 'output.txt'), 'utf8'))
.toBe('Final result that differs from the streamed progress.');
});
});
it('detects a fallback signal and terminates immediately even while an earlier transcript write is blocked, keeping output ordered (#2384)', async () => {
killProcessTree.mockClear();
// Block the FIRST chunk's serialized transcript body at its phase-working
// updateAgent await (the pid updateAgent at spawn time carries no
// metadata.phase, so it resolves normally and lets spawn finish).
let releaseFirstWrite;
const firstWriteGate = new Promise((r) => { releaseFirstWrite = r; });
agentStateMocks.updateAgent.mockImplementation((id, patch) => {
if (patch?.metadata?.phase === 'working') return firstWriteGate;
return Promise.resolve(undefined);
});
// Non-stream provider so outputBuffer is raw text and ordering is trivial to assert.
const args = {
...minimalArgs,
cliConfig: { command: 'claude', args: [], stdinMode: 'prompt', streamFormat: 'text' },
};
const spawnPromise = spawnDirectly(args);
// Yield so spawnDirectly's awaits resolve and the stdout listener registers.
await new Promise((r) => setTimeout(r, 10));
// Chunk 1: ordinary output → its serialized write body blocks on the gate.
fakeProcess.stdout.emit('data', Buffer.from('first output line\n'));
await new Promise((r) => setTimeout(r, 10));
// Chunk 2: a usage-limit fallback signal arrives WHILE chunk 1 is blocked.
// The synchronous detector must fire the kill without waiting for the gate.
fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));
// Assert: termination was immediate — killProcessTree fired synchronously in
// the data listener, before the blocked first write could settle.
expect(killProcessTree).toHaveBeenCalledTimes(1);
expect(killProcessTree.mock.calls[0][1]).toBe('SIGTERM');
fakeProcess.killed = true;
// Release the gate, let the serialized chain drain, then close.
releaseFirstWrite();
await new Promise((r) => setTimeout(r, 20));
fakeProcess.emit('close', 143);
await spawnPromise.catch(() => {});
// Assert: the two chunks landed in emission order (serialized, not reordered
// by the blocked first write racing the second).
const allLines = agentStateMocks.appendAgentOutputLines.mock.calls.flatMap((c) => c[1]);
const firstIdx = allLines.findIndex((l) => l.includes('first output line'));
const usageIdx = allLines.findIndex((l) => l.includes('Now using extra usage'));
expect(firstIdx).toBeGreaterThanOrEqual(0);
expect(usageIdx).toBeGreaterThan(firstIdx);
});
// A headless CLI still colors its progress feed. `opencode run` wraps its
// status line in bare SGR resets, and those bytes used to reach the transcript
// verbatim — the browser drops only the ESC, so the agent card rendered
// `[stderr] [0m` and a working agent read as a wedged one.
describe('ANSI decoloring of headless CLI output', () => {
const textArgs = () => ({
...minimalArgs,
cliConfig: { command: 'opencode', args: ['run'], stdinMode: 'prompt', streamFormat: 'text' },
});
const emittedLines = () =>
agentStateMocks.appendAgentOutputLines.mock.calls.flatMap(([, batch]) => batch);
// The shared mock accumulates across the whole file; these assertions are
// about the exact transcript ONE run produced.
beforeEach(() => agentStateMocks.appendAgentOutputLines.mockClear());
it('strips color codes from stdout and stderr instead of leaking them into the transcript', async () => {
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('\x1B[32mbuilding\x1B[0m\n'));
fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m> build · some-model\n'));
await new Promise((r) => setTimeout(r, 30));
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
const lines = emittedLines();
expect(lines).toContain('building\n');
expect(lines).toContain('[stderr] > build · some-model\n');
expect(lines.join('')).not.toMatch(/\x1B|\[0m|\[32m/);
});
it('reassembles an escape sequence split across two chunks rather than leaking its tail', async () => {
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
// The reset straddles the chunk boundary: a per-chunk strip would emit `2m…`.
fakeProcess.stdout.emit('data', Buffer.from('ready\x1B['));
await new Promise((r) => setTimeout(r, 20));
fakeProcess.stdout.emit('data', Buffer.from('32mgreen\n'));
await new Promise((r) => setTimeout(r, 20));
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
expect(emittedLines().join('')).toBe('readygreen\n');
});
it('drops a chunk that was ONLY terminal control rather than tagging a blank [stderr] line', async () => {
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
fakeProcess.stdout.emit('data', Buffer.from('\x1B[0m'));
await new Promise((r) => setTimeout(r, 30));
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
expect(emittedLines()).not.toContain('[stderr] ');
expect(emittedLines().some((line) => line.trim() === '')).toBe(false);
});
it('drops the claude CLI SDK unrecognized-model telemetry line from the surfaced tail', async () => {
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stderr.emit('data', Buffer.from(
'[claude-code:unrecognized_model] {"model":"gemma3:27b","query_source":"sdk"}\n'
));
await new Promise((r) => setTimeout(r, 30));
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
expect(emittedLines().join('')).not.toMatch(/unrecognized_model/);
});
it('still records a colors-only chunk as run output — it is proof the child is alive', async () => {
// Counting the DECOLORED length would report zero bytes and file a run that
// was steadily redrawing its progress line as having produced nothing.
appendRunEvent.mockClear();
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stderr.emit('data', Buffer.from('\x1B[0m'));
await new Promise((r) => setTimeout(r, 30));
const outputs = appendRunEvent.mock.calls.map(([e]) => e).filter((e) => e.kind === 'run.output');
expect(outputs).toHaveLength(1);
expect(outputs[0].data).toMatchObject({ source: 'cli-stderr' });
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('detects a fallback signal that the CLI printed with color codes inside it', async () => {
// The detector matches provider prose; an SGR pair mid-sentence used to
// split the phrase and let a usage-limit signal through unnoticed.
killProcessTree.mockClear();
const spawnPromise = spawnDirectly(textArgs());
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('\x1B[33mNow using \x1B[1mextra usage\x1B[0m\n'));
expect(killProcessTree).toHaveBeenCalledTimes(1);
fakeProcess.killed = true;
await new Promise((r) => setTimeout(r, 20));
fakeProcess.emit('close', 143);
await spawnPromise.catch(() => {});
});
});
it('routes the CLI command through prepareCliSpawn and spawns its resolved+wrapped result (#2243)', async () => {
// The reported bug: on Windows a bare `opencode`/`claude` .cmd shim can't be
// spawned directly under shell:false → ENOENT (-4058) → startup-failure.
// spawnDirectly must hand the command through prepareCliSpawn (resolve +
// cmd.exe wrap) and spawn WHATEVER it returns — asserted here with a sentinel.
vi.mocked(prepareCliSpawn).mockReturnValueOnce({
command: 'cmd.exe',
args: ['/c', 'C:\\npm\\claude.cmd', '--print'],
});
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10)); // let the getClaudeSettingsEnv await settle
// Called with the logical command + args and the child env (PATH-bearing) so
// a provider PATH override is honored.
expect(prepareCliSpawn).toHaveBeenCalledWith(
minimalArgs.cliConfig.command,
minimalArgs.cliConfig.args,
expect.objectContaining({ PATH: expect.anything() }),
);
// spawn() received the resolved+wrapped pair, NOT the bare command.
expect(spawn).toHaveBeenCalledWith(
'cmd.exe',
['/c', 'C:\\npm\\claude.cmd', '--print'],
expect.objectContaining({ shell: false }),
);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('injects the repo-owner-pinned GH_TOKEN into the spawn env so the agent\'s own `gh` uses the right account', async () => {
const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
vi.mocked(resolveForgeTokenEnv).mockResolvedValueOnce({ GH_TOKEN: 'ghp_pinned_owner_token' });
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10)); // let the resolveForgeTokenEnv await settle
// Resolved against the workspace dir (the worktree the agent will PR from).
expect(resolveForgeTokenEnv).toHaveBeenCalledWith('/tmp');
expect(spawn).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ env: expect.objectContaining({ GH_TOKEN: 'ghp_pinned_owner_token' }) }),
);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
// The agent's own prompt hands it `curl`s against this install's API, which is
// gated whenever an instance password is set. The token is the only way an
// agent — which holds no browser cookie — can answer that gate.
it('injects the loopback PortOS API token into the spawn env', async () => {
const { resolveAgentApiEnv } = await import('./agentApiAuth.js');
vi.mocked(resolveAgentApiEnv).mockResolvedValueOnce({ PORTOS_API_TOKEN: 'portos-session-token' });
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10)); // let the resolveAgentApiEnv await settle
expect(spawn).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ env: expect.objectContaining({ PORTOS_API_TOKEN: 'portos-session-token' }) }),
);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('spawns a Creative Director task in an isolated scratch cwd, not the PortOS root (#4650)', async () => {
const { creativeDirectorScratchCwd } = await import('../lib/spawnCwd.js');
const args = {
...minimalArgs,
task: {
id: 'task-cd',
description: 'Evaluate scene',
metadata: { creativeDirector: { projectId: 'p', kind: 'evaluate' }, useWorktree: false },
},
workspacePath: '/tmp', // the previous default — must not win over the scratch path
};
const spawnPromise = spawnDirectly(args);
await new Promise((r) => setTimeout(r, 10));
const expectedCwd = creativeDirectorScratchCwd('agent-test');
expect(spawn).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ cwd: expectedCwd }),
);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('leaves the spawn env\'s ambient GH_TOKEN untouched when there is no owner match', async () => {
const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
vi.mocked(resolveForgeTokenEnv).mockResolvedValueOnce({});
const prev = process.env.GH_TOKEN;
process.env.GH_TOKEN = 'ghp_ambient';
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
expect(spawn).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ env: expect.objectContaining({ GH_TOKEN: 'ghp_ambient' }) }),
);
if (prev === undefined) delete process.env.GH_TOKEN; else process.env.GH_TOKEN = prev;
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('skips the owner-token probe when the provider supplies its own GITHUB_TOKEN', async () => {
const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
vi.mocked(resolveForgeTokenEnv).mockClear();
vi.mocked(spawn).mockClear();
const args = { ...minimalArgs, provider: { ...minimalArgs.provider, envVars: { GITHUB_TOKEN: 'ghp_provider_bot' } } };
const spawnPromise = spawnDirectly(args);
await new Promise((r) => setTimeout(r, 10));
// gh prefers GH_TOKEN over GITHUB_TOKEN — injecting the owner GH_TOKEN would
// shadow the provider's explicit bot credential, so the probe is skipped.
expect(resolveForgeTokenEnv).not.toHaveBeenCalled();
const env = vi.mocked(spawn).mock.calls.at(-1)[2].env;
expect(env.GITHUB_TOKEN).toBe('ghp_provider_bot');
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
describe('initialization timeout — 3-second phase transition', () => {
it('calls updateAgent with working phase after 3s when agent has not started working', async () => {
vi.useFakeTimers();
const { activeAgents } = await import('./agentState.js');
const agents = agentStateMocks;
const spawnPromise = spawnDirectly(minimalArgs);
// Yield two microtask rounds so the getClaudeSettingsEnv await resolves and
// the setTimeout is registered before we seed activeAgents.
await vi.advanceTimersByTimeAsync(10);
// Manually seed the activeAgents map so the guard inside the timeout passes.
activeAgents.set(minimalArgs.agentId, { process: fakeProcess });
await vi.advanceTimersByTimeAsync(3000);
expect(agents.updateAgent).toHaveBeenCalledWith(
minimalArgs.agentId,
{ metadata: { phase: 'working' } }
);
// Clean up: close the fake process so spawnDirectly can settle.
activeAgents.delete(minimalArgs.agentId);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('does NOT crash when updateAgent rejects inside the timeout callback', async () => {
vi.useFakeTimers();
const { activeAgents } = await import('./agentState.js');
// spawnDirectly calls updateAgent once synchronously (PID update at line ~406)
// before the 3-second setTimeout fires. Allow that first call to resolve
// normally so spawnDirectly doesn't throw before the timeout test begins;
// then reject the SECOND call (the phase-transition inside the timeout).
agentStateMocks.updateAgent
.mockResolvedValueOnce(undefined) // PID update — let it pass
.mockRejectedValueOnce(new Error('db write failed')); // timeout update — reject
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const unhandledRejections = [];
const onUnhandled = (reason) => unhandledRejections.push(reason);
process.on('unhandledRejection', onUnhandled);
const spawnPromise = spawnDirectly(minimalArgs);
await vi.advanceTimersByTimeAsync(10);
activeAgents.set(minimalArgs.agentId, { process: fakeProcess });
// Advance the initialization threshold and let the callback's rejected
// update settle without burning three seconds of wall clock.
await vi.advanceTimersByTimeAsync(3000);
process.off('unhandledRejection', onUnhandled);
expect(unhandledRejections).toHaveLength(0);
const logged = consoleSpy.mock.calls.some(
(args) => typeof args[0] === 'string' && args[0].startsWith('❌ agentCliSpawning init timeout failed')
);
expect(logged).toBe(true);
activeAgents.delete(minimalArgs.agentId);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
consoleSpy.mockRestore();
});
});
it('hands a slashdo-capable harness to the dispatch as owning its PR, with the claim expected', async () => {
const { finalizeAgent } = await import('./agentFinalization.js');
finalizeAgent.mockClear();
const task = {
id: 'task-rv',
description: 'do stuff',
metadata: { openPR: true, reviewers: ['codex', 'antigravity'], reviewStopMode: 'on-clean' },
};
spawnDirectly({ ...minimalArgs, task, prOpenedBy: stampPrOpenedBy(task) });
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('{"type":"result","result":"ok"}\n'));
await new Promise((r) => setTimeout(r, 50));
fakeProcess.emit('close', 0);
// spawnDirectly returns before the close handler's async cleanup finishes.
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledTimes(1), { interval: 5 });
// A claude-code CLI both owns its PR workflow and can type `/do:pr`, so
// finalize was expected to verify the claim (its mock here verified none).
// The reviewer metadata travels on the task; the dispatch resolves it against
// the Code Review Defaults (agentCompletionCleanup.test.js).
expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(expect.objectContaining({
agentId: minimalArgs.agentId,
task,
success: true,
prOwnership: { taskOpenPR: true, prOpenedBy: 'agent-slashdo', agentOpensOwnPr: true, prClaimExpected: true },
prClaimVerified: false,
}));
// The claim predicate, not the ownership one, is what finalize verifies (#3358).
expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({ prExpected: true }));
});
it('hands a read-only CLI run to PortOS using the prompt ownership stamp', async () => {
const task = { id: 'task-read-only', description: 'analyze the code', metadata: { openPR: true, readOnly: true } };
const spawnPromise = spawnDirectly({ ...minimalArgs, task, prOpenedBy: stampPrOpenedBy(task) });
await vi.waitFor(() => expect(fakeProcess.listenerCount('close')).toBeGreaterThan(0));
fakeProcess.emit('close', 0);
await spawnPromise;
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledTimes(1));
expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(expect.objectContaining({
prOwnership: { taskOpenPR: true, prOpenedBy: 'portos', agentOpensOwnPr: false, prClaimExpected: true },
}));
});
// The dispatch releases the retry hold with this verdict (#3368 — its ordering
// after worktree cleanup is pinned in agentCompletionCleanup.test.js). What
// this pins is that the close handler hands it the REAL verdict: a hardcoded
// value would stamp resume pointers on every completed run, or on none.
it('hands the dispatch the run verdict — failure on a non-zero exit, success on a clean one', async () => {
const task = { id: 'task-rp', description: 'do stuff', metadata: {} };
spawnDirectly({ ...minimalArgs, task });
await new Promise((r) => setTimeout(r, 10));
fakeProcess.emit('close', 1);
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(
expect.objectContaining({ agentId: minimalArgs.agentId, task, success: false }),
), { interval: 5 });
runSpawnerCompletionCleanup.mockClear();
fakeProcess = makeFakeProcess();
spawnDirectly({ ...minimalArgs, task: { id: 'task-rp-ok', description: 'do stuff', metadata: {} } });
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('{"type":"result","result":"ok"}\n'));
await new Promise((r) => setTimeout(r, 50));
fakeProcess.emit('close', 0);
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalledWith(
expect.objectContaining({ success: true }),
), { interval: 5 });
});
// pm2's TreeKill takes direct-CLI children down with portos-server exactly as
// it does TUI PTYs (#3202). Finalizing here would charge the task's failure
// budget — and possibly file an investigation task — for a fault the agent
// didn't have, and hand its worktree to cleanup, discarding the state a resume
// needs. The run is abandoned instead, leaving the record `running` for the
// next boot's orphan sweep to reconcile from the host-shutdown marker.
describe('host restart (#3202)', () => {
// The outer beforeEach re-sets implementations but not call history, and the
// mocks are module-scoped — clear so "was it called" reads only this test.
beforeEach(async () => {
const { finalizeAgent } = await import('./agentFinalization.js');
finalizeAgent.mockClear();
agentStateMocks.updateAgent.mockClear();
});
afterEach(() => resetHostShutdownFlagForTests());
const runToClose = async (args, code = 0) => {
spawnDirectly(args);
await new Promise((r) => setTimeout(r, 10));
markHostShuttingDown();
fakeProcess.emit('close', code);
};
it('abandons without finalizing or dispatching cleanup', async () => {
const { finalizeAgent } = await import('./agentFinalization.js');
await runToClose({ ...minimalArgs });
await vi.waitFor(() => expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
minimalArgs.agentId,
{ metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
), { interval: 5 });
expect(finalizeAgent).not.toHaveBeenCalled();
expect(runSpawnerCompletionCleanup).not.toHaveBeenCalled();
// The breadcrumb the orphan sweep falls back on when no marker names the agent.
expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
minimalArgs.agentId,
{ metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
);
});
it('still finalizes a user-terminated run so it is recorded as terminated, not resurrected', async () => {
const { userTerminatedAgents } = await import('./agentState.js');
const { finalizeAgent } = await import('./agentFinalization.js');
userTerminatedAgents.add(minimalArgs.agentId);
await runToClose({ ...minimalArgs });
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });
expect(finalizeAgent).toHaveBeenCalledWith(
expect.objectContaining({ terminatedByUser: true, success: false }),
);
userTerminatedAgents.delete(minimalArgs.agentId);
});
it('still finalizes when the agent already wrote its completion sentinel', async () => {
const { finalizeAgent } = await import('./agentFinalization.js');
// The sentinel is named per agent instance so two worktree-less runs
// sharing one workspace can't be finalized on each other's signal.
vi.mocked(existsSync).mockImplementation((path) =>
path === join(minimalArgs.workspacePath, '.agent-done-agent-test'));
await runToClose({ ...minimalArgs }, null);
await vi.waitFor(() => expect(runSpawnerCompletionCleanup).toHaveBeenCalled(), { interval: 5 });
expect(finalizeAgent).toHaveBeenCalledWith(
expect.objectContaining({
agentId: minimalArgs.agentId,
success: true,
workspacePath: minimalArgs.workspacePath,
}),
);
});
});
// ── Shared finalize-sequence contract (#6619) ────────────────────────────────
//
// The CLI close handler and the TUI `finish()` used to hold two hand-mirrored
// copies of this teardown, kept in sync by prose comments and running their two
// gates in OPPOSITE order. These three tests are the oracle for the invariants
// that mirroring protected — the same three, asserted the same way, live in
// agentTuiSpawning.test.js. They pin the lane/registry/marker effects that the
// other suites' finalizeAgent-argument assertions do not observe.
describe('shared finalize sequence (#6619)', () => {
beforeEach(async () => {
const { releaseAgentLane } = await import('./agentFinalization.js');
const { consumePausedAgentExit } = await import('./agentState.js');
releaseAgentLane.mockClear();
consumePausedAgentExit.mockClear();
agentStateMocks.updateAgent.mockClear();
});
afterEach(async () => {
const { pausedAgents, userTerminatedAgents } = await import('./agentState.js');
pausedAgents.clear();
userTerminatedAgents.clear();
resetHostShutdownFlagForTests();
});
// A paused run was already finalized (and lane-released) by markAgentPaused.
// Re-releasing the same executionId logs a spurious "Invalid state
// transition", so the paused gate must win over the host-shutdown gate.
it('paused run exiting during host shutdown takes the paused path, releasing no lane and writing no interrupted marker', async () => {
const { releaseAgentLane } = await import('./agentFinalization.js');
const { pausedAgents, consumePausedAgentExit, activeAgents } = await import('./agentState.js');
spawnDirectly({ ...minimalArgs });
await new Promise((r) => setTimeout(r, 10));
pausedAgents.set(minimalArgs.agentId, true);
markHostShuttingDown();
fakeProcess.emit('close', 0);
await vi.waitFor(() => expect(consumePausedAgentExit).toHaveBeenCalledWith(minimalArgs.agentId), { interval: 5 });
expect(releaseAgentLane).not.toHaveBeenCalled();
expect(activeAgents.has(minimalArgs.agentId)).toBe(false);
expect(agentStateMocks.updateAgent).not.toHaveBeenCalledWith(
minimalArgs.agentId,
{ metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
);
});
// The process can win the race and exit 0 after the user killed it. Recording
// that as a success leaves the task blocked with a "successful" run attached.
it('user-terminated run that exits 0 finalizes as failure with the terminated error', async () => {
const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');
const { userTerminatedAgents } = await import('./agentState.js');
userTerminatedAgents.add(minimalArgs.agentId);
spawnDirectly({ ...minimalArgs });
await new Promise((r) => setTimeout(r, 10));
fakeProcess.emit('close', 0);
await vi.waitFor(() => expect(finalizeAgent).toHaveBeenCalledWith(expect.objectContaining({
terminatedByUser: true,
success: false,
error: 'Agent terminated by user',
})), { interval: 5 });
expect(releaseAgentLane).toHaveBeenCalledWith(expect.objectContaining({
success: false,
errorExecutionMessage: 'Agent terminated by user',
}));
// Consumed, so a later resume of the same agent id is not misread as a kill.
expect(userTerminatedAgents.has(minimalArgs.agentId)).toBe(false);
});
// pm2's TreeKill took the child down with portos-server. The run has no
// outcome: leave the record `running` for the next boot's orphan sweep and
// do NOT release the lane through the finalize path.
it('run interrupted by host shutdown with no sentinel is abandoned without releasing its lane', async () => {
const { finalizeAgent, releaseAgentLane } = await import('./agentFinalization.js');
spawnDirectly({ ...minimalArgs });
await new Promise((r) => setTimeout(r, 10));
markHostShuttingDown();
fakeProcess.emit('close', 0);
await vi.waitFor(() => expect(agentStateMocks.updateAgent).toHaveBeenCalledWith(
minimalArgs.agentId,
{ metadata: { phase: 'interrupted', interruptedBy: 'host-shutdown' } },
), { interval: 5 });
expect(releaseAgentLane).not.toHaveBeenCalled();
expect(finalizeAgent).not.toHaveBeenCalled();
// A restart the operator caused, preserved for resume, is the normal path: info, never warn.
expect(emitLog).toHaveBeenCalledWith('info', expect.stringContaining('interrupted by a PortOS host restart'), expect.any(Object));
expect(emitLog).not.toHaveBeenCalledWith('warn', expect.stringContaining('interrupted by a PortOS host restart'), expect.anything());
});
});
// #7496. With a credentialBootstrap provider the direct child is the user's
// bootstrap CLI, not the harness — and `<bootstrap> run <harness> -- <args>`
// is the shape of a supervising PARENT, not an exec-replacement. A per-pid
// SIGTERM would leave the harness running (possibly with
// `--dangerously-skip-permissions` in a worktree, holding a freshly minted
// credential) after the agent is finalized and its lane released.
describe('credential-bootstrap process-group teardown', () => {
const bootstrapArgs = {
...minimalArgs,
provider: {
...minimalArgs.provider,
credentialBootstrap: { command: 'token-cli', args: ['run'], argsSeparator: '--' },
},
};
it('spawns a bootstrap-wrapped child detached and records the flag for the stop paths', async () => {
const { spawn } = await import('../lib/childProcess.js');
const { activeAgents } = await import('./agentState.js');
activeAgents.clear();
spawn.mockClear();
const spawnPromise = spawnDirectly(bootstrapArgs);
await vi.waitFor(() => expect(activeAgents.has(bootstrapArgs.agentId)).toBe(true), { interval: 5 });
const [command, , options] = spawn.mock.calls.at(-1);
expect(command).toBe('token-cli');
expect(options.detached).toBe(EXPECT_GROUP);
// agentManagement's pause/terminate/force-kill hold only this entry and
// cannot re-derive the wrap, so the flag has to travel with it.
expect(activeAgents.get(bootstrapArgs.agentId).processGroup).toBe(EXPECT_GROUP);
activeAgents.delete(bootstrapArgs.agentId);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('leaves an unwrapped provider attached with no group flag', async () => {
const { spawn } = await import('../lib/childProcess.js');
const { activeAgents } = await import('./agentState.js');
activeAgents.clear();
spawn.mockClear();
const spawnPromise = spawnDirectly(minimalArgs);
await vi.waitFor(() => expect(activeAgents.has(minimalArgs.agentId)).toBe(true), { interval: 5 });
const [, , options] = spawn.mock.calls.at(-1);
expect(options.detached).toBe(false);
expect(activeAgents.get(minimalArgs.agentId).processGroup).toBe(false);
activeAgents.delete(minimalArgs.agentId);
fakeProcess.emit('close', 0);
await spawnPromise.catch(() => {});
});
it('kills by process group when a provider-fallback signal stops a wrapped run', async () => {
killProcessTree.mockClear();
const spawnPromise = spawnDirectly(bootstrapArgs);
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));
expect(killProcessTree).toHaveBeenCalledTimes(1);
expect(killProcessTree.mock.calls[0][1]).toBe('SIGTERM');
expect(killProcessTree.mock.calls[0][2]).toEqual({ processGroup: EXPECT_GROUP });
fakeProcess.killed = true;
fakeProcess.emit('close', 143);
await spawnPromise.catch(() => {});
});
it('kills by pid alone when the same signal stops an UNWRAPPED run', async () => {
killProcessTree.mockClear();
const spawnPromise = spawnDirectly(minimalArgs);
await new Promise((r) => setTimeout(r, 10));
fakeProcess.stdout.emit('data', Buffer.from('Now using extra usage\n'));
expect(killProcessTree).toHaveBeenCalledTimes(1);
expect(killProcessTree.mock.calls[0][2]).toEqual({ processGroup: false });
fakeProcess.killed = true;
fakeProcess.emit('close', 143);
await spawnPromise.catch(() => {});
});
});
});