agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/application/services/run-lease-service.ts

@@ -22,6 +22,18 @@ interface RuntimeFeatureSessionUpdateParams {
   qa_session_id: string;
 }
 
+interface RuntimeReconcilerSessionUpdateParams {
+  run_id: string;
+  owner_instance_id: string;
+  reconciler_session_id: string;
+}
+
+interface RuntimeOrganizerSessionUpdateParams {
+  run_id: string;
+  owner_instance_id: string;
+  organizer_session_id: string;
+}
+
 interface PruneFeatureSessionParams {
   run_id: string;
   owner_instance_id: string;
@@ -135,8 +147,8 @@ export class RunLeaseService {
       const current = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
       const hasLease = current.run_id !== 'none' && current.owner_instance_id !== 'none';
       const fresh = hasLease && this.port.isRunLeaseFresh(current);
-      const sameOwner =
-        current.run_id === input.run_id && current.owner_instance_id === input.owner_instance_id;
+      const sameOwnerInstance = current.owner_instance_id === input.owner_instance_id;
+      const sameOwner = current.run_id === input.run_id && sameOwnerInstance;
 
       if (fresh && !sameOwner) {
         throw {
@@ -155,7 +167,7 @@ export class RunLeaseService {
         };
       }
 
-      const staleOwnedByOther = hasLease && !fresh && !sameOwner;
+      const staleOwnedByOther = hasLease && !fresh && !sameOwnerInstance;
       if (staleOwnedByOther && !input.takeover_stale_run) {
         throw {
           normalizedResponse: fail(
@@ -191,7 +203,14 @@ export class RunLeaseService {
       };
 
       if (!sameOwner) {
-        claimed.orchestrator_session_id = 'unknown';
+        if (!staleOwnedByOther) {
+          // Fresh start with no prior lease — reset orchestrator session
+          claimed.orchestrator_session_id = 'unknown';
+          claimed.reconciler_session_id = 'unknown';
+        }
+        claimed.reconciler_active_feature_id = null;
+        claimed.reconciler_queue = [];
+        // Always reset feature sessions for a new owner
         claimed.feature_sessions = {};
       }
 
@@ -293,7 +312,8 @@ export class RunLeaseService {
         return { data: { released: false } };
       }
 
-      await this.port.writeRunLease(this.port.emptyRuntimeSessions(nowIso()));
+      // Mark as expired (keep session IDs for stale-takeover/audit) rather than clearing to empty
+      await this.port.writeRunLease({ ...current, lease_expires_at: new Date(0).toISOString() });
       return { data: { released: true } };
     });
   }
@@ -403,6 +423,102 @@ export class RunLeaseService {
     });
   }
 
+  async updateReconcilerSession(
+    params: RuntimeReconcilerSessionUpdateParams,
+  ): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }> {
+    const { run_id, owner_instance_id, reconciler_session_id } = params;
+    if (!run_id || !owner_instance_id || !reconciler_session_id) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'run_id, owner_instance_id, and reconciler_session_id are required',
+          {
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return await this.port.withIndexLock(async () => {
+      const current = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
+      if (current.run_id !== run_id || current.owner_instance_id !== owner_instance_id) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.RUN_LEASE_NOT_OWNED,
+            'Cannot update reconciler session without run ownership',
+            {
+              run_id,
+              owner_instance_id,
+              active_run_id: current.run_id,
+              active_owner_instance_id: current.owner_instance_id,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const updated: RuntimeSessionsSnapshot = {
+        ...current,
+        reconciler_session_id,
+      };
+      await this.port.writeRunLease(updated);
+
+      return {
+        data: {
+          runtime_sessions: updated,
+        },
+      };
+    });
+  }
+
+  async updateOrganizerSession(
+    params: RuntimeOrganizerSessionUpdateParams,
+  ): Promise<{ data: { runtime_sessions: RuntimeSessionsSnapshot } }> {
+    const { run_id, owner_instance_id, organizer_session_id } = params;
+    if (!run_id || !owner_instance_id || !organizer_session_id) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'run_id, owner_instance_id, and organizer_session_id are required',
+          {
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return await this.port.withIndexLock(async () => {
+      const current = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
+      if (current.run_id !== run_id || current.owner_instance_id !== owner_instance_id) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.RUN_LEASE_NOT_OWNED,
+            'Cannot update organizer session without run ownership',
+            {
+              run_id,
+              owner_instance_id,
+              active_run_id: current.run_id,
+              active_owner_instance_id: current.owner_instance_id,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const updated: RuntimeSessionsSnapshot = {
+        ...current,
+        organizer_session_id,
+      };
+
+      await this.port.writeRunLease(updated);
+      return { data: { runtime_sessions: updated } };
+    });
+  }
+
   async pruneFeatureSessionAssignments(
     params: PruneFeatureSessionParams,
   ): Promise<{ data: { removed: string[] } }> {

package/apps/control-plane/src/application/services/worktree-watchdog-service.ts

@@ -1,5 +1,10 @@
 import { EventEmitter } from 'node:events';
 import { runGit } from '../../core/git.js';
+import {
+  EMPTY_DIFF_HASH,
+  hashWorktreeDiff,
+  readMaterializedWorktreeDiff,
+} from '../../core/worktree-diff.js';
 
 interface WatchStartInput {
   featureId: string;
@@ -14,12 +19,25 @@ interface WatcherState {
   worktreePath: string;
   maxUncommittedChanges: number;
   timer: NodeJS.Timeout;
+  baselineFiles: Set<string>;
   changedFiles: Set<string>;
+  currentFiles: Set<string>;
+  baselineDiffHash: string;
+  currentDiffHash: string;
   thresholdEmitted: boolean;
   pollInFlight: boolean;
   stopped: boolean;
 }
 
+export interface WorktreeChangeSummary {
+  baselineFiles: string[];
+  currentFiles: string[];
+  changedFiles: string[];
+  baselineDiffHash: string;
+  currentDiffHash: string;
+  hasNetNewChanges: boolean;
+}
+
 function parseStatusPaths(statusPorcelain: string): string[] {
   const files: string[] = [];
   const lines = statusPorcelain
@@ -43,6 +61,12 @@ function parseStatusPaths(statusPorcelain: string): string[] {
   return [...new Set(files)].sort((a, b) => a.localeCompare(b));
 }
 
+function computeDeltaFiles(baselineFiles: Set<string>, currentFiles: Set<string>): string[] {
+  return [...currentFiles]
+    .filter((file) => !baselineFiles.has(file))
+    .sort((a, b) => a.localeCompare(b));
+}
+
 /**
  * Polling watchdog that tracks feature-worktree changes and emits threshold events.
  */
@@ -61,6 +85,7 @@ export class WorktreeWatchdogService extends EventEmitter {
         ? Math.floor(input.maxUncommittedChanges)
         : 50;
 
+    const baselineSnapshot = await this.captureSnapshot(input.repoRoot, input.worktreePath);
     const state: WatcherState = {
       repoRoot: input.repoRoot,
       worktreePath: input.worktreePath,
@@ -68,7 +93,11 @@ export class WorktreeWatchdogService extends EventEmitter {
       timer: setInterval(() => {
         void this.pollFeature(input.featureId);
       }, intervalMs),
+      baselineFiles: new Set(baselineSnapshot.files),
       changedFiles: new Set<string>(),
+      currentFiles: new Set(baselineSnapshot.files),
+      baselineDiffHash: baselineSnapshot.diffHash,
+      currentDiffHash: baselineSnapshot.diffHash,
       thresholdEmitted: false,
       pollInFlight: false,
       stopped: false,
@@ -91,12 +120,42 @@ export class WorktreeWatchdogService extends EventEmitter {
   }
 
   async getChangedFiles(featureId: string): Promise<string[]> {
+    const summary = await this.getChangeSummary(featureId);
+    return summary.changedFiles;
+  }
+
+  async getChangeSummary(featureId: string): Promise<WorktreeChangeSummary> {
     await this.pollFeature(featureId);
     const state = this.watchers.get(featureId);
     if (!state) {
-      return [];
+      return {
+        baselineFiles: [],
+        currentFiles: [],
+        changedFiles: [],
+        baselineDiffHash: EMPTY_DIFF_HASH,
+        currentDiffHash: EMPTY_DIFF_HASH,
+        hasNetNewChanges: false,
+      };
     }
-    return [...state.changedFiles].sort((a, b) => a.localeCompare(b));
+
+    const snapshot = await this.captureSnapshot(state.repoRoot, state.worktreePath);
+    state.currentFiles = new Set(snapshot.files);
+    state.currentDiffHash = snapshot.diffHash;
+
+    const hasNetNewChanges = state.currentDiffHash !== state.baselineDiffHash;
+    const changedFiles =
+      hasNetNewChanges && state.changedFiles.size === 0 && state.currentFiles.size > 0
+        ? [...state.currentFiles].sort((a, b) => a.localeCompare(b))
+        : [...state.changedFiles].sort((a, b) => a.localeCompare(b));
+
+    return {
+      baselineFiles: [...state.baselineFiles].sort((a, b) => a.localeCompare(b)),
+      currentFiles: [...state.currentFiles].sort((a, b) => a.localeCompare(b)),
+      changedFiles,
+      baselineDiffHash: state.baselineDiffHash,
+      currentDiffHash: state.currentDiffHash,
+      hasNetNewChanges,
+    };
   }
 
   getChangeCount(featureId: string): number {
@@ -112,6 +171,8 @@ export class WorktreeWatchdogService extends EventEmitter {
     if (!state) {
       return;
     }
+    state.baselineFiles = new Set(state.currentFiles);
+    state.baselineDiffHash = state.currentDiffHash;
     state.changedFiles.clear();
     state.thresholdEmitted = false;
   }
@@ -132,15 +193,13 @@ export class WorktreeWatchdogService extends EventEmitter {
 
     state.pollInFlight = true;
     try {
-      const status = await runGit(state.repoRoot, ['status', '--porcelain'], {
-        cwd: state.worktreePath,
-      });
-      if (status.code !== 0) {
+      const snapshot = await this.captureSnapshot(state.repoRoot, state.worktreePath, false);
+      if (snapshot.failed) {
         return;
       }
 
-      const files = parseStatusPaths(status.stdout);
-      state.changedFiles = new Set(files);
+      state.currentFiles = new Set(snapshot.files);
+      state.changedFiles = new Set(computeDeltaFiles(state.baselineFiles, state.currentFiles));
 
       if (state.changedFiles.size >= state.maxUncommittedChanges && !state.thresholdEmitted) {
         state.thresholdEmitted = true;
@@ -153,4 +212,32 @@ export class WorktreeWatchdogService extends EventEmitter {
       state.pollInFlight = false;
     }
   }
+
+  private async captureSnapshot(
+    repoRoot: string,
+    worktreePath: string,
+    includeDiff = true,
+  ): Promise<{ files: string[]; diffHash: string; failed: boolean }> {
+    const status = await runGit(repoRoot, ['status', '--porcelain'], {
+      cwd: worktreePath,
+    });
+    if (status.code !== 0) {
+      return { files: [], diffHash: EMPTY_DIFF_HASH, failed: true };
+    }
+
+    if (!includeDiff) {
+      return {
+        files: parseStatusPaths(status.stdout),
+        diffHash: EMPTY_DIFF_HASH,
+        failed: false,
+      };
+    }
+
+    const diffText = await readMaterializedWorktreeDiff(repoRoot, worktreePath);
+    return {
+      files: parseStatusPaths(status.stdout),
+      diffHash: hashWorktreeDiff(diffText),
+      failed: false,
+    };
+  }
 }

package/apps/control-plane/src/application/tools/tool-metadata.ts

@@ -7,6 +7,7 @@ export interface ToolBehaviorMetadata {
 
 const MUTATING_TOOLS = [
   TOOLS.FEATURE_INIT,
+  TOOLS.FEATURE_INTAKE_SUBMIT,
   TOOLS.FEATURE_STATE_PATCH,
   TOOLS.FEATURE_LOG_APPEND,
   TOOLS.PLAN_SUBMIT,
@@ -19,9 +20,15 @@ const MUTATING_TOOLS = [
   TOOLS.LOCKS_RELEASE,
   TOOLS.FEATURE_READY_TO_MERGE,
   TOOLS.FEATURE_DELETE,
+  TOOLS.RUNTIME_EXECUTION_REQUEST_SUBMIT,
   TOOLS.FEATURE_SEND_MESSAGE,
+  TOOLS.FEATURE_QUESTION_CREATE,
+  TOOLS.FEATURE_QUESTION_ANSWER,
   TOOLS.COST_RECORD,
   TOOLS.PERFORMANCE_RECORD_OUTCOME,
+  TOOLS.REPO_RECONCILE_MAINLINE,
+  TOOLS.REPO_RESOLVE_CONFLICT,
+  TOOLS.REPO_CONFLICT_ABORT,
 ] as const;
 
 export const TOOL_BEHAVIOR_METADATA: Readonly<Record<string, ToolBehaviorMetadata>> = Object.freeze(

package/apps/control-plane/src/application/usage-types.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Token usage telemetry types for truthful per-role tracking.
+ *
+ * Three-state availability model:
+ * - reported: real token counts from API response
+ * - estimated: heuristic-derived counts (e.g. from output length)
+ * - unavailable: provider does not expose usage data
+ *
+ * Missing usage is NEVER recorded as zero.
+ */
+
+export type UsageAvailability = 'reported' | 'estimated' | 'unavailable';
+
+export interface NormalizedUsageRecord {
+  /** Three-state availability label */
+  status: UsageAvailability;
+  /** Input tokens consumed (null when unavailable) */
+  input_tokens: number | null;
+  /** Output tokens produced (null when unavailable) */
+  output_tokens: number | null;
+  /** Total tokens (input + output, null when unavailable) */
+  total_tokens: number | null;
+  /** Provider that produced this usage */
+  provider: string;
+  /** Model used */
+  model: string;
+  /** Agent role that consumed these tokens */
+  role: string;
+  /** Optional estimated cost in USD (derived, never primary) */
+  estimated_cost_usd: number | null;
+}
+
+export interface RoleUsageBreakdown {
+  role: string;
+  provider: string;
+  model: string;
+  status: UsageAvailability;
+  input_tokens: number | null;
+  output_tokens: number | null;
+  total_tokens: number | null;
+  estimated_cost_usd: number | null;
+  invocation_count: number;
+}
+
+export interface FeatureUsageSummary {
+  feature_id: string;
+  aggregate_tokens: number;
+  aggregate_estimated_cost_usd: number;
+  aggregate_status: UsageAvailability;
+  by_role: RoleUsageBreakdown[];
+  last_updated: string;
+}
+
+/**
+ * Creates a usage record indicating the provider does not expose token data.
+ */
+export function unavailableUsage(
+  provider: string,
+  model: string,
+  role: string,
+): NormalizedUsageRecord {
+  return {
+    status: 'unavailable',
+    input_tokens: null,
+    output_tokens: null,
+    total_tokens: null,
+    provider,
+    model,
+    role,
+    estimated_cost_usd: null,
+  };
+}
+
+/**
+ * Creates a usage record with reported token counts from API response.
+ */
+export function reportedUsage(
+  provider: string,
+  model: string,
+  role: string,
+  inputTokens: number,
+  outputTokens: number,
+  estimatedCostUsd?: number | null,
+): NormalizedUsageRecord {
+  return {
+    status: 'reported',
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    total_tokens: inputTokens + outputTokens,
+    provider,
+    model,
+    role,
+    estimated_cost_usd: estimatedCostUsd ?? null,
+  };
+}
+
+/**
+ * Creates a usage record with estimated token counts.
+ */
+export function estimatedUsage(
+  provider: string,
+  model: string,
+  role: string,
+  inputTokens: number,
+  outputTokens: number,
+  estimatedCostUsd?: number | null,
+): NormalizedUsageRecord {
+  return {
+    status: 'estimated',
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    total_tokens: inputTokens + outputTokens,
+    provider,
+    model,
+    role,
+    estimated_cost_usd: estimatedCostUsd ?? null,
+  };
+}
+
+/**
+ * Derives the worst-case availability across multiple records.
+ * unavailable > estimated > reported
+ */
+export function aggregateAvailability(records: NormalizedUsageRecord[]): UsageAvailability {
+  if (records.length === 0) {
+    return 'unavailable';
+  }
+  let hasEstimated = false;
+  for (const record of records) {
+    if (record.status === 'unavailable') {
+      return 'unavailable';
+    }
+    if (record.status === 'estimated') {
+      hasEstimated = true;
+    }
+  }
+  return hasEstimated ? 'estimated' : 'reported';
+}

package/apps/control-plane/src/cli/add-command-handler.ts

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import { STATUS, TOOLS } from '../core/constants.js';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AopKernel } from '../core/kernel.js';
+import type { ToolClient } from '../mcp/tool-client.js';
+import type { CliOptions, ToolTransport } from './types.js';
+import { SpecInputResolver } from './spec-input-resolver.js';
+import { SpecIngestionService } from './spec-ingestion-service.js';
+import { callCliTool } from './tooling.js';
+
+export interface AddCommandContext {
+  repoRoot: string;
+  runId: string;
+  transport: ToolTransport;
+  options: CliOptions;
+  kernel: AopKernel;
+  toolClient: ToolClient;
+}
+
+const RESUME_BLOCKED_STATUSES = new Set<string>([
+  STATUS.MERGED,
+  STATUS.FAILED,
+  STATUS.PAUSED_BUDGET,
+  STATUS.READY_TO_MERGE,
+]);
+
+export class AddCommandHandler {
+  private normalizeFeatureId(value: string | undefined): string | null {
+    if (typeof value !== 'string') {
+      return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+
+  private invalidArgs(message: string, details: Record<string, unknown>) {
+    const error = new Error(message) as Error & {
+      code?: string;
+      details?: Record<string, unknown>;
+    };
+    error.code = ERROR_CODES.INVALID_CLI_ARGS;
+    error.details = details;
+    return error;
+  }
+
+  private canonicalSpecPath(repoRoot: string, featureId: string): string {
+    return path.relative(repoRoot, path.join(repoRoot, '.aop', 'features', featureId, 'spec.md'));
+  }
+
+  private async buildRequestedFeatures(
+    repoRoot: string,
+    runId: string,
+    options: CliOptions,
+    kernel: AopKernel,
+    toolClient: ToolClient,
+  ): Promise<Array<{ feature_id: string; spec_path: string }>> {
+    const resumeFeatureId = this.normalizeFeatureId(options.resume_feature_id);
+    const usingResume = resumeFeatureId !== null;
+    const usingSpecInput = Boolean(options.file_input || options.folder_input);
+
+    if (usingResume && usingSpecInput) {
+      throw this.invalidArgs('aop add accepts either --resume or --fi/--fl, not both', {
+        reason: 'conflicting_add_sources',
+        resume_feature_id: resumeFeatureId,
+      });
+    }
+
+    if (usingResume) {
+      const state = await kernel.featureStateGet(resumeFeatureId);
+      const frontMatter =
+        state.data.front_matter && typeof state.data.front_matter === 'object'
+          ? (state.data.front_matter as Record<string, unknown>)
+          : {};
+      const status = typeof frontMatter.status === 'string' ? frontMatter.status : STATUS.PLANNING;
+
+      if (RESUME_BLOCKED_STATUSES.has(status)) {
+        throw this.invalidArgs('aop add --resume requires a resumable non-terminal feature', {
+          reason: 'feature_not_resumable',
+          feature_id: resumeFeatureId,
+          status,
+        });
+      }
+
+      return [
+        {
+          feature_id: resumeFeatureId,
+          spec_path: this.canonicalSpecPath(repoRoot, resumeFeatureId).replaceAll('\\', '/'),
+        },
+      ];
+    }
+
+    if (!usingSpecInput) {
+      throw this.invalidArgs('aop add requires --resume, --fi, or --fl', {
+        reason: 'missing_add_source',
+      });
+    }
+
+    const specResolver = new SpecInputResolver(repoRoot, toolClient, runId);
+    const ingestionService = new SpecIngestionService(repoRoot, toolClient, runId);
+    const resolvedPaths = await specResolver.resolve(options);
+    const prepared = await ingestionService.prepare(resolvedPaths);
+    return prepared.map((item) => ({
+      feature_id: item.feature_id,
+      spec_path: item.canonical_spec_path,
+    }));
+  }
+
+  async execute(context: AddCommandContext): Promise<unknown> {
+    const { repoRoot, runId, transport, options, kernel, toolClient } = context;
+
+    const runtimeSessions = await kernel.getRuntimeSessions();
+    const hasActiveRun =
+      runtimeSessions.run_id !== 'none' &&
+      runtimeSessions.owner_instance_id !== 'none' &&
+      kernel.isRunLeaseFresh(runtimeSessions);
+    if (!hasActiveRun) {
+      const error = new Error('No active run is available for feature enrollment') as Error & {
+        code?: string;
+        details?: Record<string, unknown>;
+      };
+      error.code = ERROR_CODES.RUN_NOT_ACTIVE;
+      error.details = {
+        retryable: false,
+        requires_human: true,
+      };
+      throw error;
+    }
+
+    const requestedFeatures = await this.buildRequestedFeatures(
+      repoRoot,
+      runId,
+      options,
+      kernel,
+      toolClient,
+    );
+    const submitted = await callCliTool(toolClient, runId, TOOLS.RUNTIME_EXECUTION_REQUEST_SUBMIT, {
+      run_id: runtimeSessions.run_id,
+      owner_instance_id: runtimeSessions.owner_instance_id,
+      request_type: 'add_features',
+      features: requestedFeatures,
+    });
+
+    const data = submitted.data as {
+      run_id: string;
+      request_id: string;
+      request_status: 'pending';
+      requested_features: Array<{ feature_id: string; spec_path: string }>;
+    };
+
+    return {
+      ok: true,
+      data: {
+        command: 'add',
+        transport,
+        run_id: data.run_id,
+        request_id: data.request_id,
+        request_status: data.request_status,
+        requested_features: data.requested_features,
+      },
+    };
+  }
+}