oxe-cc 1.0.0 → 1.2.1

package/packages/runtime/src/plugins/plugin-manifest.ts

@@ -0,0 +1,113 @@
+import type { OxePlugin } from './plugin-abi';
+
+export const CURRENT_ABI_VERSION = '1.0.0';
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  abi_version: string;
+  capabilities: Array<'tool' | 'workspace' | 'verifier' | 'context' | 'hooks'>;
+  tool_action_types?: string[];
+  workspace_strategies?: string[];
+  verifier_check_types?: string[];
+  context_provider_names?: string[];
+  hook_names?: string[];
+}
+
+export interface PluginValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export function extractManifest(plugin: OxePlugin): PluginManifest {
+  const capabilities: PluginManifest['capabilities'] = [];
+  if (plugin.toolProviders?.length) capabilities.push('tool');
+  if (plugin.workspaceProviders?.length) capabilities.push('workspace');
+  if (plugin.verifierProviders?.length) capabilities.push('verifier');
+  if (plugin.contextProviders?.length) capabilities.push('context');
+  if (plugin.hooks && Object.keys(plugin.hooks).length > 0) capabilities.push('hooks');
+
+  return {
+    name: plugin.name,
+    version: plugin.version ?? '0.0.0',
+    abi_version: CURRENT_ABI_VERSION,
+    capabilities,
+    tool_action_types: plugin.toolProviders?.flatMap((p) =>
+      ['read_code', 'generate_patch', 'run_tests', 'collect_evidence', 'custom'].filter((t) => p.supports(t))
+    ) ?? [],
+    workspace_strategies: plugin.workspaceProviders?.map((p) => p.name) ?? [],
+    verifier_check_types: plugin.verifierProviders?.flatMap((p) =>
+      ['unit', 'integration', 'smoke', 'policy', 'security', 'custom'].filter((t) => p.supports(t))
+    ) ?? [],
+    context_provider_names: plugin.contextProviders?.map((p) => p.name) ?? [],
+    hook_names: plugin.hooks ? Object.keys(plugin.hooks) : [],
+  };
+}
+
+export function validatePlugin(plugin: OxePlugin): PluginValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!plugin.name || typeof plugin.name !== 'string') {
+    errors.push('Plugin must have a non-empty string name');
+  }
+
+  if (plugin.version && !/^\d+\.\d+\.\d+/.test(plugin.version)) {
+    warnings.push(`Plugin version "${plugin.version}" does not follow semver`);
+  }
+
+  if (!plugin.toolProviders?.length &&
+      !plugin.workspaceProviders?.length &&
+      !plugin.verifierProviders?.length &&
+      !plugin.contextProviders?.length &&
+      !plugin.hooks) {
+    warnings.push('Plugin declares no providers or hooks — it has no effect');
+  }
+
+  // Validate each tool provider
+  for (const tp of plugin.toolProviders ?? []) {
+    if (!tp.name) errors.push('ToolProvider missing name');
+    if (typeof tp.supports !== 'function') errors.push(`ToolProvider "${tp.name}" missing supports() method`);
+    if (typeof tp.invoke !== 'function') errors.push(`ToolProvider "${tp.name}" missing invoke() method`);
+  }
+
+  // Validate each workspace provider
+  for (const wp of plugin.workspaceProviders ?? []) {
+    if (!wp.name) errors.push('WorkspaceProvider missing name');
+    if (typeof wp.supportsStrategy !== 'function') errors.push(`WorkspaceProvider "${wp.name}" missing supportsStrategy()`);
+    if (typeof wp.allocate !== 'function') errors.push(`WorkspaceProvider "${wp.name}" missing allocate()`);
+  }
+
+  // Validate each verifier provider
+  for (const vp of plugin.verifierProviders ?? []) {
+    if (!vp.name) errors.push('VerifierProvider missing name');
+    if (typeof vp.supports !== 'function') errors.push(`VerifierProvider "${vp.name}" missing supports()`);
+    if (typeof vp.execute !== 'function') errors.push(`VerifierProvider "${vp.name}" missing execute()`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export function isAbiCompatible(pluginAbiVersion: string): boolean {
+  // Major version must match; minor/patch are backwards-compatible
+  const [currMajor] = CURRENT_ABI_VERSION.split('.').map(Number);
+  const [plugMajor] = pluginAbiVersion.split('.').map(Number);
+  return currMajor === plugMajor;
+}
+
+export function sandboxInvoke<T>(
+  fn: () => Promise<T>,
+  timeoutMs = 10_000
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Plugin invocation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    fn().then(
+      (result) => { clearTimeout(timer); resolve(result); },
+      (err) => { clearTimeout(timer); reject(err instanceof Error ? err : new Error(String(err))); }
+    );
+  });
+}

package/packages/runtime/src/plugins/plugin-registry.ts

@@ -7,6 +7,7 @@ import type {
   VerifierProvider,
   ContextProvider,
 } from './plugin-abi';
+import { validatePlugin } from './plugin-manifest';
 
 export class PluginRegistry {
   private plugins: OxePlugin[] = [];
@@ -15,6 +16,10 @@ export class PluginRegistry {
     if (this.plugins.some((p) => p.name === plugin.name)) {
       throw new Error(`Plugin "${plugin.name}" is already registered`);
     }
+    const validation = validatePlugin(plugin);
+    if (!validation.valid && validation.errors.length > 0) {
+      throw new Error(`Plugin "${plugin.name}" failed validation: ${validation.errors.join('; ')}`);
+    }
     this.plugins.push(plugin);
   }
 

package/packages/runtime/src/policy/policy-engine.ts

@@ -1,15 +1,42 @@
 export type PolicyAction = 'allow' | 'deny' | 'require_human_gate';
 
+export type SideEffectClass =
+  | 'read_fs'
+  | 'write_fs'
+  | 'spawn_process'
+  | 'network_call'
+  | 'git_mutation'
+  | 'db_change'
+  | 'secret_access'
+  | 'infra_operation';
+
+export type AutonomyTier = 'L0' | 'L1' | 'L2' | 'L3';
+
 export interface PolicyWhenClause {
   tool?: string;
   env?: string;
   kind?: string;
+  side_effect_class?: SideEffectClass;
+  autonomy_tier?: AutonomyTier;
 }
 
 export interface PolicyAssertClause {
   diff_within_scope?: boolean;
 }
 
+export interface NodePolicyConfig {
+  max_retries: number;
+  mutation_budget?: number;
+  autonomy_tier?: AutonomyTier;
+  allowed_side_effects?: SideEffectClass[];
+}
+
+export interface EnvironmentGuardrail {
+  protected_paths: string[];
+  protected_branches: string[];
+  require_human_gate_on: SideEffectClass[];
+}
+
 export interface PolicyRule {
   id: string;
   when: PolicyWhenClause;
@@ -23,6 +50,10 @@ export interface PolicyContext {
   kind?: string;
   mutation_scope?: string[];
   affected_paths?: string[];
+  side_effect_class?: SideEffectClass;
+  autonomy_tier?: AutonomyTier;
+  mutation_count?: number;
+  node_policy?: NodePolicyConfig;
 }
 
 export interface PolicyDecision {
@@ -39,10 +70,40 @@ const ALLOW_ALL: PolicyDecision = {
   rule_id: null,
 };
 
+const DEFAULT_GUARDRAIL: EnvironmentGuardrail = {
+  protected_paths: ['.oxe/config.json', '.env', 'package.json'],
+  protected_branches: ['main', 'master', 'production', 'release'],
+  require_human_gate_on: ['infra_operation', 'db_change', 'secret_access'],
+};
+
+// Autonomy tier → max side effect class allowed without a gate
+const TIER_SIDE_EFFECT_MAP: Record<AutonomyTier, SideEffectClass[]> = {
+  L0: ['read_fs'],
+  L1: ['read_fs', 'write_fs', 'spawn_process'],
+  L2: ['read_fs', 'write_fs', 'spawn_process', 'network_call', 'git_mutation'],
+  L3: ['read_fs', 'write_fs', 'spawn_process', 'network_call', 'git_mutation', 'db_change', 'secret_access', 'infra_operation'],
+};
+
 export class PolicyEngine {
-  constructor(private readonly rules: PolicyRule[] = []) {}
+  constructor(
+    private readonly rules: PolicyRule[] = [],
+    private readonly guardrail: EnvironmentGuardrail = DEFAULT_GUARDRAIL
+  ) {}
 
   evaluate(ctx: PolicyContext): PolicyDecision {
+    // Check autonomy tier first — a denial takes priority over guardrail gates
+    const tierDecision = this.checkAutonomyTier(ctx);
+    if (tierDecision) return tierDecision;
+
+    // Check environment guardrails (may require gate even when tier permits)
+    const guardrailDecision = this.checkGuardrails(ctx);
+    if (guardrailDecision) return guardrailDecision;
+
+    // Check mutation budget
+    const budgetDecision = this.checkMutationBudget(ctx);
+    if (budgetDecision) return budgetDecision;
+
+    // Evaluate rules (first match wins)
     for (const rule of this.rules) {
       if (!this.matches(rule.when, ctx)) continue;
 
@@ -67,13 +128,72 @@ export class PolicyEngine {
           return { allowed: true, gate_required: true, reason: `Gate required by rule ${rule.id}`, rule_id: rule.id };
       }
     }
+
     return ALLOW_ALL;
   }
 
+  private checkGuardrails(ctx: PolicyContext): PolicyDecision | null {
+    // Protected path check
+    const affected = ctx.affected_paths ?? [];
+    for (const p of affected) {
+      if (this.guardrail.protected_paths.some((pp) => p === pp || p.startsWith(pp + '/'))) {
+        return {
+          allowed: true,
+          gate_required: true,
+          reason: `Protected path affected: ${p}`,
+          rule_id: '__guardrail_path',
+        };
+      }
+    }
+
+    // Side effect class requiring gate
+    if (ctx.side_effect_class && this.guardrail.require_human_gate_on.includes(ctx.side_effect_class)) {
+      return {
+        allowed: true,
+        gate_required: true,
+        reason: `Side effect class '${ctx.side_effect_class}' requires human gate`,
+        rule_id: '__guardrail_side_effect',
+      };
+    }
+
+    return null;
+  }
+
+  private checkAutonomyTier(ctx: PolicyContext): PolicyDecision | null {
+    if (!ctx.autonomy_tier || !ctx.side_effect_class) return null;
+    const allowed = TIER_SIDE_EFFECT_MAP[ctx.autonomy_tier] ?? [];
+    if (!allowed.includes(ctx.side_effect_class)) {
+      return {
+        allowed: false,
+        gate_required: false,
+        reason: `Autonomy tier ${ctx.autonomy_tier} does not permit side effect '${ctx.side_effect_class}'`,
+        rule_id: '__autonomy_tier',
+      };
+    }
+    return null;
+  }
+
+  private checkMutationBudget(ctx: PolicyContext): PolicyDecision | null {
+    const budget = ctx.node_policy?.mutation_budget;
+    if (budget === undefined || budget === null) return null;
+    const count = ctx.mutation_count ?? 0;
+    if (count >= budget) {
+      return {
+        allowed: false,
+        gate_required: false,
+        reason: `Mutation budget exhausted: ${count}/${budget}`,
+        rule_id: '__mutation_budget',
+      };
+    }
+    return null;
+  }
+
   private matches(when: PolicyWhenClause, ctx: PolicyContext): boolean {
     if (when.tool && when.tool !== ctx.tool) return false;
     if (when.env && when.env !== ctx.env) return false;
     if (when.kind && when.kind !== ctx.kind) return false;
+    if (when.side_effect_class && when.side_effect_class !== ctx.side_effect_class) return false;
+    if (when.autonomy_tier && when.autonomy_tier !== ctx.autonomy_tier) return false;
     return true;
   }
 
@@ -81,7 +201,7 @@ export class PolicyEngine {
     if (assert.diff_within_scope === true) {
       const scope = ctx.mutation_scope ?? [];
       const affected = ctx.affected_paths ?? [];
-      if (scope.length === 0) return null; // no scope declared — pass
+      if (scope.length === 0) return null;
       const outsideScope = affected.filter(
         (p) => !scope.some((s) => p.startsWith(s) || s.startsWith(p))
       );
@@ -93,21 +213,32 @@ export class PolicyEngine {
   }
 
   withRule(rule: PolicyRule): PolicyEngine {
-    return new PolicyEngine([...this.rules, rule]);
+    return new PolicyEngine([...this.rules, rule], this.guardrail);
+  }
+
+  withGuardrail(guardrail: EnvironmentGuardrail): PolicyEngine {
+    return new PolicyEngine(this.rules, guardrail);
   }
 
-  static fromConfig(config: { policies?: PolicyRule[] }): PolicyEngine {
-    return new PolicyEngine(config.policies ?? []);
+  getGuardrail(): EnvironmentGuardrail {
+    return this.guardrail;
+  }
+
+  static fromConfig(config: { policies?: PolicyRule[]; guardrail?: EnvironmentGuardrail }): PolicyEngine {
+    return new PolicyEngine(config.policies ?? [], config.guardrail ?? DEFAULT_GUARDRAIL);
   }
 
   static fromConfigFile(configPath: string): PolicyEngine {
     try {
-      // Dynamic require to avoid bundling issues
       // eslint-disable-next-line @typescript-eslint/no-var-requires
-      const cfg = require(configPath) as { policies?: PolicyRule[] };
+      const cfg = require(configPath) as { policies?: PolicyRule[]; guardrail?: EnvironmentGuardrail };
       return PolicyEngine.fromConfig(cfg);
     } catch {
       return new PolicyEngine();
     }
   }
+
+  static defaultGuardrail(): EnvironmentGuardrail {
+    return { ...DEFAULT_GUARDRAIL };
+  }
 }

package/packages/runtime/src/reducers/run-state-reducer.ts

@@ -4,6 +4,19 @@ import type { WorkItem } from '../models/work-item';
 import type { Attempt } from '../models/attempt';
 import type { Workspace } from '../models/workspace';
 
+export interface PolicyDecisionRecord {
+  allowed: boolean;
+  gate_required: boolean;
+  reason: string;
+  rule_id: string | null;
+}
+
+export interface ToolFailureRecord {
+  tool: string;
+  error: string;
+  timestamp: string;
+}
+
 export interface RunState {
   run: Run | null;
   workItems: Map<string, WorkItem>;
@@ -12,6 +25,14 @@ export interface RunState {
   completedWorkItems: Set<string>;
   failedWorkItems: Set<string>;
   blockedWorkItems: Set<string>;
+  // Phase 1 extensions
+  retryCounts: Map<string, number>;
+  policyDecisions: Map<string, PolicyDecisionRecord>;
+  pendingGates: Set<string>;
+  resolvedGates: Map<string, { decision: string; actor?: string }>;
+  verificationStatus: Map<string, 'started' | 'completed' | 'failed'>;
+  evidenceRefs: Map<string, string[]>;
+  toolFailures: Map<string, ToolFailureRecord[]>;
 }
 
 export function createEmptyRunState(): RunState {
@@ -23,6 +44,13 @@ export function createEmptyRunState(): RunState {
     completedWorkItems: new Set(),
     failedWorkItems: new Set(),
     blockedWorkItems: new Set(),
+    retryCounts: new Map(),
+    policyDecisions: new Map(),
+    pendingGates: new Set(),
+    resolvedGates: new Map(),
+    verificationStatus: new Map(),
+    evidenceRefs: new Map(),
+    toolFailures: new Map(),
   };
 }
 
@@ -56,7 +84,6 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (existing) {
         workItems.set(event.work_item_id, { ...existing, status: 'ready' });
       } else {
-        // First time we see this work item — create from payload
         const item = event.payload as unknown as WorkItem;
         workItems.set(event.work_item_id, { ...item, work_item_id: event.work_item_id, status: 'ready' });
       }
@@ -97,6 +124,14 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (item) workItems.set(event.work_item_id, { ...item, status: 'completed' });
       const completedWorkItems = new Set(state.completedWorkItems);
       completedWorkItems.add(event.work_item_id);
+      // Collect evidence refs from payload
+      const evidence = (event.payload as { evidence?: string[] }).evidence ?? [];
+      if (evidence.length > 0) {
+        const evidenceRefs = new Map(state.evidenceRefs);
+        const existing = evidenceRefs.get(event.work_item_id) ?? [];
+        evidenceRefs.set(event.work_item_id, [...existing, ...evidence]);
+        return { ...state, workItems, completedWorkItems, evidenceRefs };
+      }
       return { ...state, workItems, completedWorkItems };
     }
 
@@ -110,6 +145,93 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       return { ...state, workItems, blockedWorkItems };
     }
 
+    case 'RetryScheduled': {
+      if (!event.work_item_id) return state;
+      const retryCounts = new Map(state.retryCounts);
+      const current = retryCounts.get(event.work_item_id) ?? 0;
+      retryCounts.set(event.work_item_id, current + 1);
+      return { ...state, retryCounts };
+    }
+
+    case 'PolicyEvaluated': {
+      const p = event.payload as {
+        work_item_id?: string;
+        allowed?: boolean;
+        gate_required?: boolean;
+        reason?: string;
+        rule_id?: string | null;
+      };
+      const key = p.work_item_id ?? event.work_item_id;
+      if (!key) return state;
+      const policyDecisions = new Map(state.policyDecisions);
+      policyDecisions.set(key, {
+        allowed: p.allowed ?? true,
+        gate_required: p.gate_required ?? false,
+        reason: p.reason ?? '',
+        rule_id: p.rule_id ?? null,
+      });
+      return { ...state, policyDecisions };
+    }
+
+    case 'GateRequested': {
+      const gateId = (event.payload as { gate_id?: string }).gate_id;
+      if (!gateId) return state;
+      const pendingGates = new Set(state.pendingGates);
+      pendingGates.add(gateId);
+      return { ...state, pendingGates };
+    }
+
+    case 'GateResolved': {
+      const p = event.payload as { gate_id?: string; decision?: string; actor?: string };
+      if (!p.gate_id) return state;
+      const pendingGates = new Set(state.pendingGates);
+      pendingGates.delete(p.gate_id);
+      const resolvedGates = new Map(state.resolvedGates);
+      resolvedGates.set(p.gate_id, { decision: p.decision ?? 'approved', actor: p.actor });
+      return { ...state, pendingGates, resolvedGates };
+    }
+
+    case 'VerificationStarted': {
+      const key = event.work_item_id ?? (event.payload as { work_item_id?: string }).work_item_id;
+      if (!key) return state;
+      const verificationStatus = new Map(state.verificationStatus);
+      verificationStatus.set(key, 'started');
+      return { ...state, verificationStatus };
+    }
+
+    case 'VerificationCompleted': {
+      const p = event.payload as { work_item_id?: string; status?: 'completed' | 'failed' };
+      const key = event.work_item_id ?? p.work_item_id;
+      if (!key) return state;
+      const verificationStatus = new Map(state.verificationStatus);
+      verificationStatus.set(key, p.status ?? 'completed');
+      return { ...state, verificationStatus };
+    }
+
+    case 'ToolFailed': {
+      if (!event.work_item_id) return state;
+      const p = event.payload as { tool?: string; error?: string };
+      const toolFailures = new Map(state.toolFailures);
+      const existing = toolFailures.get(event.work_item_id) ?? [];
+      toolFailures.set(event.work_item_id, [
+        ...existing,
+        { tool: p.tool ?? 'unknown', error: p.error ?? '', timestamp: event.timestamp },
+      ]);
+      return { ...state, toolFailures };
+    }
+
+    case 'EvidenceCollected': {
+      const p = event.payload as { work_item_id?: string; refs?: string[]; ref?: string };
+      const key = event.work_item_id ?? p.work_item_id;
+      if (!key) return state;
+      const refs = p.refs ?? (p.ref ? [p.ref] : []);
+      if (refs.length === 0) return state;
+      const evidenceRefs = new Map(state.evidenceRefs);
+      const existing = evidenceRefs.get(key) ?? [];
+      evidenceRefs.set(key, [...existing, ...refs]);
+      return { ...state, evidenceRefs };
+    }
+
     default:
       return state;
   }
@@ -125,3 +247,23 @@ export function getWorkItemStatus(
 export function getAttemptCount(state: RunState, workItemId: string): number {
   return state.attempts.get(workItemId)?.length ?? 0;
 }
+
+export function getRetryCount(state: RunState, workItemId: string): number {
+  return state.retryCounts.get(workItemId) ?? 0;
+}
+
+export function getPolicyDecision(state: RunState, workItemId: string): PolicyDecisionRecord | null {
+  return state.policyDecisions.get(workItemId) ?? null;
+}
+
+export function getVerificationStatus(state: RunState, workItemId: string): 'started' | 'completed' | 'failed' | null {
+  return state.verificationStatus.get(workItemId) ?? null;
+}
+
+export function getEvidenceRefs(state: RunState, workItemId: string): string[] {
+  return state.evidenceRefs.get(workItemId) ?? [];
+}
+
+export function getToolFailures(state: RunState, workItemId: string): ToolFailureRecord[] {
+  return state.toolFailures.get(workItemId) ?? [];
+}

package/packages/runtime/src/scheduler/agent-registry.ts

@@ -0,0 +1,132 @@
+import type { TaskExecutor } from './scheduler';
+import type { WorkspaceManager } from '../workspace/workspace-manager';
+import type { AgentRole, AgentActionLog } from './agent-roles';
+
+export type AgentStatus = 'idle' | 'running' | 'paused' | 'failed' | 'timeout';
+
+export interface AgentHeartbeat {
+  agent_id: string;
+  last_seen: string;
+  current_task: string | null;
+  status: AgentStatus;
+}
+
+export interface RegisteredAgent {
+  id: string;
+  executor: TaskExecutor;
+  workspaceManager: WorkspaceManager;
+  assignedTaskIds: string[];
+  heartbeat: AgentHeartbeat;
+  role?: AgentRole;
+  actionLog: AgentActionLog[];
+}
+
+export class AgentRegistry {
+  private agents = new Map<string, RegisteredAgent>();
+  private readonly heartbeatTimeoutMs: number;
+
+  constructor(heartbeatTimeoutMs = 30_000) {
+    this.heartbeatTimeoutMs = heartbeatTimeoutMs;
+  }
+
+  register(
+    id: string,
+    executor: TaskExecutor,
+    workspaceManager: WorkspaceManager,
+    assignedTaskIds: string[] = [],
+    role?: AgentRole
+  ): RegisteredAgent {
+    if (this.agents.has(id)) throw new Error(`Agent "${id}" is already registered`);
+    const agent: RegisteredAgent = {
+      id,
+      executor,
+      workspaceManager,
+      assignedTaskIds,
+      heartbeat: {
+        agent_id: id,
+        last_seen: new Date().toISOString(),
+        current_task: null,
+        status: 'idle',
+      },
+      role,
+      actionLog: [],
+    };
+    this.agents.set(id, agent);
+    return agent;
+  }
+
+  unregister(id: string): void {
+    this.agents.delete(id);
+  }
+
+  beat(id: string, currentTask: string | null = null): void {
+    const agent = this.agents.get(id);
+    if (!agent) return;
+    agent.heartbeat.last_seen = new Date().toISOString();
+    agent.heartbeat.current_task = currentTask;
+    agent.heartbeat.status = currentTask ? 'running' : 'idle';
+  }
+
+  setStatus(id: string, status: AgentStatus): void {
+    const agent = this.agents.get(id);
+    if (agent) agent.heartbeat.status = status;
+  }
+
+  isAlive(id: string): boolean {
+    const agent = this.agents.get(id);
+    if (!agent) return false;
+    const elapsed = Date.now() - new Date(agent.heartbeat.last_seen).getTime();
+    return elapsed < this.heartbeatTimeoutMs;
+  }
+
+  /** Returns agents that haven't sent a heartbeat within the timeout window */
+  timedOut(): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => !this.isAlive(a.id));
+  }
+
+  liveAgents(): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => this.isAlive(a.id));
+  }
+
+  get(id: string): RegisteredAgent | null {
+    return this.agents.get(id) ?? null;
+  }
+
+  list(): RegisteredAgent[] {
+    return [...this.agents.values()];
+  }
+
+  /**
+   * Reassign orphaned tasks from timed-out agents to a fallback agent.
+   * Returns the list of task IDs that were reassigned.
+   */
+  failover(fallbackAgentId: string): string[] {
+    const fallback = this.agents.get(fallbackAgentId);
+    if (!fallback) throw new Error(`Fallback agent "${fallbackAgentId}" not found`);
+
+    const orphaned: string[] = [];
+    for (const agent of this.timedOut()) {
+      orphaned.push(...agent.assignedTaskIds);
+      agent.assignedTaskIds = [];
+      agent.heartbeat.status = 'failed';
+    }
+
+    fallback.assignedTaskIds = [...fallback.assignedTaskIds, ...orphaned];
+    return orphaned;
+  }
+
+  /** Return all agents assigned to a given role */
+  getByRole(role: AgentRole): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => a.role === role);
+  }
+
+  /** Append an action log entry for a registered agent (no-op if unknown) */
+  logAction(agentId: string, log: AgentActionLog): void {
+    const agent = this.agents.get(agentId);
+    if (agent) agent.actionLog.push(log);
+  }
+
+  clear(): void {
+    this.agents.clear();
+  }
+}