oxe-cc 1.8.3 → 1.10.0

package/lib/runtime/scheduler/multi-agent-coordinator.d.ts

@@ -18,6 +18,7 @@ export interface CoordinationOptions {
     runId: string;
     onEvent?: SchedulerContext['onEvent'];
     heartbeatTimeoutMs?: number;
+    applyWorkspaceMerges?: boolean;
 }
 export interface ArbitrationRecord {
     work_item_id: string;
@@ -33,6 +34,42 @@ export interface MultiAgentOwnership {
     work_item_id: string;
     owner_agent_id: string;
 }
+export interface WorkspaceMergeRecord {
+    work_item_id: string;
+    agent_id: string;
+    workspace_id: string;
+    strategy: string;
+    isolation_level: 'shared' | 'isolated';
+    branch: string | null;
+    base_commit: string | null;
+    root_path: string | null;
+    mutation_scope: string[];
+    diff_paths: string[];
+    evidence_refs: string[];
+    evidence_count: number;
+    verify_status: 'pass' | 'fail' | 'partial';
+    status: 'ready' | 'merged' | 'blocked' | 'skipped';
+    blocker: string | null;
+    applied_paths: string[];
+    diff_summary: {
+        added: number;
+        modified: number;
+        missing: number;
+        paths: string[];
+    };
+    next_action: string | null;
+    recorded_at: string;
+}
+export interface WorkspaceMergeReport {
+    schema_version: 1;
+    run_id: string;
+    generated_at: string;
+    workspace_isolation: 'git_worktree';
+    merge_readiness: 'ready' | 'blocked' | 'partial';
+    arbitration_required: boolean;
+    blockers: string[];
+    records: WorkspaceMergeRecord[];
+}
 export interface MultiAgentStatusSnapshot {
     run_id: string;
     mode: CoordinationMode;
@@ -52,6 +89,10 @@ export interface MultiAgentStatusSnapshot {
         timed_out: boolean;
         reassigned_task_ids: string[];
     }>;
+    worktrees: WorkspaceMergeRecord[];
+    workspace_merge: WorkspaceMergeReport;
+    merge_blockers: string[];
+    arbitration_required: boolean;
     orphan_reassignments: Array<{
         from_agent_id: string;
         to_agent_id: string;
@@ -78,6 +119,10 @@ export interface MultiAgentOperationalSummary {
     orphan_reassignment_count: number;
     timeout_count: number;
     participating_agents: string[];
+    workspace_isolation: 'git_worktree';
+    merge_readiness: WorkspaceMergeReport['merge_readiness'];
+    arbitration_required: boolean;
+    merge_blocker_count: number;
     health: 'healthy' | 'degraded';
     updated_at: string;
 }
@@ -94,6 +139,7 @@ export interface CoordinationResult {
     }>;
     handoffs?: CooperativeHandoff[];
     arbitration_results?: ArbitrationRecord[];
+    workspace_merge_report?: WorkspaceMergeReport;
     state?: MultiAgentStatusSnapshot;
     summary?: MultiAgentOperationalSummary;
 }
@@ -102,5 +148,7 @@ export declare class MultiAgentCoordinator {
 }
 export declare function multiAgentStatePath(projectRoot: string, runId: string): string;
 export declare function multiAgentSummaryPath(projectRoot: string, runId: string): string;
+export declare function workspaceMergeReportPath(projectRoot: string, runId: string): string;
 export declare function loadMultiAgentState(projectRoot: string, runId: string): MultiAgentStatusSnapshot | null;
 export declare function loadMultiAgentSummary(projectRoot: string, runId: string): MultiAgentOperationalSummary | null;
+export declare function loadWorkspaceMergeReport(projectRoot: string, runId: string): WorkspaceMergeReport | null;

package/lib/runtime/scheduler/multi-agent-coordinator.js

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultiAgentCoordinator = void 0;
 exports.multiAgentStatePath = multiAgentStatePath;
 exports.multiAgentSummaryPath = multiAgentSummaryPath;
+exports.workspaceMergeReportPath = workspaceMergeReportPath;
 exports.loadMultiAgentState = loadMultiAgentState;
 exports.loadMultiAgentSummary = loadMultiAgentSummary;
+exports.loadWorkspaceMergeReport = loadWorkspaceMergeReport;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const bus_1 = require("../events/bus");
@@ -19,11 +21,12 @@ function ensureRunDir(projectRoot, runId) {
     fs_1.default.mkdirSync(dir, { recursive: true });
     return dir;
 }
-function persistMultiAgentArtifacts(projectRoot, runId, state, handoffs = [], arbitrationResults = []) {
+function persistMultiAgentArtifacts(projectRoot, runId, state, handoffs = [], arbitrationResults = [], workspaceMergeReport = emptyWorkspaceMergeReport(runId)) {
     const runDir = ensureRunDir(projectRoot, runId);
     fs_1.default.writeFileSync(path_1.default.join(runDir, 'multi-agent-state.json'), JSON.stringify(state, null, 2), 'utf8');
     fs_1.default.writeFileSync(path_1.default.join(runDir, 'handoffs.json'), JSON.stringify(handoffs, null, 2), 'utf8');
     fs_1.default.writeFileSync(path_1.default.join(runDir, 'arbitration-results.json'), JSON.stringify(arbitrationResults, null, 2), 'utf8');
+    fs_1.default.writeFileSync(path_1.default.join(runDir, 'workspace-merge-report.json'), JSON.stringify(workspaceMergeReport, null, 2), 'utf8');
     const summary = {
         run_id: state.run_id,
         mode: state.mode,
@@ -38,6 +41,10 @@ function persistMultiAgentArtifacts(projectRoot, runId, state, handoffs = [], ar
         orphan_reassignment_count: state.orphan_reassignments.length,
         timeout_count: state.timed_out_agents.length,
         participating_agents: state.agent_results.map((entry) => entry.agent_id),
+        workspace_isolation: 'git_worktree',
+        merge_readiness: workspaceMergeReport.merge_readiness,
+        arbitration_required: workspaceMergeReport.arbitration_required,
+        merge_blocker_count: workspaceMergeReport.blockers.length,
         health: state.timed_out_agents.length > 0 || state.failed.length > 0 ? 'degraded' : 'healthy',
         updated_at: state.updated_at,
     };
@@ -62,7 +69,7 @@ function buildOwnership(agents, partitions) {
     }
     return ownership;
 }
-function makeState(mode, runId, agents, partitions, agentResults, completed, failed, blocked, orphanReassignments, timedOutAgents) {
+function makeState(mode, runId, agents, partitions, agentResults, completed, failed, blocked, orphanReassignments, timedOutAgents, workspaceMergeReport = emptyWorkspaceMergeReport(runId)) {
     return {
         run_id: runId,
         mode,
@@ -85,13 +92,173 @@ function makeState(mode, runId, agents, partitions, agentResults, completed, fai
                 reassigned_task_ids: result?.reassigned_task_ids ?? [],
             };
         }),
+        worktrees: workspaceMergeReport.records,
+        workspace_merge: workspaceMergeReport,
+        merge_blockers: workspaceMergeReport.blockers,
+        arbitration_required: workspaceMergeReport.arbitration_required,
         orphan_reassignments: orphanReassignments,
         timed_out_agents: timedOutAgents,
         updated_at: new Date().toISOString(),
     };
 }
+function emptyWorkspaceMergeReport(runId) {
+    return {
+        schema_version: 1,
+        run_id: runId,
+        generated_at: new Date().toISOString(),
+        workspace_isolation: 'git_worktree',
+        merge_readiness: 'ready',
+        arbitration_required: false,
+        blockers: [],
+        records: [],
+    };
+}
+function ensureGitWorktreeLease(agent, lease) {
+    if (lease.isolation_level !== 'isolated' || lease.strategy !== 'git_worktree') {
+        throw new Error(`Multi-agent real requires git_worktree isolated workspace. Agent ${agent.id} received ${lease.strategy}/${lease.isolation_level}.`);
+    }
+}
+function mutationScopeOf(node) {
+    return Array.isArray(node?.mutation_scope) ? node.mutation_scope.map(String).filter(Boolean) : [];
+}
+function createMergeRecord(agent, node, lease, result) {
+    const evidenceRefs = Array.isArray(result?.evidence) ? result.evidence.map(String).filter(Boolean) : [];
+    const scope = mutationScopeOf(node);
+    return {
+        work_item_id: node.id,
+        agent_id: agent.id,
+        workspace_id: lease.workspace_id,
+        strategy: lease.strategy,
+        isolation_level: lease.isolation_level,
+        branch: lease.branch ?? null,
+        base_commit: lease.base_commit ?? null,
+        root_path: lease.root_path ?? null,
+        mutation_scope: scope,
+        diff_paths: scope,
+        evidence_refs: evidenceRefs,
+        evidence_count: evidenceRefs.length,
+        verify_status: result ? (result.success ? 'pass' : 'fail') : 'partial',
+        status: result ? (result.success ? 'ready' : 'blocked') : 'ready',
+        blocker: result && !result.success ? `verify_failed:${result.failure_class}` : null,
+        applied_paths: [],
+        diff_summary: { added: 0, modified: 0, missing: 0, paths: scope },
+        next_action: result && !result.success ? 'Corrija a falha de verify/evidence antes de aplicar merge do workspace.' : null,
+        recorded_at: new Date().toISOString(),
+    };
+}
+function enrichMergeRecordWithResult(record, result) {
+    if (!result)
+        return record;
+    const evidenceRefs = Array.isArray(result.evidence) ? result.evidence.map(String).filter(Boolean) : [];
+    return {
+        ...record,
+        evidence_refs: evidenceRefs,
+        evidence_count: evidenceRefs.length,
+        verify_status: result.success ? 'pass' : 'fail',
+        status: result.success ? 'ready' : 'blocked',
+        blocker: result.success ? null : `verify_failed:${result.failure_class}`,
+        next_action: result.success ? null : 'Corrija a falha de verify/evidence antes de aplicar merge do workspace.',
+        recorded_at: new Date().toISOString(),
+    };
+}
+function buildWorkspaceMergeReport(runId, records, extraBlockers = [], arbitrationRequired = false) {
+    const blockers = [
+        ...extraBlockers,
+        ...records.filter((record) => record.status === 'blocked' && record.blocker).map((record) => `${record.work_item_id}:${record.blocker}`),
+    ];
+    return {
+        schema_version: 1,
+        run_id: runId,
+        generated_at: new Date().toISOString(),
+        workspace_isolation: 'git_worktree',
+        merge_readiness: blockers.length > 0 ? 'blocked' : records.some((record) => record.status === 'ready') ? 'partial' : 'ready',
+        arbitration_required: arbitrationRequired,
+        blockers,
+        records,
+    };
+}
+function detectMutationConflicts(graph, agents, partitions) {
+    const owners = new Map();
+    const conflicts = [];
+    for (let idx = 0; idx < agents.length; idx += 1) {
+        for (const nodeId of partitions[idx] ?? []) {
+            const node = graph.nodes.get(nodeId);
+            for (const scope of mutationScopeOf(node)) {
+                const previous = owners.get(scope);
+                if (previous && previous !== agents[idx].id) {
+                    conflicts.push(`mutation_scope_overlap:${scope}:${previous}:${agents[idx].id}`);
+                }
+                else {
+                    owners.set(scope, agents[idx].id);
+                }
+            }
+        }
+    }
+    return conflicts;
+}
+function applyWorkspaceRecord(projectRoot, record) {
+    if (!record.root_path || record.status !== 'ready')
+        return record;
+    const appliedPaths = [];
+    const summary = { added: 0, modified: 0, missing: 0, paths: [...record.mutation_scope] };
+    for (const relativePath of record.mutation_scope) {
+        const source = path_1.default.join(record.root_path, relativePath);
+        const target = path_1.default.join(projectRoot, relativePath);
+        if (!fs_1.default.existsSync(source) || fs_1.default.statSync(source).isDirectory()) {
+            summary.missing += 1;
+            return {
+                ...record,
+                status: 'blocked',
+                blocker: `missing_output:${relativePath}`,
+                diff_summary: summary,
+                next_action: `Materialize o arquivo esperado ${relativePath} no worktree do agente antes do merge.`,
+            };
+        }
+        if (fs_1.default.existsSync(target))
+            summary.modified += 1;
+        else
+            summary.added += 1;
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+        fs_1.default.copyFileSync(source, target);
+        appliedPaths.push(relativePath);
+    }
+    return {
+        ...record,
+        status: 'merged',
+        blocker: null,
+        applied_paths: appliedPaths,
+        diff_summary: summary,
+        next_action: null,
+    };
+}
+function createTrackingWorkspaceManager(base, agent, graph, records) {
+    const leases = new Map();
+    return {
+        isolation_level: base.isolation_level,
+        allocate: async (req) => {
+            const lease = await base.allocate(req);
+            ensureGitWorktreeLease(agent, lease);
+            leases.set(lease.workspace_id, lease);
+            const node = graph.nodes.get(req.work_item_id);
+            if (node)
+                records.push(createMergeRecord(agent, node, lease));
+            return lease;
+        },
+        snapshot: (id) => base.snapshot(id),
+        reset: (id, snapRef) => base.reset(id, snapRef),
+        dispose: async () => {
+            // Scheduler calls dispose before the coordinator can reconcile diffs.
+            // Defer real cleanup until the merge report has been produced.
+        },
+        disposeDeferred: async () => {
+            await Promise.all([...leases.keys()].map((id) => base.dispose(id).catch(() => { })));
+            leases.clear();
+        },
+    };
+}
 async function runGraphForAgent(graph, nodeIds, agent, idx, opts, heartbeatTimeoutMs) {
     const subGraph = subGraphFor(graph, nodeIds);
+    const workspaceRecords = [];
     if (subGraph.nodes.size === 0) {
         return {
             agent_id: agent.id,
@@ -100,20 +267,32 @@ async function runGraphForAgent(graph, nodeIds, agent, idx, opts, heartbeatTimeo
             timed_out: false,
             assigned_task_ids: nodeIds,
             reassigned_task_ids: [],
+            workspace_records: workspaceRecords,
+            cleanup: async () => { },
         };
     }
+    const trackingWorkspaceManager = createTrackingWorkspaceManager(agent.workspaceManager, agent, graph, workspaceRecords);
+    const taskResults = new Map();
+    const trackingExecutor = {
+        execute: async (node, lease, runId, attemptNumber) => {
+            const result = await agent.executor.execute(node, lease, runId, attemptNumber);
+            taskResults.set(node.id, result);
+            return result;
+        },
+    };
     const ctx = {
         projectRoot: opts.projectRoot,
         sessionId: opts.sessionId,
         runId: `${opts.runId}-agent${idx}`,
-        executor: agent.executor,
-        workspaceManager: agent.workspaceManager,
+        executor: trackingExecutor,
+        workspaceManager: trackingWorkspaceManager,
         onEvent: opts.onEvent,
     };
     const scheduler = new scheduler_1.Scheduler();
     const work = scheduler.run(subGraph, ctx);
     if (!heartbeatTimeoutMs || heartbeatTimeoutMs <= 0) {
         const result = await work;
+        const reconciledRecords = workspaceRecords.map((record) => enrichMergeRecordWithResult(record, taskResults.get(record.work_item_id)));
         return {
             agent_id: agent.id,
             completed: result.completed,
@@ -121,6 +300,8 @@ async function runGraphForAgent(graph, nodeIds, agent, idx, opts, heartbeatTimeo
             timed_out: false,
             assigned_task_ids: nodeIds,
             reassigned_task_ids: [],
+            workspace_records: reconciledRecords,
+            cleanup: () => trackingWorkspaceManager.disposeDeferred(),
         };
     }
     let timer = null;
@@ -140,9 +321,12 @@ async function runGraphForAgent(graph, nodeIds, agent, idx, opts, heartbeatTimeo
             timed_out: true,
             assigned_task_ids: nodeIds,
             reassigned_task_ids: [],
+            workspace_records: workspaceRecords,
+            cleanup: () => trackingWorkspaceManager.disposeDeferred(),
         };
     }
     const result = raced.result;
+    const reconciledRecords = workspaceRecords.map((record) => enrichMergeRecordWithResult(record, taskResults.get(record.work_item_id)));
     return {
         agent_id: agent.id,
         completed: result.completed,
@@ -150,6 +334,8 @@ async function runGraphForAgent(graph, nodeIds, agent, idx, opts, heartbeatTimeo
         timed_out: false,
         assigned_task_ids: nodeIds,
         reassigned_task_ids: [],
+        workspace_records: reconciledRecords,
+        cleanup: () => trackingWorkspaceManager.disposeDeferred(),
     };
 }
 // ─── Parallel mode ───────────────────────────────────────────────────────────
@@ -164,6 +350,30 @@ async function runParallel(graph, opts) {
             partitions[index % agents.length].push(id);
         });
     }
+    const mutationConflicts = detectMutationConflicts(graph, agents, partitions);
+    if (mutationConflicts.length > 0) {
+        const blocked = mutationConflicts;
+        const workspaceMergeReport = buildWorkspaceMergeReport(runId, [], blocked);
+        const state = makeState('parallel', runId, agents, partitions, [], [], [], blocked, [], [], workspaceMergeReport);
+        persistMultiAgentArtifacts(projectRoot, runId, state, [], [], workspaceMergeReport);
+        (0, bus_1.appendEvent)(projectRoot, sessionId, {
+            type: 'WorkItemBlocked',
+            run_id: runId,
+            payload: { mode: 'parallel', blockers: blocked },
+        });
+        return {
+            mode: 'parallel',
+            run_id: runId,
+            completed: [],
+            failed: [],
+            blocked,
+            agent_results: [],
+            arbitration_results: [],
+            workspace_merge_report: workspaceMergeReport,
+            state,
+            summary: loadMultiAgentSummary(projectRoot, runId) || undefined,
+        };
+    }
     const registry = new agent_registry_1.AgentRegistry(heartbeatTimeoutMs == null ? 30000 : heartbeatTimeoutMs);
     agents.forEach((agent, idx) => {
         registry.register(agent.id, agent.executor, agent.workspaceManager, partitions[idx] ?? []);
@@ -201,7 +411,13 @@ async function runParallel(graph, opts) {
         const rerun = await runGraphForAgent(graph, timedOut.assigned_task_ids, agents[fallbackIdx], fallbackIdx, opts, null);
         fallback.completed.push(...rerun.completed);
         fallback.failed.push(...rerun.failed);
+        fallback.workspace_records.push(...rerun.workspace_records);
         fallback.reassigned_task_ids.push(...timedOut.assigned_task_ids);
+        const previousCleanup = fallback.cleanup;
+        fallback.cleanup = async () => {
+            await previousCleanup?.();
+            await rerun.cleanup?.();
+        };
         partitions[fallbackIdx] = [...partitions[fallbackIdx], ...timedOut.assigned_task_ids];
         partitions[timeoutIdx] = [];
         orphanReassignments.push({
@@ -212,8 +428,14 @@ async function runParallel(graph, opts) {
     }
     const completed = Array.from(new Set(agentResults.flatMap((result) => result.completed)));
     const failed = Array.from(new Set(agentResults.flatMap((result) => result.failed)));
-    const state = makeState('parallel', runId, agents, partitions, agentResults, completed, failed, blocked, orphanReassignments, timedOutAgents);
-    persistMultiAgentArtifacts(projectRoot, runId, state);
+    const rawRecords = agentResults.flatMap((result) => result.workspace_records || []);
+    const mergedRecords = opts.applyWorkspaceMerges
+        ? rawRecords.map((record) => applyWorkspaceRecord(projectRoot, record))
+        : rawRecords;
+    await Promise.all(agentResults.map((result) => result.cleanup?.().catch(() => { })));
+    const workspaceMergeReport = buildWorkspaceMergeReport(runId, mergedRecords, blocked);
+    const state = makeState('parallel', runId, agents, partitions, agentResults, completed, failed, blocked, orphanReassignments, timedOutAgents, workspaceMergeReport);
+    persistMultiAgentArtifacts(projectRoot, runId, state, [], [], workspaceMergeReport);
     (0, bus_1.appendEvent)(projectRoot, sessionId, {
         type: 'RunCompleted',
         run_id: runId,
@@ -227,6 +449,7 @@ async function runParallel(graph, opts) {
         blocked,
         agent_results: agentResults,
         arbitration_results: [],
+        workspace_merge_report: workspaceMergeReport,
         state,
         summary: loadMultiAgentSummary(projectRoot, runId) || undefined,
     };
@@ -248,10 +471,11 @@ async function runCompetitive(graph, opts) {
     const failed = [];
     const blocked = [];
     const arbitrationResults = [];
+    const workspaceRecords = [];
     for (const wave of graph.waves) {
         for (const nodeId of wave.node_ids) {
             const node = graph.nodes.get(nodeId);
-            const result = await competeTwoAgents(nodeId, node, agentA, agentB, opts, arbitrationResults);
+            const result = await competeTwoAgents(nodeId, node, agentA, agentB, opts, arbitrationResults, workspaceRecords);
             if (result.success)
                 completed.push(nodeId);
             else
@@ -263,11 +487,12 @@ async function runCompetitive(graph, opts) {
             break;
     }
     const partitions = [Array.from(graph.nodes.keys()), Array.from(graph.nodes.keys())];
+    const workspaceMergeReport = buildWorkspaceMergeReport(runId, workspaceRecords, blocked, true);
     const state = makeState('competitive', runId, opts.agents, partitions, [
         { agent_id: agentA.id, completed, failed, timed_out: false, reassigned_task_ids: [] },
         { agent_id: agentB.id, completed: [], failed: [], timed_out: false, reassigned_task_ids: [] },
-    ], completed, failed, blocked, [], []);
-    persistMultiAgentArtifacts(projectRoot, runId, state, [], arbitrationResults);
+    ], completed, failed, blocked, [], [], workspaceMergeReport);
+    persistMultiAgentArtifacts(projectRoot, runId, state, [], arbitrationResults, workspaceMergeReport);
     (0, bus_1.appendEvent)(projectRoot, sessionId, {
         type: 'RunCompleted',
         run_id: runId,
@@ -284,18 +509,21 @@ async function runCompetitive(graph, opts) {
             { agent_id: agentB.id, completed: [], failed: [] },
         ],
         arbitration_results: arbitrationResults,
+        workspace_merge_report: workspaceMergeReport,
         state,
         summary: loadMultiAgentSummary(projectRoot, runId) || undefined,
     };
 }
-async function competeTwoAgents(nodeId, node, agentA, agentB, opts, arbitrationResults) {
+async function competeTwoAgents(nodeId, node, agentA, agentB, opts, arbitrationResults, workspaceRecords) {
     const { projectRoot, sessionId, runId } = opts;
     const allocA = await agentA.workspaceManager.allocate({
         work_item_id: nodeId, attempt_number: 1, strategy: node.workspace_strategy, mutation_scope: node.mutation_scope,
     });
+    ensureGitWorktreeLease(agentA, allocA);
     const allocB = await agentB.workspaceManager.allocate({
         work_item_id: nodeId, attempt_number: 1, strategy: node.workspace_strategy, mutation_scope: node.mutation_scope,
     });
+    ensureGitWorktreeLease(agentB, allocB);
     (0, bus_1.appendEvent)(projectRoot, sessionId, {
         type: 'AttemptStarted',
         run_id: runId,
@@ -310,12 +538,23 @@ async function competeTwoAgents(nodeId, node, agentA, agentB, opts, arbitrationR
             success: false, failure_class: 'env', evidence: [], output: String(error),
         })),
     ]);
+    const candidates = [
+        { agent: agentA, alloc: allocA, result: resultA },
+        { agent: agentB, alloc: allocB, result: resultB },
+    ].sort((left, right) => {
+        const leftScore = (left.result.success ? 10000 : 0) + left.result.evidence.length * 100 - String(left.result.output || '').length;
+        const rightScore = (right.result.success ? 10000 : 0) + right.result.evidence.length * 100 - String(right.result.output || '').length;
+        return rightScore - leftScore;
+    });
+    const winnerCandidate = candidates[0];
+    const winner = winnerCandidate.result;
+    const winnerAgentId = winnerCandidate.agent.id;
+    const winnerRecord = createMergeRecord(winnerCandidate.agent, node, winnerCandidate.alloc, winner);
+    workspaceRecords.push(opts.applyWorkspaceMerges ? applyWorkspaceRecord(projectRoot, winnerRecord) : winnerRecord);
     await Promise.all([
         agentA.workspaceManager.dispose(allocA.workspace_id).catch(() => { }),
         agentB.workspaceManager.dispose(allocB.workspace_id).catch(() => { }),
     ]);
-    const winner = resultA.success ? resultA : resultB.success ? resultB : resultA;
-    const winnerAgentId = resultA.success ? agentA.id : resultB.success ? agentB.id : agentA.id;
     arbitrationResults.push({
         work_item_id: nodeId,
         mode: 'competitive',
@@ -343,6 +582,7 @@ async function runCooperative(graph, opts) {
     const [planner, executor] = opts.agents;
     const { projectRoot, sessionId, runId } = opts;
     const handoffs = [];
+    const workspaceRecords = [];
     (0, bus_1.appendEvent)(projectRoot, sessionId, {
         type: 'RunStarted',
         run_id: runId,
@@ -360,6 +600,7 @@ async function runCooperative(graph, opts) {
                 strategy: node.workspace_strategy,
                 mutation_scope: node.mutation_scope,
             });
+            ensureGitWorktreeLease(planner, planAlloc);
             await planner.workspaceManager.dispose(planAlloc.workspace_id).catch(() => { });
             const handoff = (0, agent_roles_1.buildHandoff)({
                 from_agent_id: planner.id,
@@ -382,6 +623,7 @@ async function runCooperative(graph, opts) {
                 strategy: node.workspace_strategy,
                 mutation_scope: node.mutation_scope,
             });
+            ensureGitWorktreeLease(executor, execAlloc);
             let result;
             try {
                 result = await executor.executor.execute(node, execAlloc, runId, 1);
@@ -389,6 +631,8 @@ async function runCooperative(graph, opts) {
             catch (error) {
                 result = { success: false, failure_class: 'env', evidence: [], output: String(error) };
             }
+            const mergeRecord = createMergeRecord(executor, node, execAlloc, result);
+            workspaceRecords.push(opts.applyWorkspaceMerges ? applyWorkspaceRecord(projectRoot, mergeRecord) : mergeRecord);
             await executor.workspaceManager.dispose(execAlloc.workspace_id).catch(() => { });
             if (result.success) {
                 completed.push(nodeId);
@@ -404,11 +648,12 @@ async function runCooperative(graph, opts) {
             break;
     }
     const partitions = [Array.from(graph.nodes.keys()), Array.from(graph.nodes.keys())];
+    const workspaceMergeReport = buildWorkspaceMergeReport(runId, workspaceRecords, blocked);
     const state = makeState('cooperative', runId, opts.agents, partitions, [
         { agent_id: planner.id, completed: [], failed: [], timed_out: false, reassigned_task_ids: [] },
         { agent_id: executor.id, completed, failed, timed_out: false, reassigned_task_ids: [] },
-    ], completed, failed, blocked, [], []);
-    persistMultiAgentArtifacts(projectRoot, runId, state, handoffs, []);
+    ], completed, failed, blocked, [], [], workspaceMergeReport);
+    persistMultiAgentArtifacts(projectRoot, runId, state, handoffs, [], workspaceMergeReport);
     (0, bus_1.appendEvent)(projectRoot, sessionId, {
         type: 'RunCompleted',
         run_id: runId,
@@ -426,6 +671,7 @@ async function runCooperative(graph, opts) {
         ],
         handoffs,
         arbitration_results: [],
+        workspace_merge_report: workspaceMergeReport,
         state,
         summary: loadMultiAgentSummary(projectRoot, runId) || undefined,
     };
@@ -449,6 +695,9 @@ function multiAgentStatePath(projectRoot, runId) {
 function multiAgentSummaryPath(projectRoot, runId) {
     return path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'multi-agent-summary.json');
 }
+function workspaceMergeReportPath(projectRoot, runId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'workspace-merge-report.json');
+}
 function loadMultiAgentState(projectRoot, runId) {
     const statePath = multiAgentStatePath(projectRoot, runId);
     if (!fs_1.default.existsSync(statePath))
@@ -471,6 +720,17 @@ function loadMultiAgentSummary(projectRoot, runId) {
         return null;
     }
 }
+function loadWorkspaceMergeReport(projectRoot, runId) {
+    const reportPath = workspaceMergeReportPath(projectRoot, runId);
+    if (!fs_1.default.existsSync(reportPath))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(reportPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function subGraphFor(graph, nodeIds) {
     const ids = new Set(nodeIds);

package/lib/runtime/workspace/strategies/git-worktree.js

@@ -15,13 +15,15 @@ class GitWorktreeManager {
         this.leases = new Map();
     }
     async allocate(req) {
-        const wsId = `ws-${req.work_item_id}-a${req.attempt_number}`;
-        const branch = `oxe/${req.work_item_id}-attempt${req.attempt_number}`;
+        const suffix = crypto_1.default.randomBytes(4).toString('hex');
+        const safeWorkItem = String(req.work_item_id).replace(/[^A-Za-z0-9._-]/g, '-');
+        const wsId = `ws-${safeWorkItem}-a${req.attempt_number}-${suffix}`;
+        const branch = `oxe/${safeWorkItem}-attempt${req.attempt_number}-${suffix}`;
         const worktreePath = path_1.default.join(this.projectRoot, '.oxe', 'workspaces', wsId);
-        const baseCommit = this.git(['rev-parse', 'HEAD']).trim();
+        const baseCommit = this.git(['rev-parse', 'HEAD'], undefined, 'git_worktree requires a git repository with at least one base commit').trim();
         fs_1.default.mkdirSync(path_1.default.dirname(worktreePath), { recursive: true });
         // Create worktree on a new branch starting from HEAD
-        this.git(['worktree', 'add', worktreePath, '-b', branch]);
+        this.git(['worktree', 'add', worktreePath, '-b', branch], undefined, 'failed to create git_worktree workspace');
         const lease = {
             workspace_id: wsId,
             strategy: 'git_worktree',
@@ -71,11 +73,18 @@ class GitWorktreeManager {
         }
         this.leases.delete(id);
     }
-    git(args, cwd) {
-        return (0, child_process_1.execFileSync)('git', args, {
-            cwd: cwd ?? this.projectRoot,
-            encoding: 'utf8',
-        });
+    git(args, cwd, message) {
+        try {
+            return (0, child_process_1.execFileSync)('git', args, {
+                cwd: cwd ?? this.projectRoot,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`${message || 'git command failed'}: git ${args.join(' ')} (${detail})`);
+        }
     }
 }
 exports.GitWorktreeManager = GitWorktreeManager;

package/oxe/templates/REFERENCE-ANCHORS.template.md

@@ -4,18 +4,23 @@
 
 <reference_anchors version="1" ready="false" status="not_ready">
   <anchor
-    id="RA-01"
-    task="T1"
-    critical="true"
-    status="resolved"
-    source_type="local"
+    id="RA-01"
+    task="T1"
+    critical="true"
+    status="resolved"
+    source_type="local"
     path=".oxe/investigations/externals/exemplo.txt"
+    visual_ref="not_applicable"
+    extraction_confidence="not_applicable"
+    reproducibility="local_file"
     snippet_ref="lines 10-30"
     source_ref="external-ref: exemplo">
     <relevance>Por que esta referência sustenta a tarefa.</relevance>
     <action>copy | adapt | consult</action>
     <summary>Resumo semântico curto do trecho relevante ou do contrato.</summary>
     <critical_fields>IDs, colunas, offsets, eventos ou contratos que não podem ser improvisados.</critical_fields>
+    <limitations>Limitações da referência. Para imagem/anexo visual, registrar se depende de inspeção do runtime hospedeiro.</limitations>
+    <derived_requirements>R-ID/A* derivados desta referência, quando aplicável.</derived_requirements>
   </anchor>
 </reference_anchors>
 
@@ -26,3 +31,5 @@
 - `path` deve ser reproduzível no workspace ou materializado em `.oxe/investigations/externals/`.
 - Referência solta em texto não é evidência. Se o path/range/snippet não puder ser materializado, marcar `status="missing"` e derrubar readiness.
 - Anchors podem ser locais, externos materializados, predecessor interno, contrato público, fixture ou decisão registrada.
+- Para imagens/anexos visuais, usar `source_type="visual_attachment|screenshot|mockup|image_description"` e ligar `visual_ref` a `VISUAL-INPUTS.md/json`.
+- Âncora visual crítica só pode ficar `resolved` quando a extração textual for suficiente para executar sem reabrir a imagem.