@renseiai/agentfactory 0.8.13 → 0.8.15

package/dist/src/orchestrator/orchestrator.js

@@ -16,6 +16,7 @@ import { createSessionLogger } from './session-logger.js';
 import { ContextManager } from './context-manager.js';
 import { isSessionLoggingEnabled, getLogAnalysisConfig } from './log-config.js';
 import { parseWorkResult } from './parse-work-result.js';
+import { runBackstop, formatBackstopComment } from './session-backstop.js';
 import { createActivityEmitter } from './activity-emitter.js';
 import { createApiActivityEmitter } from './api-activity-emitter.js';
 import { createLogger } from '../logger.js';
@@ -303,7 +304,7 @@ function extractToolNameFromError(error) {
  * @param worktreePath - Path to the git worktree
  * @returns Check result with reason if incomplete work is found
  */
-function checkForIncompleteWork(worktreePath) {
+export function checkForIncompleteWork(worktreePath) {
     try {
         // Check for uncommitted changes (staged or unstaged)
         const statusOutput = execSync('git status --porcelain', {
@@ -358,15 +359,12 @@ function checkForIncompleteWork(worktreePath) {
                         encoding: 'utf-8',
                         timeout: 10000,
                     }).trim();
-                    try {
-                        execSync(`git ls-remote --heads origin ${currentBranch}`, {
-                            cwd: worktreePath,
-                            encoding: 'utf-8',
-                            timeout: 10000,
-                        });
-                        // Remote branch exists, no issue
-                    }
-                    catch {
+                    const remoteRef = execSync(`git ls-remote --heads origin ${currentBranch}`, {
+                        cwd: worktreePath,
+                        encoding: 'utf-8',
+                        timeout: 10000,
+                    }).trim();
+                    if (remoteRef.length === 0) {
                         // Remote branch doesn't exist - branch never pushed
                         return {
                             hasIncompleteWork: true,
@@ -391,7 +389,7 @@ function checkForIncompleteWork(worktreePath) {
         };
     }
 }
-function checkForPushedWorkWithoutPR(worktreePath) {
+export function checkForPushedWorkWithoutPR(worktreePath) {
     try {
         const currentBranch = execSync('git branch --show-current', {
             cwd: worktreePath,
@@ -840,6 +838,8 @@ export class AgentOrchestrator {
     // Session loggers per agent for verbose analysis logging
     sessionLoggers = new Map();
     contextManagers = new Map();
+    // Session output flags for completion contract validation (keyed by issueId)
+    sessionOutputFlags = new Map();
     // Template registry for configurable workflow prompts
     templateRegistry;
     // Allowlisted project names from .agentfactory/config.yaml
@@ -1287,6 +1287,38 @@ export class AgentOrchestrator {
                 return false;
             }
         }
+        // SAFETY GUARD 4: Preserved worktrees — save work as patch, then allow cleanup.
+        // Preserved worktrees contain uncommitted work from a previous agent session.
+        // A diagnostic comment was already posted to the issue when the worktree was
+        // preserved. Blocking all future agents on this branch indefinitely causes
+        // work stoppages, so we save a patch for manual recovery and allow cleanup.
+        const preservedMarker = resolve(conflictPath, '.agent', 'preserved.json');
+        if (existsSync(preservedMarker)) {
+            console.warn(`Preserved worktree detected at ${conflictPath}. ` +
+                `Saving incomplete work as patch before cleanup to unblock branch '${branchName}'.`);
+            try {
+                const patchDir = resolve(resolveWorktreePath(this.config.worktreePath, this.gitRoot), '.patches');
+                if (!existsSync(patchDir)) {
+                    mkdirSync(patchDir, { recursive: true });
+                }
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const patchName = `${branchName}-preserved-${timestamp}.patch`;
+                const patchPath = resolve(patchDir, patchName);
+                const diff = execSync('git diff HEAD', {
+                    cwd: conflictPath,
+                    encoding: 'utf-8',
+                    timeout: 10000,
+                });
+                if (diff.trim().length > 0) {
+                    writeFileSync(patchPath, diff);
+                    console.log(`Saved preserved worktree patch: ${patchPath}`);
+                }
+            }
+            catch (patchError) {
+                console.warn('Failed to save preserved worktree patch:', patchError instanceof Error ? patchError.message : String(patchError));
+            }
+            // Fall through to cleanup below (don't return false)
+        }
         // Check if the agent in the conflicting worktree is still alive
         const recoveryInfo = checkRecovery(conflictPath, {
             heartbeatTimeoutMs: getHeartbeatTimeoutFromEnv(),
@@ -1899,6 +1931,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                 buildCommand: perProject?.buildCommand ?? this.buildCommand,
                 testCommand: perProject?.testCommand ?? this.testCommand,
                 validateCommand: perProject?.validateCommand ?? this.validateCommand,
+                agentBugBacklog: process.env.AGENT_BUG_BACKLOG || undefined,
             };
             const rendered = this.templateRegistry.renderPrompt(workType, context);
             prompt = rendered ?? generatePromptForWorkType(identifier, workType);
@@ -2080,7 +2113,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
         }
         log.info('Starting agent via provider', { provider: spawnProviderName, source: providerSource, cwd: worktreePath ?? 'repo-root', workType, promptPreview: prompt.substring(0, 50) });
         // Create in-process tool servers from registered plugins
-        const mcpServers = spawnProviderName === 'claude'
+        const toolServers = spawnProviderName === 'claude'
             ? this.toolRegistry.createServers({ env, cwd: worktreePath ?? process.cwd() })
             : undefined;
         // Coordinators need significantly more turns than standard agents
@@ -2096,7 +2129,8 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             abortController,
             autonomous: true,
             sandboxEnabled: this.config.sandboxEnabled,
-            mcpServers,
+            mcpServers: toolServers?.servers,
+            mcpToolNames: toolServers?.toolNames,
             maxTurns,
             onProcessSpawned: (pid) => {
                 agent.pid = pid;
@@ -2213,6 +2247,43 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                     }
                 }
             }
+            // --- Session Backstop: Validate completion contract and recover missing outputs ---
+            if (agent.status === 'completed') {
+                const outputFlags = this.sessionOutputFlags.get(issueId);
+                const backstopCtx = {
+                    agent,
+                    commentPosted: outputFlags?.commentPosted ?? false,
+                    issueUpdated: outputFlags?.issueUpdated ?? false,
+                    subIssuesCreated: outputFlags?.subIssuesCreated ?? false,
+                };
+                const backstopResult = runBackstop(backstopCtx);
+                if (backstopResult.backstop.actions.length > 0) {
+                    log?.info('Session backstop ran', {
+                        actions: backstopResult.backstop.actions.map(a => `${a.field}:${a.success ? 'ok' : 'fail'}`),
+                        fullyRecovered: backstopResult.backstop.fullyRecovered,
+                        remainingGaps: backstopResult.backstop.remainingGaps,
+                    });
+                    // Post backstop diagnostic comment if there were actions taken or gaps remaining
+                    const backstopComment = formatBackstopComment(backstopResult);
+                    if (backstopComment) {
+                        try {
+                            await this.client.createComment(issueId, backstopComment);
+                        }
+                        catch {
+                            // Best-effort diagnostic comment
+                        }
+                    }
+                }
+                // If backstop recovered the PR URL, update the session
+                if (agent.pullRequestUrl && sessionId) {
+                    try {
+                        await this.updateSessionPullRequest(sessionId, agent.pullRequestUrl, agent);
+                    }
+                    catch {
+                        // Best-effort session update
+                    }
+                }
+            }
             // Update Linear status based on work type if auto-transition is enabled
             if (agent.status === 'completed' && this.config.autoTransition) {
                 const workType = agent.workType ?? 'development';
@@ -2271,22 +2342,14 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                         const incompleteCheck = checkForIncompleteWork(agent.worktreePath);
                         if (incompleteCheck.hasIncompleteWork) {
                             // Agent has uncommitted/unpushed changes — block promotion
+                            // The diagnostic comment is posted in the cleanup section AFTER the
+                            // worktree preservation is confirmed — not here, to avoid promising
+                            // preservation before it actually happens.
                             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 {
@@ -2411,6 +2474,34 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                             catch {
                                 // Best-effort - heartbeat will go stale naturally after timeout
                             }
+                            // Write a .preserved marker so branch conflict resolution knows not to
+                            // destroy this worktree. The marker includes context for diagnostics.
+                            try {
+                                const agentDir = resolve(agent.worktreePath, '.agent');
+                                if (!existsSync(agentDir)) {
+                                    mkdirSync(agentDir, { recursive: true });
+                                }
+                                writeFileSync(resolve(agentDir, 'preserved.json'), JSON.stringify({
+                                    preservedAt: new Date().toISOString(),
+                                    issueId,
+                                    reason: incompleteCheck.reason,
+                                    details: incompleteCheck.details,
+                                }, null, 2));
+                            }
+                            catch {
+                                // Best-effort - the shouldCleanup=false flag is the primary guard
+                            }
+                            // Post diagnostic comment NOW that preservation is confirmed
+                            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
+                            }
                         }
                         else {
                             // No PR but also no local changes - agent may not have made any changes
@@ -2496,6 +2587,23 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                         catch {
                             // Best-effort - heartbeat will go stale naturally after timeout
                         }
+                        // Write a .preserved marker so branch conflict resolution knows not to
+                        // destroy this worktree
+                        try {
+                            const agentDir = resolve(agent.worktreePath, '.agent');
+                            if (!existsSync(agentDir)) {
+                                mkdirSync(agentDir, { recursive: true });
+                            }
+                            writeFileSync(resolve(agentDir, 'preserved.json'), JSON.stringify({
+                                preservedAt: new Date().toISOString(),
+                                issueId,
+                                reason: incompleteCheck.reason,
+                                details: incompleteCheck.details,
+                            }, null, 2));
+                        }
+                        catch {
+                            // Best-effort - the shouldCleanup=false flag is the primary guard
+                        }
                     }
                 }
                 if (shouldCleanup && agent.worktreeIdentifier) {
@@ -2622,6 +2730,8 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
                 heartbeatWriter?.recordToolCall(event.toolName);
                 progressLogger?.logTool(event.toolName, event.input);
                 sessionLogger?.logToolUse(event.toolName, event.input);
+                // Track session output signals for completion contract validation
+                this.trackSessionOutputSignal(issueId, event.toolName, event.input);
                 // Intercept TodoWrite tool calls to persist todos
                 if (event.toolName === 'TodoWrite') {
                     try {
@@ -2789,6 +2899,45 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
     /**
      * Extract GitHub PR URL from text (typically from gh pr create output)
      */
+    /**
+     * Track session output signals from tool calls for completion contract validation.
+     * Detects when agents call Linear CLI or MCP tools that produce required outputs.
+     */
+    trackSessionOutputSignal(issueId, toolName, input) {
+        let flags = this.sessionOutputFlags.get(issueId);
+        if (!flags) {
+            flags = { commentPosted: false, issueUpdated: false, subIssuesCreated: false };
+            this.sessionOutputFlags.set(issueId, flags);
+        }
+        // Detect comment creation (CLI via Bash or MCP tool)
+        if (toolName === 'af_linear_create_comment' ||
+            toolName === 'mcp__af-linear__af_linear_create_comment') {
+            flags.commentPosted = true;
+        }
+        // Detect issue update (CLI via Bash or MCP tool)
+        if (toolName === 'af_linear_update_issue' ||
+            toolName === 'mcp__af-linear__af_linear_update_issue') {
+            flags.issueUpdated = true;
+        }
+        // Detect issue creation (CLI via Bash or MCP tool)
+        if (toolName === 'af_linear_create_issue' ||
+            toolName === 'mcp__af-linear__af_linear_create_issue') {
+            flags.subIssuesCreated = true;
+        }
+        // Detect Bash tool calls that invoke the Linear CLI
+        if (toolName === 'Bash') {
+            const command = typeof input?.command === 'string' ? input.command : '';
+            if (command.includes('af-linear create-comment') || command.includes('af-linear create_comment')) {
+                flags.commentPosted = true;
+            }
+            if (command.includes('af-linear update-issue') || command.includes('af-linear update_issue')) {
+                flags.issueUpdated = true;
+            }
+            if (command.includes('af-linear create-issue') || command.includes('af-linear create_issue')) {
+                flags.subIssuesCreated = true;
+            }
+        }
+    }
     extractPullRequestUrl(text) {
         // GitHub PR URL pattern: https://github.com/owner/repo/pull/123
         const prUrlPattern = /https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/g;
@@ -2924,6 +3073,8 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             progressLogger.stop();
             this.progressLoggers.delete(issueId);
         }
+        // Cleanup session output flags
+        this.sessionOutputFlags.delete(issueId);
         // Persist and cleanup context manager
         const contextManager = this.contextManagers.get(issueId);
         if (contextManager) {
@@ -3650,7 +3801,7 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             workType: workType ?? 'development',
         });
         // Create in-process tool servers from registered plugins
-        const mcpServers = spawnProviderName === 'claude'
+        const toolServers = spawnProviderName === 'claude'
             ? this.toolRegistry.createServers({ env, cwd: worktreePath ?? process.cwd() })
             : undefined;
         // Coordinators need significantly more turns than standard agents
@@ -3665,7 +3816,8 @@ ORCHESTRATOR_INSTALL=1 exec pnpm add "$@"
             abortController,
             autonomous: true,
             sandboxEnabled: this.config.sandboxEnabled,
-            mcpServers,
+            mcpServers: toolServers?.servers,
+            mcpToolNames: toolServers?.toolNames,
             maxTurns,
             onProcessSpawned: (pid) => {
                 agent.pid = pid;

package/dist/src/orchestrator/session-backstop.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Session Backstop
+ *
+ * Deterministic post-session recovery that runs after every agent session.
+ * Validates the session's outputs against the work type's completion contract,
+ * then takes backstop actions for any recoverable gaps.
+ *
+ * This is provider-agnostic — it operates on the worktree and GitHub API,
+ * not on the agent session. Every provider gets the same backstop.
+ *
+ * Architecture:
+ * 1. Collect session outputs (git state, PR detection, work result markers)
+ * 2. Validate against the completion contract
+ * 3. Run backstop actions for recoverable fields (push, create PR)
+ * 4. Return structured result for the orchestrator to act on
+ */
+import type { AgentProcess } from './types.js';
+import type { BackstopResult, CompletionContract, CompletionValidationResult, SessionOutputs } from './completion-contracts.js';
+/** Context needed to collect session outputs */
+export interface SessionContext {
+    agent: AgentProcess;
+    /** Whether the agent posted at least one comment to the issue */
+    commentPosted: boolean;
+    /** Whether the agent updated the issue description */
+    issueUpdated: boolean;
+    /** Whether the agent created sub-issues */
+    subIssuesCreated: boolean;
+}
+/**
+ * Collect structured outputs from the completed session.
+ * Inspects git state, agent process data, and tracked flags.
+ */
+export declare function collectSessionOutputs(ctx: SessionContext): SessionOutputs;
+/** Options for running the backstop */
+export interface BackstopOptions {
+    /** Skip destructive backstop actions (push, PR creation) — useful for dry-run */
+    dryRun?: boolean;
+    /** PR title template. {identifier} is replaced with the issue key */
+    prTitleTemplate?: string;
+    /** PR body template. {identifier} is replaced with the issue key */
+    prBodyTemplate?: string;
+}
+/**
+ * Run the post-session backstop for an agent.
+ *
+ * 1. Collects session outputs
+ * 2. Validates against completion contract
+ * 3. Runs backstop actions for recoverable gaps
+ * 4. Returns structured result
+ *
+ * This function is safe to call for any work type — it returns a no-op
+ * result for work types without contracts.
+ */
+export declare function runBackstop(ctx: SessionContext, options?: BackstopOptions): BackstopRunResult;
+/** Full result of a backstop run */
+export interface BackstopRunResult {
+    contract: CompletionContract | null;
+    outputs: SessionOutputs;
+    validation: CompletionValidationResult | null;
+    backstop: BackstopResult;
+    diagnosticMessage: string | null;
+}
+/**
+ * Format a backstop result into a diagnostic comment for the issue tracker.
+ */
+export declare function formatBackstopComment(result: BackstopRunResult): string | null;
+//# sourceMappingURL=session-backstop.d.ts.map

package/dist/src/orchestrator/session-backstop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-backstop.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/session-backstop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,KAAK,EAEV,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACf,MAAM,2BAA2B,CAAA;AAWlC,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAA;IACnB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAA;IACtB,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAA;IACrB,2CAA2C;IAC3C,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CA8BzE;AAMD,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,eAAe,GACxB,iBAAiB,CAkGnB;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACnC,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,0BAA0B,GAAG,IAAI,CAAA;IAC7C,QAAQ,EAAE,cAAc,CAAA;IACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAmOD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CA8C9E"}