agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/core/worktree-diff.ts

@@ -0,0 +1,66 @@
+import crypto from 'node:crypto';
+import { runGit } from './git.js';
+
+const EMPTY_DIFF_HASH = crypto.createHash('sha256').update('', 'utf8').digest('hex');
+const DEV_NULL_PATH = '/dev/null';
+
+function parseNullSeparatedPaths(stdout: string): string[] {
+  return stdout
+    .split('\0')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function readTrackedDiff(repoRoot: string, worktreePath: string): Promise<string> {
+  const diff = await runGit(repoRoot, ['diff', '--no-ext-diff', '--binary'], {
+    cwd: worktreePath,
+  });
+  return diff.code === 0 ? diff.stdout : '';
+}
+
+async function readUntrackedPaths(repoRoot: string, worktreePath: string): Promise<string[]> {
+  const untracked = await runGit(repoRoot, ['ls-files', '--others', '--exclude-standard', '-z'], {
+    cwd: worktreePath,
+  });
+  if (untracked.code !== 0) {
+    return [];
+  }
+  return parseNullSeparatedPaths(untracked.stdout);
+}
+
+async function readUntrackedDiffs(repoRoot: string, worktreePath: string): Promise<string[]> {
+  const untrackedPaths = await readUntrackedPaths(repoRoot, worktreePath);
+  const patches: string[] = [];
+  for (const relativePath of untrackedPaths) {
+    const patch = await runGit(
+      repoRoot,
+      ['diff', '--no-index', '--no-ext-diff', '--binary', '--', DEV_NULL_PATH, relativePath],
+      {
+        cwd: worktreePath,
+      },
+    );
+    if (patch.code === 0 || patch.code === 1) {
+      patches.push(patch.stdout);
+    }
+  }
+  return patches;
+}
+
+export async function readMaterializedWorktreeDiff(
+  repoRoot: string,
+  worktreePath: string,
+): Promise<string> {
+  const trackedDiff = await readTrackedDiff(repoRoot, worktreePath);
+  const untrackedDiffs = await readUntrackedDiffs(repoRoot, worktreePath);
+  return [trackedDiff, ...untrackedDiffs].filter((entry) => entry.length > 0).join('');
+}
+
+export function hashWorktreeDiff(diffText: string): string {
+  if (diffText.length === 0) {
+    return EMPTY_DIFF_HASH;
+  }
+  return crypto.createHash('sha256').update(diffText, 'utf8').digest('hex');
+}
+
+export { EMPTY_DIFF_HASH };

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

@@ -1,7 +1,11 @@
 export { AopKernel } from './core/kernel.js';
 export type { AgentsConfigSnapshot } from './core/kernel.js';
 export { SupervisorRuntime } from './supervisor/runtime.js';
-export { resolveProviderSelection, NullWorkerProvider } from './providers/providers.js';
+export {
+  resolveProviderSelection,
+  NullWorkerProvider,
+  CREDENTIAL_REQUIRED_PROVIDERS,
+} from './providers/providers.js';
 export type { WorkerProvider, ProviderSelectionResolver } from './providers/providers.js';
 export {
   DefaultWorkerProviderFactory,
@@ -15,6 +19,7 @@ export {
   resolveProviderSpawnFailureAction,
   resolveOutputLoopStallAction,
   resolvePlanConformanceStallAction,
+  resolvePromptOverlayDir,
 } from './providers/worker-provider-factory.js';
 export type {
   WorkerProviderMode,
@@ -32,3 +37,26 @@ export {
   isMutatingTool,
   toolRequiresOperationId,
 } from './application/tools/tool-metadata.js';
+export { prepareSpecDraft, prepareSpecDrafts } from './cli/spec-preparation.js';
+export {
+  buildCanonicalSpecPath,
+  canonicalFeatureIdFromMarkdown,
+  canonicalFeatureIdFromPath,
+  canonicalFeatureIdFromSourceText,
+  normalizeFeatureIdCandidate,
+} from './cli/spec-utils.js';
+export { ResumeCommandHandler } from './cli/resume-command-handler.js';
+export { hasPendingMainlineConflict } from './core/mainline-conflict.js';
+export {
+  mergeFailureRequiresRepairLoop,
+  shouldAttemptAutoResumeAfterRetry,
+} from './cli/retry-resume-decision.js';
+export { RetryCommandHandler } from './cli/retry-command-handler.js';
+export {
+  normalizeMergeRepairState,
+  buildMergeRepairQaReroute,
+  buildMergeGateFailureState,
+  isBlockedMergeGateFailure,
+  clearActiveMergeRepair,
+} from './core/merge-repair.js';
+export type { MergeRepairState } from './core/merge-repair.js';

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

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { AopKernel } from '../../core/kernel.js';
@@ -12,19 +13,31 @@ import { createToolingRuntime, resolveToolClient } from '../../mcp/runtime-facto
 import { CliArgumentParser } from '../../cli/cli-argument-parser.js';
 import { CliCommand } from '../../cli/types.js';
 import { printError, printPayload } from '../../cli/io.js';
+import { CompletionCommandHandler } from '../../cli/completion-command-handler.js';
+import { CompleteCommandHandler } from '../../cli/complete-command-handler.js';
 import { StatusCommandHandler } from '../../cli/status-command-handler.js';
+import { QuestionsCommandHandler } from '../../cli/questions-command-handler.js';
+import { AnswerCommandHandler } from '../../cli/answer-command-handler.js';
 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 { AddCommandHandler } from '../../cli/add-command-handler.js';
 import { InitCommandHandler } from '../../cli/init-command-handler.js';
 import { DashboardCommandHandler } from '../../cli/dashboard-command-handler.js';
+import { CollisionCommandHandler } from '../../cli/collision-command-handler.js';
 import { RetryCommandHandler } from '../../cli/retry-command-handler.js';
+import { MergeCommandHandler } from '../../cli/merge-command-handler.js';
 import { SendCommandHandler } from '../../cli/send-command-handler.js';
 import { AttachCommandHandler } from '../../cli/attach-command-handler.js';
 import { HelpCommandHandler } from '../../cli/help-command-handler.js';
+import { ReplayCommandHandler } from '../../cli/replay-command-handler.js';
+import {
+  mergeFailureRequiresRepairLoop,
+  shouldAttemptAutoResumeAfterRetry,
+} from '../../cli/retry-resume-decision.js';
 import { readEnvFileValues } from '../../cli/env-file.js';
 import { MultiProjectLoader } from '../../application/multi-project-loader.js';
 import { resolveProviderSelection } from '../../providers/providers.js';
@@ -34,12 +47,45 @@ import {
   resolveWorkerProviderObservability,
   resolveWorkerProviderPolicy,
   resolveWorkerProviderRuntime,
+  resolvePromptOverlayDir,
 } from '../../providers/worker-provider-factory.js';
 import type { RuntimeContext } from '../../cli/types.js';
+import type { CliOptions, ToolTransport } from '../../cli/types.js';
 import type { ProjectConfig } from '../../application/multi-project-loader.js';
+import type { ToolClient } from '../../mcp/tool-client.js';
 
 const SUPPORTED_COMMANDS = new Set<string>(Object.values(CliCommand));
 
+/**
+ * Resolves the main repository root when running from inside a git worktree.
+ * Git worktrees have a `.git` file (not dir) containing: `gitdir: /path/to/.git/worktrees/<name>`
+ * We extract the main repo root so the kernel always uses the authoritative `.aop/` directory.
+ */
+async function resolveWorktreeAwareRoot(cwd: string): Promise<string> {
+  try {
+    const gitPath = path.join(cwd, '.git');
+    const stat = await fs.stat(gitPath);
+    if (stat.isDirectory()) {
+      return cwd;
+    }
+    const gitFileContent = await fs.readFile(gitPath, 'utf8');
+    const match = /^gitdir:\s*(.+)$/m.exec(gitFileContent);
+    if (!match) {
+      return cwd;
+    }
+    const gitdir = match[1].trim();
+    const worktreesMarker = `${path.sep}worktrees${path.sep}`;
+    const worktreesIdx = gitdir.indexOf(worktreesMarker);
+    if (worktreesIdx === -1) {
+      return cwd;
+    }
+    const mainGitDir = gitdir.slice(0, worktreesIdx);
+    return path.dirname(mainGitDir);
+  } catch {
+    return cwd;
+  }
+}
+
 function isPathWithin(parent: string, target: string): boolean {
   const relative = path.relative(path.resolve(parent), path.resolve(target));
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
@@ -59,6 +105,16 @@ interface NormalizedCliError {
   details: Record<string, unknown>;
 }
 
+interface CommandPayloadEnvelope {
+  ok: boolean;
+  data?: Record<string, unknown>;
+  error?: {
+    code?: string;
+    message?: string;
+    details?: Record<string, unknown>;
+  };
+}
+
 function normalizeCliError(error: unknown): NormalizedCliError {
   if (error && typeof error === 'object') {
     const errorRecord = error as Record<string, unknown>;
@@ -99,6 +155,63 @@ function normalizeCliError(error: unknown): NormalizedCliError {
   };
 }
 
+async function attemptFeatureRepairHandoff(params: {
+  repoRoot: string;
+  env: NodeJS.ProcessEnv;
+  runId: string;
+  transport: ToolTransport;
+  options: CliOptions;
+  kernel: AopKernel;
+  toolClient: ToolClient;
+  featureId: string;
+}): Promise<{ ok: boolean; data?: Record<string, unknown> }> {
+  return (await new ResumeCommandHandler().execute({
+    repoRoot: params.repoRoot,
+    env: params.env,
+    runId: params.runId,
+    transport: params.transport,
+    options: {
+      ...params.options,
+      command: CliCommand.Resume,
+      feature_id: params.featureId,
+      takeover_stale_run: true,
+    },
+    kernel: params.kernel,
+    toolClient: params.toolClient,
+  })) as { ok: boolean; data?: Record<string, unknown> };
+}
+
+async function attemptMergeFailureRepairHandoff(params: {
+  repoRoot: string;
+  env: NodeJS.ProcessEnv;
+  runId: string;
+  transport: ToolTransport;
+  options: CliOptions;
+  kernel: AopKernel;
+  toolClient: ToolClient;
+  featureId: string;
+}): Promise<{
+  retry: { ok: boolean; data?: Record<string, unknown> };
+  autoResume: { ok: boolean; data?: Record<string, unknown> };
+}> {
+  const retryPayload = (await new RetryCommandHandler(params.toolClient, params.runId).execute({
+    ...params.options,
+    command: CliCommand.Retry,
+    feature_id: params.featureId,
+    no_resume: true,
+  })) as { ok: boolean; data?: Record<string, unknown> };
+
+  const autoResumePayload = (await attemptFeatureRepairHandoff(params)) as {
+    ok: boolean;
+    data?: Record<string, unknown>;
+  };
+
+  return {
+    retry: retryPayload,
+    autoResume: autoResumePayload,
+  };
+}
+
 async function promptForProjectSelection(projects: ProjectConfig[]): Promise<string | null> {
   const sorted = [...projects].sort((a, b) => a.name.localeCompare(b.name));
   process.stdout.write('Multiple projects configured. Select one:\n');
@@ -129,11 +242,37 @@ export async function runCli(
   const parser = new CliArgumentParser();
   const options = parser.parse(argv);
 
+  // Fast-path: completion commands need no project context.
+  if (options.command === CliCommand.Completion) {
+    const handler = new CompletionCommandHandler();
+    try {
+      const payload = handler.execute(options.shell);
+      process.stdout.write(payload.data.script + '\n');
+      return 0;
+    } catch {
+      printError(ERROR_CODES.INVALID_CLI_ARGS, `Unsupported shell: ${options.shell ?? '(none)'}`, {
+        provided: options.shell,
+        supported: ['bash', 'zsh', 'fish'],
+      });
+      return 1;
+    }
+  }
+
+  if (options.command === CliCommand.InternalComplete) {
+    const shellArgs = argv.slice(1);
+    const handler = new CompleteCommandHandler(runtime.cwd);
+    const candidates = handler.resolve(shellArgs);
+    if (candidates.length > 0) {
+      process.stdout.write(candidates.join('\n') + '\n');
+    }
+    return 0; // always exit 0
+  }
+
   const multiLoader = new MultiProjectLoader();
   const multiConfig = await multiLoader.load(runtime.cwd);
 
   // Resolve repo root and project context.
-  let repoRoot = runtime.cwd;
+  let repoRoot = await resolveWorktreeAwareRoot(runtime.cwd);
   let selectedProject: ProjectConfig | null = null;
 
   if (options.project) {
@@ -250,6 +389,7 @@ export async function runCli(
         port: options.port ?? defaultDashboardPort,
         foreground: options.foreground,
         dev: options.dev,
+        repoRoot,
       });
       printPayload(payload);
       return 0;
@@ -334,6 +474,13 @@ export async function runCli(
     const tooling = await createToolingRuntime(repoRoot, kernel);
     const toolClient = resolveToolClient(transport, tooling);
 
+    if (options.command === CliCommand.Collision) {
+      const handler = new CollisionCommandHandler(kernel, runId);
+      const payload = await handler.execute(options);
+      printPayload(payload);
+      return 0;
+    }
+
     let commandProvider = null;
     if (options.command === CliCommand.Send || options.command === CliCommand.Attach) {
       let selection;
@@ -361,6 +508,10 @@ export async function runCli(
         policySnapshot.observability && typeof policySnapshot.observability === 'object'
           ? (policySnapshot.observability as Record<string, unknown>)
           : null;
+      const overlayDir = resolvePromptOverlayDir(
+        repoRoot,
+        kernel.getAgentsConfig().runtime?.prompt_overlay_dir,
+      );
       commandProvider = workerProviderFactory.create({
         selection,
         mode: resolveWorkerProviderMode(
@@ -373,6 +524,7 @@ export async function runCli(
         observability: resolveWorkerProviderObservability(observabilityPolicy),
         runtime: resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime),
         repoRoot,
+        overlayDir,
       });
       kernel.setProvider(commandProvider);
     }
@@ -384,6 +536,34 @@ export async function runCli(
       return 0;
     }
 
+    if (options.command === CliCommand.Questions) {
+      const handler = new QuestionsCommandHandler(toolClient, runId);
+      const payload = await handler.execute(options);
+      printPayload(payload);
+      return 0;
+    }
+
+    if (options.command === CliCommand.Answer) {
+      const handler = new AnswerCommandHandler(toolClient, runId);
+      const payload = await handler.execute(options);
+      printPayload(payload);
+      return 0;
+    }
+
+    if (options.command === CliCommand.Add) {
+      const handler = new AddCommandHandler();
+      const payload = await handler.execute({
+        repoRoot,
+        runId,
+        transport,
+        options,
+        kernel,
+        toolClient,
+      });
+      printPayload(payload);
+      return 0;
+    }
+
     if (options.command === CliCommand.Resume) {
       const handler = new ResumeCommandHandler();
       const payload = await handler.execute({
@@ -408,10 +588,18 @@ export async function runCli(
 
     if (options.command === CliCommand.Cleanup) {
       const policySnapshot = kernel.getPolicySnapshot() as {
-        cleanup?: { grace_period_seconds?: number; auto_after_merge?: boolean };
+        cleanup?: {
+          auto_after_merge?: {
+            aop?: { enabled?: boolean; grace_period_seconds?: number };
+          };
+        };
       };
-      const gracePeriodSeconds = policySnapshot.cleanup?.grace_period_seconds;
-      const autoAfterMerge = policySnapshot.cleanup?.auto_after_merge === true;
+      const aopCleanup = policySnapshot.cleanup?.auto_after_merge?.aop;
+      const gracePeriodSeconds =
+        typeof aopCleanup?.grace_period_seconds === 'number'
+          ? aopCleanup.grace_period_seconds
+          : undefined;
+      const autoAfterMerge = aopCleanup?.enabled === true;
       const handler = new CleanupCommandHandler(
         toolClient,
         runId,
@@ -433,8 +621,101 @@ export async function runCli(
 
     if (options.command === CliCommand.Retry) {
       const handler = new RetryCommandHandler(toolClient, runId);
-      const payload = await handler.execute(options);
-      printPayload(payload);
+      const retryPayload = (await handler.execute(options)) as {
+        ok: boolean;
+        data?: Record<string, unknown>;
+      };
+      if (options.no_resume) {
+        printPayload(retryPayload);
+        return 0;
+      }
+
+      const autoResumeDecision = shouldAttemptAutoResumeAfterRetry(retryPayload);
+      if (!autoResumeDecision.attempt) {
+        printPayload({
+          ok: true,
+          data: {
+            retry: retryPayload.data ?? {},
+            auto_resume: {
+              attempted: false,
+              skipped_reason: autoResumeDecision.skippedReason ?? 'no_resume_required',
+            },
+          },
+        });
+        return 0;
+      }
+
+      const retryFeatureId =
+        typeof options.feature_id === 'string' ? options.feature_id : undefined;
+      try {
+        const autoResumePayload = await attemptFeatureRepairHandoff({
+          repoRoot,
+          env: effectiveEnv,
+          runId,
+          transport,
+          options,
+          kernel,
+          toolClient,
+          featureId: retryFeatureId ?? '',
+        });
+        printPayload({
+          ok: true,
+          data: {
+            retry: retryPayload.data ?? {},
+            auto_resume: { attempted: true, ok: true, data: autoResumePayload.data ?? {} },
+          },
+        });
+      } catch (error) {
+        const normalized = normalizeCliError(error);
+        printPayload({
+          ok: true,
+          data: {
+            retry: retryPayload.data ?? {},
+            auto_resume: { attempted: true, ok: false, error: normalized },
+          },
+        });
+      }
+      return 0;
+    }
+
+    if (options.command === CliCommand.Merge) {
+      const handler = new MergeCommandHandler(toolClient, runId);
+      const payload = (await handler.execute(options)) as CommandPayloadEnvelope;
+      const repairFeatureId = mergeFailureRequiresRepairLoop(payload);
+      if (!repairFeatureId) {
+        printPayload(payload);
+        return 0;
+      }
+
+      try {
+        const handoff = await attemptMergeFailureRepairHandoff({
+          repoRoot,
+          env: effectiveEnv,
+          runId,
+          transport,
+          options,
+          kernel,
+          toolClient,
+          featureId: repairFeatureId,
+        });
+        printPayload({
+          ok: true,
+          data: {
+            merge: payload,
+            retry: handoff.retry.data ?? {},
+            auto_resume: { attempted: true, ok: true, data: handoff.autoResume.data ?? {} },
+          },
+        });
+      } catch (error) {
+        const normalized = normalizeCliError(error);
+        printPayload({
+          ok: true,
+          data: {
+            merge: payload,
+            auto_resume: { attempted: true, ok: false, error: normalized },
+          },
+        });
+      }
       return 0;
     }
 
@@ -457,6 +738,19 @@ export async function runCli(
       return 0;
     }
 
+    if (options.command === CliCommand.Replay) {
+      const handler = new ReplayCommandHandler(toolClient, runId);
+      await handler.execute({
+        runId: options.run_id,
+        fromSequence: options.from_sequence,
+        limit: options.limit,
+        featureId: options.feature_id,
+        toolFilter: options.tool_filter,
+        jsonOutput: options.json_output,
+      });
+      return 0;
+    }
+
     const handler = new RunCommandHandler();
     const payload = await handler.execute({
       repoRoot,

package/apps/control-plane/src/mcp/kernel-tool-executor.ts

@@ -27,6 +27,9 @@ export class KernelToolExecutor {
         actorType: claims.actor_type,
         actorId: claims.actor_id,
       })) as Record<string, unknown>;
+      if (isToolResponseEnvelope(result)) {
+        return result;
+      }
       const payload =
         result.data && typeof result.data === 'object'
           ? (result.data as Record<string, unknown>)
@@ -41,3 +44,17 @@ export class KernelToolExecutor {
     }
   }
 }
+
+function isToolResponseEnvelope(value: unknown): value is ToolResponse {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  if (record.ok === true) {
+    return Object.prototype.hasOwnProperty.call(record, 'data');
+  }
+  if (record.ok === false) {
+    return Object.prototype.hasOwnProperty.call(record, 'error');
+  }
+  return false;
+}