@renseiai/agentfactory 0.8.5 → 0.8.7

package/dist/src/orchestrator/orchestrator.js

@@ -14,14 +14,13 @@ import { createHeartbeatWriter, getHeartbeatIntervalFromEnv } from './heartbeat-
 import { createProgressLogger } from './progress-logger.js';
 import { createSessionLogger } from './session-logger.js';
 import { isSessionLoggingEnabled, getLogAnalysisConfig } from './log-config.js';
-import { createLinearAgentClient, createAgentSession, buildCompletionComments, STATUS_WORK_TYPE_MAP, WORK_TYPE_START_STATUS, WORK_TYPE_COMPLETE_STATUS, WORK_TYPE_FAIL_STATUS, TERMINAL_STATUSES, WORK_TYPES_REQUIRING_WORKTREE, } from '@renseiai/agentfactory-linear';
 import { parseWorkResult } from './parse-work-result.js';
 import { createActivityEmitter } from './activity-emitter.js';
 import { createApiActivityEmitter } from './api-activity-emitter.js';
 import { createLogger } from '../logger.js';
 import { TemplateRegistry, createToolPermissionAdapter } from '../templates/index.js';
 import { loadRepositoryConfig, getProjectConfig, getProvidersConfig } from '../config/index.js';
-import { ToolRegistry, linearPlugin } from '../tools/index.js';
+import { ToolRegistry } from '../tools/index.js';
 // Default inactivity timeout: 5 minutes
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 300000;
 // Default max session timeout: unlimited (undefined)
@@ -442,6 +441,46 @@ Dependencies are symlinked from the main repo by the orchestrator. Do NOT run pn
 If you encounter a specific "Cannot find module" error, run it SYNCHRONOUSLY
 (never with run_in_background). Never use sleep or polling loops to wait for commands.
 
+IMPORTANT: If you encounter "exceeds maximum allowed tokens" error when reading files:
+- Use Grep to search for specific code patterns instead of reading entire files
+- Use Read with offset/limit parameters to paginate through large files
+- Avoid reading auto-generated files like payload-types.ts (use Grep instead)
+See the "Working with Large Files" section in the project documentation (CLAUDE.md / AGENTS.md) for details.${LINEAR_CLI_INSTRUCTION}`;
+            break;
+        case 'inflight-coordination':
+            basePrompt = `Resume coordination of sub-issue execution for parent issue ${identifier}.
+Check sub-issue statuses, continue work on incomplete sub-issues, and create a PR when all are done.
+
+SUB-ISSUE STATUS MANAGEMENT:
+You MUST update sub-issue statuses in Linear as work progresses:
+- When starting work on a sub-issue: pnpm af-linear update-sub-issue <id> --state Started
+- When a sub-agent completes a sub-issue: pnpm af-linear update-sub-issue <id> --state Finished --comment "Completed by coordinator agent"
+- If a sub-agent fails on a sub-issue: pnpm af-linear create-comment <sub-issue-id> --body "Sub-agent failed: <reason>"
+
+COMPLETION VERIFICATION:
+Before marking the parent issue as complete, verify ALL sub-issues are in Finished status:
+  pnpm af-linear list-sub-issue-statuses ${identifier}
+If any sub-issue is not Finished, report the failure and do not mark the parent as complete.
+
+SUB-AGENT SAFETY RULES (CRITICAL):
+This is a SHARED WORKTREE. Multiple sub-agents run concurrently in this directory.
+Every sub-agent prompt you construct MUST include these rules:
+
+1. NEVER run: git worktree remove, git worktree prune
+2. NEVER run: git checkout, git switch (to a different branch)
+3. NEVER run: git reset --hard, git clean -fd, git restore .
+4. NEVER delete or modify the .git file in the worktree root
+5. Only the orchestrator manages worktree lifecycle
+6. Work only on files relevant to your sub-issue to minimize conflicts
+7. Commit changes with descriptive messages before reporting completion
+
+Prefix every sub-agent prompt with: "SHARED WORKTREE — DO NOT MODIFY GIT STATE"
+
+DEPENDENCY INSTALLATION:
+Dependencies are symlinked from the main repo by the orchestrator. Do NOT run pnpm install.
+If you encounter a specific "Cannot find module" error, run it SYNCHRONOUSLY
+(never with run_in_background). Never use sleep or polling loops to wait for commands.
+
 IMPORTANT: If you encounter "exceeds maximum allowed tokens" error when reading files:
 - Use Grep to search for specific code patterns instead of reading entire files
 - Use Read with offset/limit parameters to paginate through large files
@@ -651,6 +690,7 @@ const WORK_TYPE_SUFFIX = {
     'backlog-creation': 'BC',
     development: 'DEV',
     inflight: 'INF',
+    'inflight-coordination': 'INF-COORD',
     coordination: 'COORD',
     qa: 'QA',
     acceptance: 'AC',
@@ -678,8 +718,9 @@ export function getWorktreeIdentifier(issueIdentifier, workType) {
  * being dispatched as 'development' (which uses the wrong template and
  * produces no sub-agent orchestration).
  */
-export function detectWorkType(statusName, isParent) {
-    let workType = STATUS_WORK_TYPE_MAP[statusName] ?? 'development';
+export function detectWorkType(statusName, isParent, statusToWorkType) {
+    const mapping = statusToWorkType ?? {};
+    let workType = mapping[statusName] ?? 'development';
     console.log(`Auto-detected work type: ${workType} (from status: ${statusName})`);
     if (isParent) {
         if (workType === 'development')
@@ -688,6 +729,8 @@ export function detectWorkType(statusName, isParent) {
             workType = 'qa-coordination';
         else if (workType === 'acceptance')
             workType = 'acceptance-coordination';
+        else if (workType === 'inflight')
+            workType = 'inflight-coordination';
         else if (workType === 'refinement')
             workType = 'refinement-coordination';
         console.log(`Upgraded to coordination work type: ${workType} (parent issue)`);
@@ -697,6 +740,7 @@ export function detectWorkType(statusName, isParent) {
 export class AgentOrchestrator {
     config;
     client;
+    statusMappings;
     events;
     activeAgents = new Map();
     agentHandles = new Map();
@@ -737,10 +781,15 @@ export class AgentOrchestrator {
     validateCommand;
     // Tool plugin registry for in-process agent tools
     toolRegistry;
+    // Git repository root for running git commands (resolved from worktreePath or cwd)
+    gitRoot;
     constructor(config = {}, events = {}) {
-        const apiKey = config.linearApiKey ?? process.env.LINEAR_API_KEY;
-        if (!apiKey) {
-            throw new Error('LINEAR_API_KEY is required');
+        // Validate that an issue tracker client is available
+        if (!config.issueTrackerClient) {
+            const apiKey = config.linearApiKey ?? process.env.LINEAR_API_KEY;
+            if (!apiKey) {
+                throw new Error('Either issueTrackerClient or LINEAR_API_KEY is required');
+            }
         }
         // Parse timeout config from environment variables (can be overridden by config)
         const envInactivityTimeout = process.env.AGENT_INACTIVITY_TIMEOUT_MS
@@ -752,7 +801,7 @@ export class AgentOrchestrator {
         this.config = {
             ...DEFAULT_CONFIG,
             ...config,
-            linearApiKey: apiKey,
+            linearApiKey: config.linearApiKey ?? process.env.LINEAR_API_KEY ?? '',
             streamConfig: {
                 ...DEFAULT_CONFIG.streamConfig,
                 ...config.streamConfig,
@@ -763,11 +812,15 @@ export class AgentOrchestrator {
             inactivityTimeoutMs: config.inactivityTimeoutMs ?? envInactivityTimeout ?? DEFAULT_CONFIG.inactivityTimeoutMs,
             maxSessionTimeoutMs: config.maxSessionTimeoutMs ?? envMaxSessionTimeout ?? DEFAULT_CONFIG.maxSessionTimeoutMs,
         };
+        // Resolve git root from worktreePath (which may point to a different repo than cwd)
+        this.gitRoot = findRepoRoot(resolve(this.config.worktreePath)) ?? findRepoRoot(process.cwd()) ?? process.cwd();
         // Validate git remote matches configured repository (if set)
         if (this.config.repository) {
-            validateGitRemote(this.config.repository);
+            validateGitRemote(this.config.repository, this.gitRoot);
         }
-        this.client = createLinearAgentClient({ apiKey });
+        // Use injected client or fail (caller must provide one)
+        this.client = config.issueTrackerClient;
+        this.statusMappings = config.statusMappings;
         this.events = events;
         // Initialize default agent provider — per-spawn resolution may override
         const providerName = resolveProviderName({ project: config.project });
@@ -779,8 +832,8 @@ export class AgentOrchestrator {
             if (config.templateDir) {
                 templateDirs.push(config.templateDir);
             }
-            // Auto-detect .agentfactory/templates/ in working directory
-            const projectTemplateDir = resolve(process.cwd(), '.agentfactory', 'templates');
+            // Auto-detect .agentfactory/templates/ in target repo
+            const projectTemplateDir = resolve(this.gitRoot, '.agentfactory', 'templates');
             if (existsSync(projectTemplateDir) && !templateDirs.includes(projectTemplateDir)) {
                 templateDirs.push(projectTemplateDir);
             }
@@ -797,7 +850,7 @@ export class AgentOrchestrator {
         }
         // Auto-load .agentfactory/config.yaml from repository root
         try {
-            const repoRoot = findRepoRoot(process.cwd());
+            const repoRoot = this.gitRoot;
             if (repoRoot) {
                 const repoConfig = loadRepositoryConfig(repoRoot);
                 if (repoConfig) {
@@ -805,7 +858,7 @@ export class AgentOrchestrator {
                     // Use repository from config as fallback if not set in OrchestratorConfig
                     if (!this.config.repository && repoConfig.repository) {
                         this.config.repository = repoConfig.repository;
-                        validateGitRemote(this.config.repository);
+                        validateGitRemote(this.config.repository, this.gitRoot);
                     }
                     // Store allowedProjects for backlog filtering
                     if (repoConfig.projectPaths) {
@@ -845,9 +898,13 @@ export class AgentOrchestrator {
         catch (err) {
             console.warn('[orchestrator] Failed to load .agentfactory/config.yaml:', err instanceof Error ? err.message : err);
         }
-        // Initialize tool plugin registry with Linear plugin
+        // Initialize tool plugin registry with injected plugins
         this.toolRegistry = new ToolRegistry();
-        this.toolRegistry.register(linearPlugin);
+        if (config.toolPlugins) {
+            for (const plugin of config.toolPlugins) {
+                this.toolRegistry.register(plugin);
+            }
+        }
     }
     /**
      * Update the last activity timestamp for an agent (for inactivity timeout tracking)
@@ -891,86 +948,63 @@ export class AgentOrchestrator {
      */
     async detectWorkType(issueId, statusName) {
         const isParent = await this.client.isParentIssue(issueId);
-        return detectWorkType(statusName, isParent);
+        return detectWorkType(statusName, isParent, this.statusMappings.statusToWorkType);
     }
     /**
      * Get backlog issues for the configured project
      */
     async getBacklogIssues(limit) {
         const maxIssues = limit ?? this.config.maxConcurrent;
-        // Build filter based on project
-        const filter = {
-            state: { name: { eqIgnoreCase: 'Backlog' } },
-        };
-        if (this.config.project) {
-            const projects = await this.client.linearClient.projects({
-                filter: { name: { eqIgnoreCase: this.config.project } },
-            });
-            if (projects.nodes.length > 0) {
-                filter.project = { id: { eq: projects.nodes[0].id } };
-                // Cross-reference project repo metadata with config (SUP-725)
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- runtime check for method added in SUP-725
-                const clientAny = this.client;
-                if (this.config.repository && typeof clientAny.getProjectRepositoryUrl === 'function') {
-                    try {
-                        const projectRepoUrl = await clientAny.getProjectRepositoryUrl(projects.nodes[0].id);
-                        if (projectRepoUrl) {
-                            const normalizedProjectRepo = projectRepoUrl
-                                .replace(/^https?:\/\//, '')
-                                .replace(/\.git$/, '');
-                            const normalizedConfigRepo = this.config.repository
-                                .replace(/^https?:\/\//, '')
-                                .replace(/\.git$/, '');
-                            if (!normalizedProjectRepo.includes(normalizedConfigRepo) && !normalizedConfigRepo.includes(normalizedProjectRepo)) {
-                                console.warn(`Warning: Project '${this.config.project}' repository metadata '${projectRepoUrl}' ` +
-                                    `does not match configured repository '${this.config.repository}'. Skipping issues.`);
-                                return [];
-                            }
-                        }
-                    }
-                    catch (error) {
-                        // Non-fatal: log warning but continue if metadata check fails
-                        console.warn('Warning: Could not check project repository metadata:', error instanceof Error ? error.message : String(error));
+        // Cross-reference project repo metadata with config
+        if (this.config.project && this.config.repository) {
+            try {
+                const projectRepoUrl = await this.client.getProjectRepositoryUrl(this.config.project);
+                if (projectRepoUrl) {
+                    const normalizedProjectRepo = projectRepoUrl
+                        .replace(/^https?:\/\//, '')
+                        .replace(/\.git$/, '');
+                    const normalizedConfigRepo = this.config.repository
+                        .replace(/^https?:\/\//, '')
+                        .replace(/\.git$/, '');
+                    if (!normalizedProjectRepo.includes(normalizedConfigRepo) && !normalizedConfigRepo.includes(normalizedProjectRepo)) {
+                        console.warn(`Warning: Project '${this.config.project}' repository metadata '${projectRepoUrl}' ` +
+                            `does not match configured repository '${this.config.repository}'. Skipping issues.`);
+                        return [];
                     }
                 }
             }
+            catch (error) {
+                // Non-fatal: log warning but continue if metadata check fails
+                console.warn('Warning: Could not check project repository metadata:', error instanceof Error ? error.message : String(error));
+            }
         }
-        const issues = await this.client.linearClient.issues({
-            filter,
-            first: maxIssues * 2, // Fetch extra to account for filtering
+        // Query issues using the abstract client
+        const allIssues = await this.client.queryIssues({
+            project: this.config.project,
+            status: 'Backlog',
+            maxResults: maxIssues * 2, // Fetch extra to account for filtering
         });
         const results = [];
-        for (const issue of issues.nodes) {
+        for (const issue of allIssues) {
             if (results.length >= maxIssues)
                 break;
             // Filter by allowedProjects from .agentfactory/config.yaml
-            let resolvedProjectName;
             if (this.allowedProjects && this.allowedProjects.length > 0) {
-                const project = await issue.project;
-                const projectName = project?.name;
-                if (!projectName || !this.allowedProjects.includes(projectName)) {
-                    console.warn(`[orchestrator] Skipping issue ${issue.identifier} — project "${projectName ?? '(none)'}" is not in allowedProjects: [${this.allowedProjects.join(', ')}]`);
+                if (!issue.projectName || !this.allowedProjects.includes(issue.projectName)) {
+                    console.warn(`[orchestrator] Skipping issue ${issue.identifier} — project "${issue.projectName ?? '(none)'}" is not in allowedProjects: [${this.allowedProjects.join(', ')}]`);
                     continue;
                 }
-                resolvedProjectName = projectName;
-            }
-            // Resolve project name for path scoping even when not filtering by allowedProjects
-            if (!resolvedProjectName && this.projectPaths) {
-                const project = await issue.project;
-                resolvedProjectName = project?.name;
             }
-            const labels = await issue.labels();
-            const team = await issue.team;
             results.push({
                 id: issue.id,
                 identifier: issue.identifier,
                 title: issue.title,
-                description: issue.description ?? undefined,
+                description: issue.description,
                 url: issue.url,
                 priority: issue.priority,
-                labels: labels.nodes.map((l) => l.name),
-                teamName: team?.key,
-                projectName: resolvedProjectName,
+                labels: issue.labels,
+                teamName: issue.teamName,
+                projectName: issue.projectName,
             });
         }
         // Sort by priority (lower number = higher priority, 0 means no priority -> goes last)
@@ -1075,6 +1109,7 @@ export class AgentOrchestrator {
             const output = execSync('git worktree list --porcelain', {
                 stdio: 'pipe',
                 encoding: 'utf-8',
+                cwd: this.gitRoot,
             });
             const mainTreeMatch = output.match(/^worktree (.+)$/m);
             if (mainTreeMatch) {
@@ -1134,7 +1169,7 @@ export class AgentOrchestrator {
         if (!existsSync(conflictPath)) {
             // Directory doesn't exist - just prune git's worktree list
             try {
-                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
                 console.log(`Pruned stale worktree reference for branch ${branchName}`);
                 return true;
             }
@@ -1203,6 +1238,7 @@ export class AgentOrchestrator {
             execSync(`git worktree remove "${conflictPath}" --force`, {
                 stdio: 'pipe',
                 encoding: 'utf-8',
+                cwd: this.gitRoot,
             });
             console.log(`Removed stale worktree: ${conflictPath}`);
             return true;
@@ -1219,7 +1255,7 @@ export class AgentOrchestrator {
             // this path is inside .worktrees/ and is not the main tree)
             try {
                 execSync(`rm -rf "${conflictPath}"`, { stdio: 'pipe', encoding: 'utf-8' });
-                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
                 console.log(`Force-removed stale worktree: ${conflictPath}`);
                 return true;
             }
@@ -1264,7 +1300,7 @@ export class AgentOrchestrator {
         }
         // Prune any stale worktrees first (handles deleted directories)
         try {
-            execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+            execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
         }
         catch {
             // Ignore prune errors
@@ -1306,6 +1342,7 @@ export class AgentOrchestrator {
                 execSync(`git worktree add "${worktreePath}" -b ${branchName} ${baseBranch}`, {
                     stdio: 'pipe',
                     encoding: 'utf-8',
+                    cwd: this.gitRoot,
                 });
             }
             catch (error) {
@@ -1332,6 +1369,7 @@ export class AgentOrchestrator {
                         execSync(`git worktree add "${worktreePath}" ${branchName}`, {
                             stdio: 'pipe',
                             encoding: 'utf-8',
+                            cwd: this.gitRoot,
                         });
                     }
                     catch (innerError) {
@@ -1366,7 +1404,7 @@ export class AgentOrchestrator {
                 if (existsSync(worktreePath)) {
                     execSync(`rm -rf "${worktreePath}"`, { stdio: 'pipe', encoding: 'utf-8' });
                 }
-                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
             }
             catch {
                 // Ignore cleanup errors
@@ -1399,13 +1437,14 @@ export class AgentOrchestrator {
                 execSync(`git worktree remove "${worktreePath}" --force`, {
                     stdio: 'pipe',
                     encoding: 'utf-8',
+                    cwd: this.gitRoot,
                 });
             }
             catch (error) {
                 console.warn(`Failed to remove worktree via git, trying fallback:`, error);
                 try {
                     execSync(`rm -rf "${worktreePath}"`, { stdio: 'pipe', encoding: 'utf-8' });
-                    execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+                    execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
                 }
                 catch (fallbackError) {
                     console.warn(`Fallback worktree removal also failed:`, fallbackError);
@@ -1415,7 +1454,7 @@ export class AgentOrchestrator {
         else {
             // Directory gone but git may still track it
             try {
-                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8' });
+                execSync('git worktree prune', { stdio: 'pipe', encoding: 'utf-8', cwd: this.gitRoot });
             }
             catch {
                 // Ignore
@@ -1792,8 +1831,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             else {
                 // Direct Linear API - only works with OAuth tokens (not API keys)
                 // This will fail for createAgentActivity calls but works for comments
-                const session = createAgentSession({
-                    client: this.client.linearClient,
+                const session = this.client.createSession({
                     issueId,
                     sessionId,
                     autoTransition: false, // Orchestrator handles transitions
@@ -1847,7 +1885,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         // Set work type so agent knows what kind of work it's doing
         env.LINEAR_WORK_TYPE = workType;
         // Flag shared worktree for coordination mode so sub-agents know not to modify git state
-        if (workType === 'coordination' || workType === 'qa-coordination' || workType === 'acceptance-coordination' || workType === 'refinement-coordination') {
+        if (workType === 'coordination' || workType === 'inflight-coordination' || workType === 'qa-coordination' || workType === 'acceptance-coordination' || workType === 'refinement-coordination') {
             env.SHARED_WORKTREE = 'true';
         }
         // Set Claude Code Task List ID for intra-issue task coordination
@@ -1866,7 +1904,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         // Coordinators need significantly more turns than standard agents
         // since they spawn sub-agents and poll their status repeatedly.
         // Inflight also gets the bump — it may be resuming coordination work.
-        const needsMoreTurns = workType === 'coordination' || workType === 'qa-coordination' || workType === 'acceptance-coordination' || workType === 'refinement-coordination' || workType === 'inflight';
+        const needsMoreTurns = workType === 'coordination' || workType === 'inflight-coordination' || workType === 'qa-coordination' || workType === 'acceptance-coordination' || workType === 'refinement-coordination' || workType === 'inflight';
         const maxTurns = needsMoreTurns ? 200 : undefined;
         // Spawn agent via provider interface
         const spawnConfig = {
@@ -1977,11 +2015,11 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                     }
                     agent.workResult = workResult;
                     if (workResult === 'passed') {
-                        targetStatus = WORK_TYPE_COMPLETE_STATUS[workType];
+                        targetStatus = this.statusMappings.workTypeCompleteStatus[workType];
                         log?.info('Work result: passed, promoting', { workType, targetStatus });
                     }
                     else if (workResult === 'failed') {
-                        targetStatus = WORK_TYPE_FAIL_STATUS[workType];
+                        targetStatus = this.statusMappings.workTypeFailStatus[workType];
                         log?.info('Work result: failed, transitioning to fail status', { workType, targetStatus });
                     }
                     else {
@@ -2009,8 +2047,39 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                     }
                 }
                 else {
-                    // Non-QA/acceptance: unchanged behavior — always promote on completion
-                    targetStatus = WORK_TYPE_COMPLETE_STATUS[workType];
+                    // Non-QA/acceptance: promote on completion, but validate code-producing work types first
+                    const isCodeProducing = workType === 'development' || workType === 'inflight';
+                    if (isCodeProducing && agent.worktreePath && !agent.pullRequestUrl) {
+                        // Code-producing agent completed without a detected PR — check for commits
+                        const incompleteCheck = checkForIncompleteWork(agent.worktreePath);
+                        if (incompleteCheck.hasIncompleteWork) {
+                            // Agent has uncommitted/unpushed changes — block promotion
+                            log?.error('Code-producing agent completed without PR and has incomplete work — blocking promotion', {
+                                workType,
+                                reason: incompleteCheck.reason,
+                                details: incompleteCheck.details,
+                            });
+                            // Post a diagnostic comment
+                            try {
+                                await this.client.createComment(issueId, `⚠️ **Agent completed but work was not persisted.**\n\n` +
+                                    `The agent reported success but no PR was detected, and the worktree has ${incompleteCheck.details}.\n\n` +
+                                    `**Issue status was NOT promoted** to prevent lost work from advancing through the pipeline.\n\n` +
+                                    `The worktree has been preserved at \`${agent.worktreePath}\`. ` +
+                                    `To recover: cd into the worktree, commit, push, and create a PR manually.`);
+                            }
+                            catch {
+                                // Best-effort comment
+                            }
+                            // Do NOT set targetStatus — leave issue in current state
+                        }
+                        else {
+                            // No PR but worktree is clean — either no changes needed or agent cleaned up
+                            targetStatus = this.statusMappings.workTypeCompleteStatus[workType];
+                        }
+                    }
+                    else {
+                        targetStatus = this.statusMappings.workTypeCompleteStatus[workType];
+                    }
                 }
                 if (targetStatus) {
                     try {
@@ -2455,7 +2524,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             }
         }
         else {
-            // Direct Linear API - use AgentSession if available
+            // Direct issue tracker API - use session if available
             const session = this.agentSessions.get(agent.issueId);
             if (session) {
                 try {
@@ -2476,7 +2545,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
      */
     async postCompletionComment(issueId, sessionId, resultMessage, log) {
         // Build completion comments with multi-part splitting
-        const comments = buildCompletionComments(resultMessage, [], // No plan items to include (already shown via activities)
+        const comments = this.client.buildCompletionComments(resultMessage, [], // No plan items to include (already shown via activities)
         sessionId ?? null);
         log?.info('Posting completion comment', {
             parts: comments.length,
@@ -2591,7 +2660,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                 const { worktreePath, worktreeIdentifier } = this.createWorktree(issue.identifier, workType);
                 // Link dependencies from main repo into worktree
                 this.linkDependencies(worktreePath, issue.identifier);
-                const startStatus = WORK_TYPE_START_STATUS[workType];
+                const startStatus = this.statusMappings.workTypeStartStatus[workType];
                 // Update issue status based on work type if auto-transition is enabled
                 if (this.config.autoTransition && startStatus) {
                     await this.client.updateIssueStatus(issue.id, startStatus);
@@ -2638,41 +2707,53 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         const issue = await this.client.getIssue(issueIdOrIdentifier);
         const identifier = issue.identifier;
         const issueId = issue.id; // Use the actual UUID
-        const team = await issue.team;
-        const teamName = team?.key;
-        // Fetch labels for provider resolution
-        const issueLabels = await issue.labels();
-        const labelNames = issueLabels.nodes.map((l) => l.name);
+        const teamName = issue.teamName;
+        // Labels for provider resolution (pre-resolved by IssueTrackerClient)
+        const labelNames = issue.labels;
         // Resolve project name for path scoping in monorepos
         let projectName;
         if (this.projectPaths) {
-            const project = await issue.project;
-            projectName = project?.name;
+            projectName = issue.projectName;
         }
         console.log(`Processing single issue: ${identifier} (${issueId}) - ${issue.title}`);
         // Guard: skip work if the issue has moved to a terminal status since being queued
-        const currentState = await issue.state;
-        const currentStatus = currentState?.name;
-        if (currentStatus && TERMINAL_STATUSES.includes(currentStatus)) {
+        const currentStatus = issue.status;
+        if (currentStatus && this.statusMappings.terminalStatuses.includes(currentStatus)) {
             throw new Error(`Issue ${identifier} is in terminal status '${currentStatus}' — skipping ${workType ?? 'auto'} work. ` +
                 `The issue was likely accepted/canceled after being queued.`);
         }
         // Defense in depth: re-validate git remote before spawning (guards against long-running instances)
         if (this.config.repository) {
-            validateGitRemote(this.config.repository);
+            validateGitRemote(this.config.repository, this.gitRoot);
         }
         // Auto-detect work type from issue status if not provided
         // This must happen BEFORE creating worktree since path includes work type suffix
         let effectiveWorkType = workType;
         if (!effectiveWorkType) {
-            const state = await issue.state;
-            const statusName = state?.name ?? 'Backlog';
+            const statusName = issue.status ?? 'Backlog';
             effectiveWorkType = await this.detectWorkType(issueId, statusName);
         }
+        else {
+            // Re-validate: upgrade to coordination variant if this is a parent issue
+            // The caller may have a stale work type from before the session was queued
+            try {
+                const isParent = await this.client.isParentIssue(issueId);
+                if (isParent) {
+                    const upgraded = detectWorkType(issue.status ?? 'Backlog', isParent, this.statusMappings.statusToWorkType);
+                    if (upgraded !== effectiveWorkType) {
+                        console.log(`Upgrading work type from ${effectiveWorkType} to ${upgraded} (parent issue detected)`);
+                        effectiveWorkType = upgraded;
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`Failed to check parent status for coordination upgrade:`, err);
+            }
+        }
         // Create isolated worktree for the agent
         let worktreePath;
         let worktreeIdentifier;
-        if (WORK_TYPES_REQUIRING_WORKTREE.has(effectiveWorkType)) {
+        if (this.statusMappings.workTypesRequiringWorktree.has(effectiveWorkType)) {
             const wt = this.createWorktree(identifier, effectiveWorkType);
             worktreePath = wt.worktreePath;
             worktreeIdentifier = wt.worktreeIdentifier;
@@ -2704,7 +2785,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                 const effectiveSessionId = sessionId ?? recoveryCheck.state.linearSessionId ?? randomUUID();
                 console.log(`Resuming work on ${identifier} (recovery attempt ${updatedState?.recoveryAttempts ?? 1})`);
                 // Update status based on work type if auto-transition is enabled
-                const startStatus = WORK_TYPE_START_STATUS[recoveryWorkType];
+                const startStatus = this.statusMappings.workTypeStartStatus[recoveryWorkType];
                 if (this.config.autoTransition && startStatus) {
                     await this.client.updateIssueStatus(issueId, startStatus);
                     console.log(`Updated ${identifier} status to ${startStatus}`);
@@ -2727,7 +2808,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         }
         // No recovery needed - proceed with fresh spawn
         // Update status based on work type if auto-transition is enabled
-        const startStatus = WORK_TYPE_START_STATUS[effectiveWorkType];
+        const startStatus = this.statusMappings.workTypeStartStatus[effectiveWorkType];
         if (this.config.autoTransition && startStatus) {
             await this.client.updateIssueStatus(issueId, startStatus);
             console.log(`Updated ${identifier} status to ${startStatus}`);
@@ -2900,12 +2981,10 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             try {
                 const issue = await this.client.getIssue(issueId);
                 identifier = issue.identifier;
-                const issueTeam = await issue.team;
-                teamName = issueTeam?.key;
+                teamName = issue.teamName;
                 // Guard: skip work if the issue has moved to a terminal status since being queued
-                const currentState = await issue.state;
-                const currentStatus = currentState?.name;
-                if (currentStatus && TERMINAL_STATUSES.includes(currentStatus)) {
+                const currentStatus = issue.status;
+                if (currentStatus && this.statusMappings.terminalStatuses.includes(currentStatus)) {
                     console.log(`Issue ${identifier} is in terminal status '${currentStatus}' — skipping work`);
                     return {
                         forwarded: false,
@@ -2921,7 +3000,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                     workType = await this.detectWorkType(issue.id, statusName);
                 }
                 // Create isolated worktree for the agent
-                if (WORK_TYPES_REQUIRING_WORKTREE.has(workType)) {
+                if (this.statusMappings.workTypesRequiringWorktree.has(workType)) {
                     const result = this.createWorktree(identifier, workType);
                     worktreePath = result.worktreePath;
                     worktreeIdentifier = result.worktreeIdentifier;
@@ -2940,7 +3019,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         }
         // Check if worktree exists (only relevant for code work types)
         const effectiveWorkType = workType ?? 'development';
-        if (WORK_TYPES_REQUIRING_WORKTREE.has(effectiveWorkType) && worktreePath && !existsSync(worktreePath)) {
+        if (this.statusMappings.workTypesRequiringWorktree.has(effectiveWorkType) && worktreePath && !existsSync(worktreePath)) {
             try {
                 const result = this.createWorktree(identifier, effectiveWorkType);
                 worktreePath = result.worktreePath;
@@ -3056,7 +3135,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         // Use the work type to determine if we need to transition on start
         // Only certain work types trigger a start transition
         const effectiveWorkType = workType ?? 'development';
-        const startStatus = WORK_TYPE_START_STATUS[effectiveWorkType];
+        const startStatus = this.statusMappings.workTypeStartStatus[effectiveWorkType];
         if (this.config.autoTransition && startStatus) {
             try {
                 await this.client.updateIssueStatus(issueId, startStatus);
@@ -3168,9 +3247,8 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             });
         }
         else {
-            // Direct Linear API
-            const session = createAgentSession({
-                client: this.client.linearClient,
+            // Direct issue tracker API
+            const session = this.client.createSession({
                 issueId,
                 sessionId,
                 autoTransition: false,