Provider '${entry.id}' cannot advertise sessionFork without

Error message

Provider '${entry.id}' cannot advertise sessionFork without sessionResume

What it means

The provider registry enforces capability consistency at registration: sessionFork (starting a new run that continues from an existing session) is only meaningful if the provider also supports sessionResume (re-opening an existing session). A provider advertising fork without resume would promise a capability it cannot deliver, so assertValidCapabilities throws during registerProvider or registerBuiltinProviders.

Source

Thrown at packages/providers/src/registry.ts:40

import { registerCopilotProvider } from './community/copilot/registration';
import { registerOpencodeProvider } from './community/opencode/registration';
import { registerPiProvider } from './community/pi/registration';
import { InvalidProviderRunConfigError, UnknownProviderError } from './errors';
import { createLogger } from '@archon/paths';

/** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
let cachedLog: ReturnType<typeof createLogger> | undefined;
function getLog(): ReturnType<typeof createLogger> {
  if (!cachedLog) cachedLog = createLogger('provider.registry');
  return cachedLog;
}

/** Backing store for registered providers. */
const registry = new Map<string, ProviderRegistration>();

function assertValidCapabilities(entry: ProviderRegistration): void {
  if (entry.capabilities.sessionFork === true && !entry.capabilities.sessionResume) {
    throw new Error(`Provider '${entry.id}' cannot advertise sessionFork without sessionResume`);
  }
}

/**
 * Register a provider. Throws on duplicate registration.
 */
export function registerProvider(entry: ProviderRegistration): void {
  if (registry.has(entry.id)) {
    throw new Error(`Provider '${entry.id}' is already registered`);
  }
  assertValidCapabilities(entry);
  registry.set(entry.id, entry);
  getLog().debug({ provider: entry.id, builtIn: entry.builtIn }, 'provider.registered');
}

/**
 * Get an instantiated agent provider by ID.
 * @throws UnknownProviderError if not registered

View on GitHub (pinned to 0773b97458)

Solutions

Set capabilities.sessionResume: true alongside sessionFork in the provider registration
If the provider truly cannot resume sessions, remove the sessionFork: true flag
Fix the builtin/registration code if a recent edit accidentally dropped sessionResume

Example fix

// before
registerProvider({ id: 'myprovider', capabilities: { sessionFork: true } });
// after
registerProvider({ id: 'myprovider', capabilities: { sessionFork: true, sessionResume: true } });

Defensive patterns

Strategy: validation

Validate before calling

function assertForkNeedsResume(caps: ProviderCapabilities): void {
  if (caps.sessionFork === true && !caps.sessionResume) {
    throw new Error('sessionFork requires sessionResume');
  }
}

Type guard

function forkIsValid(c: ProviderCapabilities): boolean {
  return c.sessionFork !== true || c.sessionResume === true;
}

Try / catch

try {
  registerProvider(entry);
} catch (err) {
  if (String(err.message).includes('sessionFork without sessionResume')) {
    console.error(`Fix capabilities for provider ${entry.id}`);
  }
  throw err;
}

Prevention

Type capability objects so sessionResume is required when sessionFork is true
Copy capability blocks from a valid builtin registration
Run registration tests that touch every custom provider

When it happens

Trigger: registerProvider({ id, capabilities: { sessionFork: true, sessionResume: false|undefined }, ... }) — fork set true while resume unset/false.

Common situations: Hand-writing a custom provider registration and ticking capabilities without understanding their dependency; copying a capabilities object and editing one flag; a refactor that accidentally dropped sessionResume from a builtin.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/85670e630bd352d2. Report an issue: GitHub.