agentic-orchestrator 0.1.26 → 0.1.28

package/apps/control-plane/src/core/tool-caller.ts

@@ -26,6 +26,16 @@ export interface ToolCaller {
 export interface FeatureStateFrontMatter {
   version: number;
   status: string;
+  execution_mode?: 'deterministic' | 'interactive';
+  checkpoints?: Array<{
+    checkpoint_id: string;
+    timestamp: string;
+    files_changed: string[];
+    validation_status: 'valid' | 'invalid' | 'skipped';
+    violations?: string[];
+    severity?: 'info' | 'warning' | 'error' | 'critical';
+    diff_snapshot?: string;
+  }>;
   cluster?: Record<string, string>;
   gate_retry_count?: number;
   last_retry_at?: string | null;

package/apps/control-plane/src/core/utils/field-readers.ts

@@ -0,0 +1,38 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+export function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
+export function readStringField(record: AnyRecord, key: string): string | null {
+  const value = record[key];
+  return typeof value === 'string' ? value : null;
+}
+
+export function readNumberField(record: AnyRecord, key: string): number | null {
+  const value = record[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function readPositiveIntegerField(record: AnyRecord, key: string): number | null {
+  const value = record[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+    return null;
+  }
+  return Math.floor(value);
+}
+
+export function readBooleanField(record: AnyRecord, key: string): boolean | null {
+  const value = record[key];
+  return typeof value === 'boolean' ? value : null;
+}
+
+export function readObjectField(record: AnyRecord, key: string): AnyRecord {
+  const value = record[key];
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+export function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}

package/apps/control-plane/src/core/utils/index-normalizer.ts

@@ -0,0 +1,119 @@
+import { stableHash, nowIso } from '../fs.js';
+import type { RuntimeSessionsSnapshot } from '../runtime-sessions.js';
+import { asArray, normalizeSet } from './field-readers.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+export function emptyRuntimeSessions(at = nowIso()): RuntimeSessionsSnapshot {
+  return {
+    run_id: 'none',
+    orchestrator_session_id: 'unknown',
+    provider: 'unknown',
+    model: 'unknown',
+    provider_config_ref_hash: stableHash('none'),
+    owner_instance_id: 'none',
+    lease_id: 'none',
+    started_at: at,
+    last_heartbeat_at: at,
+    lease_expires_at: at,
+    orchestrator_epoch: 0,
+    feature_sessions: {},
+  };
+}
+
+export function normalizeRuntimeSessions(value: unknown, at = nowIso()): RuntimeSessionsSnapshot {
+  const fallback = emptyRuntimeSessions(at);
+  const source = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+  const featureSessionsInput =
+    source.feature_sessions && typeof source.feature_sessions === 'object'
+      ? (source.feature_sessions as Record<string, unknown>)
+      : {};
+  const featureSessions: RuntimeSessionsSnapshot['feature_sessions'] = {};
+
+  for (const [featureId, raw] of Object.entries(featureSessionsInput)) {
+    if (!featureId || typeof raw !== 'object' || !raw) {
+      continue;
+    }
+    const typed = raw as Record<string, unknown>;
+    featureSessions[featureId] = {
+      planner_session_id:
+        typeof typed.planner_session_id === 'string' ? typed.planner_session_id : 'unassigned',
+      builder_session_id:
+        typeof typed.builder_session_id === 'string' ? typed.builder_session_id : 'unassigned',
+      qa_session_id: typeof typed.qa_session_id === 'string' ? typed.qa_session_id : 'unassigned',
+    };
+  }
+
+  const epoch =
+    typeof source.orchestrator_epoch === 'number' && Number.isFinite(source.orchestrator_epoch)
+      ? Math.max(0, Math.floor(source.orchestrator_epoch))
+      : 0;
+
+  return {
+    run_id: typeof source.run_id === 'string' && source.run_id ? source.run_id : fallback.run_id,
+    orchestrator_session_id:
+      typeof source.orchestrator_session_id === 'string' && source.orchestrator_session_id
+        ? source.orchestrator_session_id
+        : fallback.orchestrator_session_id,
+    provider:
+      typeof source.provider === 'string' && source.provider ? source.provider : fallback.provider,
+    model: typeof source.model === 'string' && source.model ? source.model : fallback.model,
+    provider_config_ref_hash:
+      typeof source.provider_config_ref_hash === 'string' && source.provider_config_ref_hash
+        ? source.provider_config_ref_hash
+        : fallback.provider_config_ref_hash,
+    owner_instance_id:
+      typeof source.owner_instance_id === 'string' && source.owner_instance_id
+        ? source.owner_instance_id
+        : fallback.owner_instance_id,
+    lease_id:
+      typeof source.lease_id === 'string' && source.lease_id ? source.lease_id : fallback.lease_id,
+    started_at:
+      typeof source.started_at === 'string' && source.started_at
+        ? source.started_at
+        : fallback.started_at,
+    last_heartbeat_at:
+      typeof source.last_heartbeat_at === 'string' && source.last_heartbeat_at
+        ? source.last_heartbeat_at
+        : fallback.last_heartbeat_at,
+    lease_expires_at:
+      typeof source.lease_expires_at === 'string' && source.lease_expires_at
+        ? source.lease_expires_at
+        : fallback.lease_expires_at,
+    orchestrator_epoch: epoch,
+    feature_sessions: featureSessions,
+  };
+}
+
+export function normalizeIndexShape(value: unknown): AnyRecord {
+  const now = nowIso();
+  const source = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+  return {
+    version:
+      typeof source.version === 'number' && Number.isFinite(source.version)
+        ? Math.max(1, Math.floor(source.version))
+        : 1,
+    active: normalizeSet(asArray<string>(source.active).filter((item) => typeof item === 'string')),
+    blocked: normalizeSet(
+      asArray<string>(source.blocked).filter((item) => typeof item === 'string'),
+    ),
+    merged: normalizeSet(asArray<string>(source.merged).filter((item) => typeof item === 'string')),
+    locks: source.locks && typeof source.locks === 'object' ? source.locks : {},
+    lock_leases:
+      source.lock_leases && typeof source.lock_leases === 'object' ? source.lock_leases : {},
+    blocked_queue: asArray(source.blocked_queue).filter((item) => item && typeof item === 'object'),
+    dep_blocked: asArray(source.dep_blocked).filter((item) => item && typeof item === 'object'),
+    updated_at:
+      typeof source.updated_at === 'string' && source.updated_at ? source.updated_at : now,
+    runtime_sessions: normalizeRuntimeSessions(source.runtime_sessions, now),
+  };
+}
+
+export function isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean {
+  const expiry = new Date(runtimeSessions.lease_expires_at).getTime();
+  if (!Number.isFinite(expiry)) {
+    return false;
+  }
+  return expiry > Date.now();
+}

package/apps/control-plane/src/core/utils/path-normalizers.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+
+export function normalizeRepoPathForState(repoRoot: string, absolutePath: string): string {
+  const relative = path.relative(repoRoot, absolutePath).replaceAll('\\\\', '/');
+  if (!relative || relative === '.') {
+    return '.';
+  }
+  return relative;
+}
+
+export function normalizeFromWorktree(
+  worktreePath: string,
+  repoRoot: string,
+  repoRelativeFromWorktree: string,
+): string {
+  const absolute = path.resolve(repoRoot, repoRelativeFromWorktree);
+  const maybeRelativeToWorktree = path.relative(worktreePath, absolute).replaceAll('\\\\', '/');
+  if (!maybeRelativeToWorktree.startsWith('../')) {
+    return maybeRelativeToWorktree;
+  }
+  return path.relative(repoRoot, absolute).replaceAll('\\\\', '/');
+}

package/apps/control-plane/src/interfaces/cli/bootstrap.ts

@@ -17,6 +17,7 @@ import { ResumeCommandHandler } from '../../cli/resume-command-handler.js';
 import { StopCommandHandler } from '../../cli/stop-command-handler.js';
 import { DeleteCommandHandler } from '../../cli/delete-command-handler.js';
 import { CleanupCommandHandler } from '../../cli/cleanup-command-handler.js';
+import { RollbackCommandHandler } from '../../cli/rollback-command-handler.js';
 import { RunCommandHandler } from '../../cli/run-command-handler.js';
 import { InitCommandHandler } from '../../cli/init-command-handler.js';
 import { DashboardCommandHandler } from '../../cli/dashboard-command-handler.js';
@@ -30,6 +31,7 @@ import { resolveProviderSelection } from '../../providers/providers.js';
 import {
   DefaultWorkerProviderFactory,
   resolveWorkerProviderMode,
+  resolveWorkerProviderObservability,
   resolveWorkerProviderPolicy,
   resolveWorkerProviderRuntime,
 } from '../../providers/worker-provider-factory.js';
@@ -355,6 +357,10 @@ export async function runCli(
         policySnapshot.execution && typeof policySnapshot.execution === 'object'
           ? (policySnapshot.execution as Record<string, unknown>)
           : null;
+      const observabilityPolicy =
+        policySnapshot.observability && typeof policySnapshot.observability === 'object'
+          ? (policySnapshot.observability as Record<string, unknown>)
+          : null;
       commandProvider = workerProviderFactory.create({
         selection,
         mode: resolveWorkerProviderMode(
@@ -364,7 +370,9 @@ export async function runCli(
         ),
         context: options.command === CliCommand.Send ? 'send' : 'attach',
         policy: resolveWorkerProviderPolicy(executionPolicy),
+        observability: resolveWorkerProviderObservability(observabilityPolicy),
         runtime: resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime),
+        repoRoot,
       });
       kernel.setProvider(commandProvider);
     }
@@ -416,6 +424,13 @@ export async function runCli(
       return 0;
     }
 
+    if (options.command === CliCommand.Rollback) {
+      const handler = new RollbackCommandHandler(repoRoot);
+      const payload = await handler.execute(options);
+      printPayload(payload);
+      return 0;
+    }
+
     if (options.command === CliCommand.Retry) {
       const handler = new RetryCommandHandler(toolClient, runId);
       const payload = await handler.execute(options);

package/apps/control-plane/src/providers/api-worker-provider.ts

@@ -5,7 +5,9 @@ import type {
   ProviderSelection,
   WorkerCapabilities,
   WorkerHandle,
+  WorkerProviderCapabilities,
   WorkerProvider,
+  WorkerRunInput,
   WorkerSession,
 } from './providers.js';
 import type { ProviderOutputParser } from './output-parsers/types.js';
@@ -52,6 +54,13 @@ export class ApiWorkerProvider implements WorkerProvider {
     supportsIdleDetection: false,
     supportsSpawnDetection: false,
   };
+  private readonly providerCapabilities: WorkerProviderCapabilities = {
+    supportsInteractiveMode: false,
+    supportsWorkingDirectory: false,
+    supportsPauseResume: false,
+    supportsMessagePassing: false,
+    supportsAcknowledgment: false,
+  };
 
   constructor(selection: ProviderSelection, options: ApiWorkerProviderOptions) {
     this.selection = selection;
@@ -95,18 +104,7 @@ export class ApiWorkerProvider implements WorkerProvider {
     return Promise.resolve({ closed: true });
   }
 
-  runWorker(input: {
-    role: string;
-    feature_id: string;
-    context_bundle?: Record<string, unknown>;
-    instructions?: string;
-    last_tool_results?: Array<Record<string, unknown>>;
-    runtime_selection?: {
-      provider: string;
-      model: string;
-      provider_config_ref: string | null;
-    };
-  }): Promise<Record<string, unknown>> {
+  runWorker(input: WorkerRunInput): Promise<Record<string, unknown>> {
     const workerHandle: WorkerHandle = {
       capabilities: this.workerCapabilities,
       kill: () => {
@@ -169,4 +167,8 @@ export class ApiWorkerProvider implements WorkerProvider {
       });
     }
   }
+
+  getCapabilities(): WorkerProviderCapabilities {
+    return this.providerCapabilities;
+  }
 }

package/apps/control-plane/src/providers/cli-worker-provider.ts

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { ERROR_CODES } from '../core/error-codes.js';
 import {
   NodeProviderCommandRunner,
@@ -6,6 +8,8 @@ import {
   type ProviderCommandResult,
   type ProviderCommandRunner,
   type ProviderSelection,
+  type WorkerProviderCapabilities,
+  type WorkerRunInput,
   type WorkerCapabilities,
   type WorkerHandle,
   type WorkerProvider,
@@ -18,6 +22,9 @@ import { WorkerWatchdog, type WatchdogOutcome } from './worker-watchdog.js';
 interface CliWorkerProviderOptions {
   outputParser: ProviderOutputParser;
   commandRunner?: ProviderCommandRunner;
+  repoRoot?: string;
+  rawAgentLogsEnabled?: boolean;
+  rawAgentLogsRetentionDays?: number;
   workerResponseTimeoutMs: number;
   workerSpawnTimeoutMs?: number;
   workerIdleTimeoutMs?: number;
@@ -39,6 +46,14 @@ const DEFAULT_SPAWN_TIMEOUT_MS = 15_000;
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 const DEFAULT_WATCHDOG_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_KILL_GRACE_PERIOD_MS = 1_500;
+const DEFAULT_RAW_LOG_RETENTION_DAYS = 60;
+const CLI_PROVIDER_CAPABILITIES: WorkerProviderCapabilities = {
+  supportsInteractiveMode: true,
+  supportsWorkingDirectory: true,
+  supportsPauseResume: false,
+  supportsMessagePassing: true,
+  supportsAcknowledgment: false,
+};
 
 function buildStructuredWorkerPrompt(
   payload: Record<string, unknown>,
@@ -201,6 +216,9 @@ export class CliWorkerProvider implements WorkerProvider {
   private readonly workerIdleTimeoutMs: number;
   private readonly workerWatchdogPollIntervalMs: number;
   private readonly workerKillGracePeriodMs: number;
+  private readonly repoRoot: string | null;
+  private readonly rawAgentLogsEnabled: boolean;
+  private readonly rawAgentLogsRetentionDays: number;
   private readonly workerCapabilities: WorkerCapabilities;
   private readonly runTemplate: ProviderCommandTemplate | undefined;
   private readonly attachTemplate: ProviderCommandTemplate | undefined;
@@ -229,6 +247,13 @@ export class CliWorkerProvider implements WorkerProvider {
       options.workerKillGracePeriodMs,
       DEFAULT_KILL_GRACE_PERIOD_MS,
     );
+    this.repoRoot =
+      typeof options.repoRoot === 'string' && options.repoRoot.length > 0 ? options.repoRoot : null;
+    this.rawAgentLogsEnabled = options.rawAgentLogsEnabled === true;
+    this.rawAgentLogsRetentionDays = asPositiveInteger(
+      options.rawAgentLogsRetentionDays,
+      DEFAULT_RAW_LOG_RETENTION_DAYS,
+    );
     this.workerCapabilities = resolveCliWorkerCapabilities(selection);
     this.runTemplate = resolveRunTemplate(selection);
     this.attachTemplate = resolveAttachTemplate(selection);
@@ -290,18 +315,7 @@ export class CliWorkerProvider implements WorkerProvider {
     return Promise.resolve({ closed: true });
   }
 
-  async runWorker(input: {
-    role: string;
-    feature_id: string;
-    context_bundle?: Record<string, unknown>;
-    instructions?: string;
-    last_tool_results?: Array<Record<string, unknown>>;
-    runtime_selection?: {
-      provider: string;
-      model: string;
-      provider_config_ref: string | null;
-    };
-  }): Promise<Record<string, unknown>> {
+  async runWorker(input: WorkerRunInput): Promise<Record<string, unknown>> {
     if (!this.runTemplate) {
       throw providerError(
         ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
@@ -364,6 +378,7 @@ export class CliWorkerProvider implements WorkerProvider {
     try {
       runResult = await this.commandRunner.run(this.runTemplate.command, args, {
         stdin: prompt,
+        cwd: input.working_directory,
         timeoutMs: runnerBackstopTimeoutMs,
         env: buildRunCommandEnv(this.selection),
         onLifecycleEvent: (event) => {
@@ -391,6 +406,7 @@ export class CliWorkerProvider implements WorkerProvider {
       effectiveTimeoutMs,
       watchdogOutcome,
     );
+    await this.persistRawAgentOutput(input.feature_id, input.role, runResult.stdout ?? '');
 
     return this.outputParser.parse(runResult.stdout ?? '', {
       sessionId,
@@ -401,6 +417,10 @@ export class CliWorkerProvider implements WorkerProvider {
     });
   }
 
+  getCapabilities(): WorkerProviderCapabilities {
+    return CLI_PROVIDER_CAPABILITIES;
+  }
+
   private sessionKey(role: string, featureId: string): string {
     return `${role}::${featureId}`;
   }
@@ -520,4 +540,54 @@ export class CliWorkerProvider implements WorkerProvider {
       },
     );
   }
+
+  private async persistRawAgentOutput(
+    featureId: string,
+    role: string,
+    stdout: string,
+  ): Promise<void> {
+    if (!this.rawAgentLogsEnabled || !this.repoRoot) {
+      return;
+    }
+    if (stdout.trim().length === 0) {
+      return;
+    }
+    if (role !== 'planner' && role !== 'builder' && role !== 'qa') {
+      return;
+    }
+
+    const logsDir = path.join(this.repoRoot, '.aop', 'features', featureId, 'logs');
+    const filename = `${role}-${Date.now()}.txt`;
+    const filePath = path.join(logsDir, filename);
+
+    try {
+      await fs.mkdir(logsDir, { recursive: true });
+      await fs.writeFile(filePath, stdout, 'utf8');
+      await this.cleanupExpiredRawAgentLogs(logsDir);
+    } catch {
+      // Raw log persistence must not fail orchestration flow.
+    }
+  }
+
+  private async cleanupExpiredRawAgentLogs(logsDir: string): Promise<void> {
+    const cutoffMs = Date.now() - this.rawAgentLogsRetentionDays * 24 * 60 * 60 * 1000;
+    try {
+      const files = await fs.readdir(logsDir);
+      await Promise.all(
+        files.map(async (filename) => {
+          const match = filename.match(/^(planner|builder|qa)-([0-9]{13})\.txt$/);
+          if (!match) {
+            return;
+          }
+          const unixMs = Number.parseInt(match[2], 10);
+          if (Number.isNaN(unixMs) || unixMs >= cutoffMs) {
+            return;
+          }
+          await fs.unlink(path.join(logsDir, filename)).catch(() => undefined);
+        }),
+      );
+    } catch {
+      // Best effort cleanup.
+    }
+  }
 }

package/apps/control-plane/src/providers/providers.ts

@@ -225,6 +225,32 @@ export interface WorkerSession {
   system_prompt_loaded: boolean;
 }
 
+export type ExecutionMode = 'deterministic' | 'interactive';
+
+export interface WorkerProviderCapabilities {
+  supportsInteractiveMode: boolean;
+  supportsWorkingDirectory: boolean;
+  supportsPauseResume: boolean;
+  supportsMessagePassing: boolean;
+  supportsAcknowledgment: boolean;
+}
+
+export interface WorkerRunInput {
+  role: string;
+  feature_id: string;
+  context_bundle?: Record<string, unknown>;
+  instructions?: string;
+  last_tool_results?: Array<Record<string, unknown>>;
+  runtime_selection?: {
+    provider: string;
+    model: string;
+    provider_config_ref: string | null;
+  };
+  execution_mode?: ExecutionMode;
+  working_directory?: string;
+  pause_resume_protocol?: 'signal' | 'message' | 'none';
+}
+
 /**
  * Worker provider interface for agent session management.
  *
@@ -293,18 +319,7 @@ export interface WorkerProvider {
    * @param input - execution input with role, feature, context, instructions
    * @returns Worker output with tool calls and text
    */
-  runWorker(input: {
-    role: string;
-    feature_id: string;
-    context_bundle?: Record<string, unknown>;
-    instructions?: string;
-    last_tool_results?: Array<Record<string, unknown>>;
-    runtime_selection?: {
-      provider: string;
-      model: string;
-      provider_config_ref: string | null;
-    };
-  }): Promise<Record<string, unknown>>;
+  runWorker(input: WorkerRunInput): Promise<Record<string, unknown>>;
 
   /**
    * Sends a message to an active session (optional).
@@ -328,6 +343,11 @@ export interface WorkerProvider {
    * @returns Session status
    */
   getSessionInfo?(sessionId: string): Promise<{ active: boolean; provider: string }>;
+
+  /**
+   * Reports provider runtime capabilities (optional).
+   */
+  getCapabilities?(): WorkerProviderCapabilities;
 }
 
 /**
@@ -367,6 +387,7 @@ export interface ProviderCommandRunnerOptions {
   interactive?: boolean;
   stdin?: string;
   env?: NodeJS.ProcessEnv;
+  cwd?: string;
   timeoutMs?: number;
   onLifecycleEvent?: (event: WorkerLifecycleEvent) => void;
   registerKill?: (kill: (signal: 'SIGTERM' | 'SIGKILL') => void) => void;
@@ -391,6 +412,7 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
       try {
         child = spawn(command, args, {
           env: options.env,
+          cwd: options.cwd,
           stdio: options.interactive ? 'inherit' : ['pipe', 'pipe', 'pipe'],
         });
       } catch {
@@ -638,18 +660,7 @@ export class NullWorkerProvider implements WorkerProvider {
     role,
     feature_id,
     context_bundle,
-  }: {
-    role: string;
-    feature_id: string;
-    context_bundle?: Record<string, unknown>;
-    instructions?: string;
-    last_tool_results?: Array<Record<string, unknown>>;
-    runtime_selection?: {
-      provider: string;
-      model: string;
-      provider_config_ref: string | null;
-    };
-  }): Promise<Record<string, unknown>> {
+  }: WorkerRunInput): Promise<Record<string, unknown>> {
     if (role === 'planner') {
       const state = context_bundle?.state;
       const frontMatter =
@@ -715,4 +726,14 @@ export class NullWorkerProvider implements WorkerProvider {
     }
     throw commandFailureError(this.selection.provider, kind, details, ERROR_CODES.INTERNAL_ERROR);
   }
+
+  getCapabilities(): WorkerProviderCapabilities {
+    return {
+      supportsInteractiveMode: false,
+      supportsWorkingDirectory: false,
+      supportsPauseResume: false,
+      supportsMessagePassing: Boolean(this.sendMessage),
+      supportsAcknowledgment: false,
+    };
+  }
 }

package/apps/control-plane/src/providers/worker-provider-factory.ts

@@ -31,6 +31,11 @@ export interface WorkerProviderFactoryPolicy {
   require_live_provider_for_run: boolean;
 }
 
+export interface WorkerProviderFactoryObservability {
+  raw_agent_logs_enabled: boolean;
+  raw_agent_logs_retention_days: number;
+}
+
 export interface WorkerProviderFactoryRuntime {
   worker_response_timeout_ms: number;
   worker_spawn_timeout_ms: number;
@@ -49,7 +54,9 @@ export interface CreateWorkerProviderInput {
   mode: WorkerProviderMode;
   context: ProviderCommandContext;
   policy: WorkerProviderFactoryPolicy;
+  observability?: WorkerProviderFactoryObservability;
   runtime: WorkerProviderFactoryRuntime;
+  repoRoot?: string;
   commandRunner?: ProviderCommandRunner;
 }
 
@@ -81,6 +88,11 @@ interface PolicyConfigInput {
   no_progress_action?: unknown;
 }
 
+interface ObservabilityConfigInput {
+  raw_agent_logs_enabled?: unknown;
+  raw_agent_logs_retention_days?: unknown;
+}
+
 function asPositiveInteger(value: unknown, fallback: number): number {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
     return fallback;
@@ -175,6 +187,15 @@ export function resolveWorkerProviderPolicy(
   };
 }
 
+export function resolveWorkerProviderObservability(
+  input: ObservabilityConfigInput | null | undefined,
+): WorkerProviderFactoryObservability {
+  return {
+    raw_agent_logs_enabled: input?.raw_agent_logs_enabled === true,
+    raw_agent_logs_retention_days: asPositiveInteger(input?.raw_agent_logs_retention_days, 60),
+  };
+}
+
 export function resolveMalformedWorkerOutputAction(
   input: PolicyConfigInput | null | undefined,
 ): WorkerMalformedOutputAction {
@@ -219,7 +240,12 @@ export function resolvePlanConformanceStallAction(
 
 export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
   create(input: CreateWorkerProviderInput): WorkerProvider {
-    const { selection, mode, context, policy, runtime, commandRunner } = input;
+    const { selection, mode, context, policy, runtime, observability, repoRoot, commandRunner } =
+      input;
+    const resolvedObservability = observability ?? {
+      raw_agent_logs_enabled: false,
+      raw_agent_logs_retention_days: 60,
+    };
 
     if (!SUPPORTED_PROVIDERS.has(selection.provider)) {
       throw toAppError(ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER, 'Unsupported worker provider', {
@@ -259,6 +285,9 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
       return new CliWorkerProvider(selection, {
         outputParser: new CodexOutputParser(),
         commandRunner,
+        repoRoot,
+        rawAgentLogsEnabled: resolvedObservability.raw_agent_logs_enabled,
+        rawAgentLogsRetentionDays: resolvedObservability.raw_agent_logs_retention_days,
         workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
         workerSpawnTimeoutMs: runtime.worker_spawn_timeout_ms,
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,
@@ -271,6 +300,9 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
       return new CliWorkerProvider(selection, {
         outputParser: new ClaudeOutputParser(),
         commandRunner,
+        repoRoot,
+        rawAgentLogsEnabled: resolvedObservability.raw_agent_logs_enabled,
+        rawAgentLogsRetentionDays: resolvedObservability.raw_agent_logs_retention_days,
         workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
         workerSpawnTimeoutMs: runtime.worker_spawn_timeout_ms,
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,
@@ -287,6 +319,9 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
       return new CliWorkerProvider(selection, {
         outputParser: new GenericCliOutputParser(),
         commandRunner,
+        repoRoot,
+        rawAgentLogsEnabled: resolvedObservability.raw_agent_logs_enabled,
+        rawAgentLogsRetentionDays: resolvedObservability.raw_agent_logs_retention_days,
         workerResponseTimeoutMs: runtime.worker_response_timeout_ms,
         workerSpawnTimeoutMs: runtime.worker_spawn_timeout_ms,
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,