Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

refactor: split agent workspace preparation into named provisioning steps (#12957)

[._.]/ Adam Eivy5cdcd368e2b8
diff --git a/server/services/agentWorkspacePrep.js b/server/services/agentWorkspacePrep.js
index 9db532fc00..7e2436a875 100644
--- a/server/services/agentWorkspacePrep.js
+++ b/server/services/agentWorkspacePrep.js
@@ -12,8 +12,8 @@ import { isPrivateSecurityTask } from '../lib/privateSecurityPolicy.js';
* creation.
*
* Side effects that don't touch spawn-local state (creating a conflict task,
- * flipping the task to pending/blocked, creating worktrees, mutating
- * `task.metadata` with JIRA fields) happen inline. Outcomes that the caller
+ * flipping the task to pending/blocked, creating worktrees, recording JIRA
+ * fields on `task.metadata`) happen inline. Outcomes that the caller
* must finish are returned as a discriminated result so the caller can fire
* `cleanupOnError` + the matching `agent:deferred` / `agent:error` event:
*
@@ -551,7 +551,12 @@ export async function prepareAgentWorkspace({ agentId, task, onPrepared = result
return withCheckoutPublication(workspacePath, prepareAndRegister);
}
-async function prepareResolvedWorkspace({ agentId, task, workspacePath, resolvedApp, resolvedAppName, isReadOnly }) {
+/**
+ * Refuse a launch whose recovery target or remediation pin no longer matches the
+ * task, before any checkout is touched.
+ * @returns {Promise<object|null>} the blocked outcome, or null to proceed
+ */
+async function refuseUnsafeLaunchTarget({ task, workspacePath, isReadOnly }) {
const recoveryTarget = task.metadata?.cleanupReviewTarget;
if (recoveryTarget) {
const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');
@@ -568,48 +573,263 @@ async function prepareResolvedWorkspace({ agentId, task, workspacePath, resolved
|| !resolveTaskRemoteBranch(task.metadata))) {
return refusePinnedAttach(task, workspacePath, `Task ${task.id} has no valid reviewed head and branch; refusing an unpinned remediation workspace`);
}
+ return null;
+}
- let jiraTicket = null;
- let jiraBranchName = null;
- let worktreeInfo = null;
- // A relaunched claim keeps the `claim-*` directory the previous run cut.
- // Moving it (the ordinary adopt path) would rename it to `agent-<id>` and
- // break the claim prompt's own cleanup path. Use it where it sits, and skip
- // every later provisioner so a checked-out claim branch cannot fall through
- // to the shared checkout.
- const claimWorkspace = remediationPin !== null ? null : claimContinuationWorkspace({
+/**
+ * A relaunched claim keeps the `claim-*` directory the previous run cut. Moving
+ * it (the ordinary adopt path) would rename it to `agent-<id>` and break the
+ * claim prompt's own cleanup path, so it is used where it sits.
+ *
+ * The pointer is a cached answer, not authority: confirm the holder, the branch
+ * and the absence of another live owner NOW, and wait (bounded) when that cannot
+ * be established rather than entering someone's checkout.
+ *
+ * @returns {Promise<{ workspacePath: string, worktreeInfo: object }|object|null>}
+ * the claim checkout, a blocked outcome, or null when the task continues no claim
+ */
+async function admitClaimWorkspace({ task, agentId, workspacePath }) {
+ const claimWorkspace = claimContinuationWorkspace({
metadata: task.metadata,
pathExists: existsSync,
worktreesRoot: PATHS.worktrees,
});
- if (claimWorkspace) {
- // The pointer is a cached answer, not authority: confirm the holder, the
- // branch and the absence of another live owner NOW, and wait (bounded) when
- // that cannot be established rather than entering someone's checkout.
- const admission = await admitClaimContinuation({ task, agentId, sourceWorkspace: workspacePath, claimWorkspace });
- if (!admission.admit) {
- const attempt = (Number(task.metadata?.worktreeBusyAttempts) || 0) + 1;
- const detail = `The claim worktree for ${claimWorkspace.worktreeInfo.branchName} cannot be confirmed free (${admission.reason}); nothing in it was touched`;
- if (attempt <= WORKTREE_BUSY_MAX_ATTEMPTS) {
- emitLog('info', `🌳 ${detail}; retrying after a short cooldown (attempt ${attempt}/${WORKTREE_BUSY_MAX_ATTEMPTS})`, { taskId: task.id, branch: claimWorkspace.worktreeInfo.branchName, reason: admission.reason });
- await blockTask(task, `${detail}; retrying after a short cooldown`, 'worktree-busy', {
- cooldownUntil: new Date(Date.now() + WORKTREE_BUSY_COOLDOWN_MS).toISOString(),
- worktreeBusyAttempts: attempt,
- });
- return { outcome: 'blocked', reason: detail };
- }
- emitLog('warn', `🌳 ${detail}; giving up after ${WORKTREE_BUSY_MAX_ATTEMPTS} attempts`, { taskId: task.id, branch: claimWorkspace.worktreeInfo.branchName, reason: admission.reason });
- await blockTask(task, `${detail}. Resolve who owns the checkout, then re-run this task.`, 'worktree-failed');
- return { outcome: 'blocked', reason: detail };
+ if (!claimWorkspace) return null;
+ const { branchName } = claimWorkspace.worktreeInfo;
+ const admission = await admitClaimContinuation({ task, agentId, sourceWorkspace: workspacePath, claimWorkspace });
+ if (admission.admit) {
+ emitLog('info', `🌳 Agent ${agentId} is continuing the claim worktree ${branchName}`, {
+ agentId, taskId: task.id, worktreePath: claimWorkspace.workspacePath, branchName,
+ });
+ return { workspacePath: claimWorkspace.workspacePath, worktreeInfo: claimWorkspace.worktreeInfo };
+ }
+ const attempt = (Number(task.metadata?.worktreeBusyAttempts) || 0) + 1;
+ const detail = `The claim worktree for ${branchName} cannot be confirmed free (${admission.reason}); nothing in it was touched`;
+ if (attempt <= WORKTREE_BUSY_MAX_ATTEMPTS) {
+ emitLog('info', `🌳 ${detail}; retrying after a short cooldown (attempt ${attempt}/${WORKTREE_BUSY_MAX_ATTEMPTS})`, { taskId: task.id, branch: branchName, reason: admission.reason });
+ await blockTask(task, `${detail}; retrying after a short cooldown`, 'worktree-busy', {
+ cooldownUntil: new Date(Date.now() + WORKTREE_BUSY_COOLDOWN_MS).toISOString(),
+ worktreeBusyAttempts: attempt,
+ });
+ return { outcome: 'blocked', reason: detail };
+ }
+ emitLog('warn', `🌳 ${detail}; giving up after ${WORKTREE_BUSY_MAX_ATTEMPTS} attempts`, { taskId: task.id, branch: branchName, reason: admission.reason });
+ await blockTask(task, `${detail}. Resolve who owns the checkout, then re-run this task.`, 'worktree-failed');
+ return { outcome: 'blocked', reason: detail };
+}
+
+/**
+ * File a resolver task for the shared checkout that will not pull, and pause this
+ * task on a cooldown until it lands.
+ */
+async function deferForGitConflict({ task, workspacePath, resolvedAppName, pullResult }) {
+ emitLog('warn', `🔀 Git conflict in ${workspacePath} (branch: ${pullResult.branch}): ${pullResult.error}`, {
+ taskId: task.id, workspace: workspacePath, branch: pullResult.branch
+ });
+ const checkoutName = resolvedAppName || workspacePath;
+ // The description's first line is the duplicate key, so it stays stable
+ // across retries; the (varying) git error goes in the context.
+ await addTask({
+ description: `Resolve git conflict in ${checkoutName} on branch ${pullResult.branch}. `
+ + `The branch has diverged from origin and automatic rebase failed.`,
+ priority: 'HIGH',
+ app: task.metadata?.app || null,
+ metadata: { gitConflictResolution: true },
+ context: `Error: ${pullResult.error}\n`
+ + `This conflict is blocking task ${task.id}: "${task.description}". `
+ + `Resolve the conflict, commit, and push so the blocked task can proceed.`,
+ position: 'top'
+ }, 'internal').catch(err => {
+ emitLog('warn', `Failed to create conflict resolution task: ${err.message}`, { taskId: task.id });
+ });
+
+ // A timed pause, not `pending`: a pending task is re-dequeued within
+ // seconds and re-runs the same failing rebase in a hot loop until the
+ // resolver lands. The cooldown sweeper revives it.
+ await blockTask(task, `Git conflict in ${checkoutName} (branch ${pullResult.branch}); waiting for the resolver task`, 'git-conflict-wait', {
+ cooldownUntil: new Date(Date.now() + GIT_CONFLICT_COOLDOWN_MS).toISOString(),
+ });
+ return {
+ outcome: 'deferred',
+ reason: 'Git conflict blocks task — conflict resolution task created',
+ deferReason: 'git-conflict',
+ branch: pullResult.branch
+ };
+}
+
+/**
+ * Pull the shared checkout a task is about to run in.
+ * @returns {Promise<object|null>} the deferred outcome on an unresolvable conflict, else null
+ */
+async function pullSharedCheckout({ task, workspacePath, resolvedAppName, wantsWorktree }) {
+ // Isolated tasks fetch their base in createWorktree; never rebase the
+ // shared checkout as a side effect of preparing a separate workspace.
+ // The conflict-resolution task works on the very checkout that won't pull;
+ // gating it on a clean pull would defer it forever.
+ const pullResult = wantsWorktree ? { skipped: 'isolated-task' }
+ : isTruthyMeta(task.metadata?.gitConflictResolution) ? { skipped: 'git-conflict-resolver' }
+ : await git.ensureLatest(workspacePath).catch(err => {
+ emitLog('warn', `⚠️ Pre-task git pull failed for ${workspacePath}: ${err.message}`, { taskId: task.id, workspace: workspacePath });
+ return { success: false, error: err.message };
+ });
+
+ if (pullResult.skipped) {
+ emitLog('debug', `Pre-task git pull skipped: ${pullResult.skipped}`, { taskId: task.id, workspace: workspacePath });
+ } else if (pullResult.conflict) {
+ return deferForGitConflict({ task, workspacePath, resolvedAppName, pullResult });
+ } else if (pullResult.success && !pullResult.upToDate) {
+ emitLog('info', `📥 Pulled latest for ${resolvedAppName || 'workspace'} (branch: ${pullResult.branch})`, {
+ taskId: task.id, workspace: workspacePath, branch: pullResult.branch
+ });
+ } else if (!pullResult.success) {
+ emitLog('warn', `⚠️ Pre-task git pull error: ${pullResult.error}`, { taskId: task.id, workspace: workspacePath });
+ }
+ return null;
+}
+
+/**
+ * Create a JIRA ticket and its feature branch when the app has JIRA enabled and
+ * the task opted in. Writes nothing to the task: the fields the ticket adds to
+ * `task.metadata` are returned as `metadataPatch` for the caller to record.
+ *
+ * @returns {Promise<{ jiraTicket: object|null, jiraBranchName: string|null, metadataPatch: object|null }>}
+ * `jiraBranchName` is null when the branch could not be created, even with a ticket
+ */
+async function prepareJiraBranch({ task, workspacePath }) {
+ const none = { jiraTicket: null, jiraBranchName: null, metadataPatch: null };
+ if (!task.metadata?.createJiraTicket) return none;
+ const appData = await getAppDataForTask(task);
+ if (!appData?.jira?.enabled) return none;
+ const jiraTicket = await createJiraTicketForTask(task, appData);
+ if (!jiraTicket) return none;
+
+ const slug = (task.description || 'task')
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-|-$/g, '')
+ .substring(0, 40);
+ let jiraBranchName = `feature/${jiraTicket.ticketId}-${slug}`;
+
+ if (task.metadata?.app) {
+ await git.fetchOrigin(workspacePath).catch(() => {});
+ const { baseBranch: defaultBranch } = await git.getRepoBranches(workspacePath).catch(() => ({ baseBranch: null }));
+ if (defaultBranch) {
+ await git.checkout(workspacePath, defaultBranch).catch(() => {});
+ await execGit(['merge', '--ff-only', `origin/${defaultBranch}`], workspacePath).catch(err => { emitLog('warn', `Fast-forward merge of ${defaultBranch} failed: ${err.message}`, { taskId: task.id }); });
}
- workspacePath = claimWorkspace.workspacePath;
- worktreeInfo = claimWorkspace.worktreeInfo;
- emitLog('info', `🌳 Agent ${agentId} is continuing the claim worktree ${worktreeInfo.branchName}`, {
- agentId, taskId: task.id, worktreePath: workspacePath, branchName: worktreeInfo.branchName,
+ }
+
+ await git.createBranch(workspacePath, jiraBranchName)
+ // `checkout -b` off a LOCAL branch doesn't auto-track under git's default
+ // `branch.autoSetupMerge`, but a repo configured `always` records the base
+ // branch as this one's upstream — and a config-derived push
+ // (`git push <remote> HEAD:<merge>`) then lands the agent's work on the base
+ // branch instead of opening a PR (#4172). Verify before handing it over.
+ .then(() => enforceSafeBranchUpstream(workspacePath, jiraBranchName))
+ .then(() => {
+ emitLog('success', `Created feature branch ${jiraBranchName}`, { taskId: task.id, ticketId: jiraTicket.ticketId });
+ })
+ .catch(err => {
+ emitLog('warn', `Failed to create JIRA branch ${jiraBranchName}: ${err.message}`, { taskId: task.id });
+ jiraBranchName = null;
+ });
+
+ return {
+ jiraTicket,
+ jiraBranchName,
+ metadataPatch: {
+ jiraTicketId: jiraTicket.ticketId,
+ jiraTicketUrl: jiraTicket.ticketUrl,
+ jiraBranch: jiraBranchName,
+ jiraInstanceId: appData.jira.instanceId,
+ jiraCreatePR: appData.jira.createPR !== false
+ },
+ };
+}
+
+/**
+ * A feature-agent run works in that agent's persistent worktree instead of a
+ * fresh one.
+ * @returns {Promise<{ workspacePath: string, worktreeInfo: object }|null>}
+ */
+async function adoptFeatureAgentWorktree(task) {
+ if (!task.metadata?.featureAgentRun || !task.metadata?.featureAgentId) return null;
+ const { getFeatureAgent } = await import('./featureAgents.js');
+ const fa = await getFeatureAgent(task.metadata.featureAgentId).catch(() => null);
+ if (!fa) return null;
+ const faWorktreePath = join(PATHS.cos, 'feature-agents', fa.id, 'worktree');
+ if (!existsSync(faWorktreePath)) return null;
+ if (fa.git.autoMergeBase) {
+ const { mergeBaseIntoFeatureWorktree } = await import('./worktreeManager.js');
+ await mergeBaseIntoFeatureWorktree(fa.id, fa.git.baseBranch).catch(err => {
+ emitLog('warn', `🌳 Feature agent base merge failed: ${err.message}`, { featureAgentId: fa.id });
+ });
+ }
+ emitLog('info', `🌳 Feature agent ${fa.name} using persistent worktree: ${fa.git.branchName}`, {
+ featureAgentId: fa.id, worktreePath: faWorktreePath
+ });
+ return {
+ workspacePath: faWorktreePath,
+ worktreeInfo: {
+ worktreePath: faWorktreePath,
+ branchName: fa.git.branchName,
+ baseBranch: fa.git.baseBranch || 'main',
+ isPersistentWorktree: true
+ },
+ };
+}
+
+/**
+ * Cut a worktree for a shared-checkout task only when conflict detection finds
+ * another running agent in the same checkout. Creation failure keeps the task
+ * in the shared checkout.
+ * @returns {Promise<object|null>} the new worktree's info, or null to stay put
+ */
+async function provisionConflictWorktree({ agentId, task, workspacePath }) {
+ const { getAgents } = await import('./cos.js');
+ const runningAgents = (await getAgents()).filter(a => a.status === 'running');
+
+ const conflictResult = await detectConflicts(task, workspacePath, runningAgents).catch(err => {
+ emitLog('warn', `Conflict detection failed: ${err.message}`, { taskId: task.id });
+ return { hasConflict: false, recommendation: 'proceed' };
+ });
+
+ if (conflictResult.recommendation === 'proceed') {
+ emitLog('debug', `No conflicts for task ${task.id}, using shared workspace`, { taskId: task.id });
+ }
+ if (conflictResult.recommendation !== 'worktree') return null;
+
+ emitLog('info', `🌳 Conflict detected for task ${task.id}: ${conflictResult.reason} — creating worktree`, {
+ taskId: task.id,
+ conflictingAgents: conflictResult.conflictingAgents,
+ reason: conflictResult.reason
+ });
+ const worktreeInfo = await createWorktree(agentId, workspacePath, task.id, {
+ planId: task.metadata?.planId || undefined,
+ linkDependencies: resolveTaskHookType(task) !== 'dependency-updates',
+ }).catch(err => {
+ emitLog('warn', `🌳 Worktree creation failed, using shared workspace: ${err.message}`, { taskId: task.id });
+ return null;
+ });
+ if (worktreeInfo) {
+ emitLog('success', `🌳 Agent ${agentId} will work in worktree: ${worktreeInfo.branchName}`, {
+ agentId, worktreePath: worktreeInfo.worktreePath, branchName: worktreeInfo.branchName
});
}
- const explicitOpenPR = isTruthyMeta(task.metadata?.openPR);
- const explicitWorktree = isTruthyMeta(task.metadata?.useWorktree) || explicitOpenPR || remediationPin !== null;
+ return worktreeInfo;
+}
+
+/**
+ * Pick the checkout the agent runs in. The provisioning steps run in this fixed
+ * order and any refusal, deferral, continued claim or JIRA branch returns at
+ * once, so a later step never has to infer an earlier outcome from a flag.
+ */
+async function prepareResolvedWorkspace({ agentId, task, workspacePath: sourceWorkspace, resolvedApp, resolvedAppName, isReadOnly }) {
+ const refusal = await refuseUnsafeLaunchTarget({ task, workspacePath: sourceWorkspace, isReadOnly });
+ if (refusal) return refusal;
+
+ const remediationPin = resolveTaskPinnedHead(task.metadata);
+ const explicitWorktree = isTruthyMeta(task.metadata?.useWorktree) || isTruthyMeta(task.metadata?.openPR) || remediationPin !== null;
// A task pointed at an existing branch must run in a worktree whatever isolated
// the ORIGINAL run, because that is the only way to reach the work: the branch
// has to be checked out somewhere, and an adoptable tree has to be attached.
@@ -619,213 +839,56 @@ async function prepareResolvedWorkspace({ agentId, task, workspacePath, resolved
// detection returns `proceed` once the dead agent is gone) and silently
// abandons the work the pointer was recorded to save.
const existingBranch = resolveTaskTargetBranch(task.metadata);
- // Where that branch lives when the task points at a fork PR's head — read
- // here rather than inside the worktree layer, which has no forge client.
- const forkHead = resolveTaskForkHead(task.metadata);
const wantsWorktree = explicitWorktree || !!existingBranch;
+ const ready = ({ workspacePath, worktreeInfo, jiraTicket = null, jiraBranchName = null }) => {
+ // Announce the FINAL cwd, after any worktree reassignment, so the task log
+ // names the directory the agent actually runs in rather than the repo it was
+ // cut from (#3180).
+ emitLog('info', `📂 Agent workspace: ${workspacePath}`, { taskId: task.id, workspace: workspacePath });
+ return { outcome: 'ready', workspacePath, resolvedApp, resolvedAppName, worktreeInfo, jiraTicket, jiraBranchName, explicitWorktree };
+ };
- if (!isReadOnly && !claimWorkspace) {
- // Isolated tasks fetch their base in createWorktree; never rebase the
- // shared checkout as a side effect of preparing a separate workspace.
- // The conflict-resolution task works on the very checkout that won't pull;
- // gating it on a clean pull would defer it forever.
- const pullResult = wantsWorktree ? { skipped: 'isolated-task' }
- : isTruthyMeta(task.metadata?.gitConflictResolution) ? { skipped: 'git-conflict-resolver' }
- : await git.ensureLatest(workspacePath).catch(err => {
- emitLog('warn', `⚠️ Pre-task git pull failed for ${workspacePath}: ${err.message}`, { taskId: task.id, workspace: workspacePath });
- return { success: false, error: err.message };
- });
-
- if (pullResult.skipped) {
- emitLog('debug', `Pre-task git pull skipped: ${pullResult.skipped}`, { taskId: task.id, workspace: workspacePath });
- } else if (pullResult.conflict) {
- emitLog('warn', `🔀 Git conflict in ${workspacePath} (branch: ${pullResult.branch}): ${pullResult.error}`, {
- taskId: task.id, workspace: workspacePath, branch: pullResult.branch
- });
-
- const appId = task.metadata?.app || null;
- // The description's first line is the duplicate key, so it stays stable
- // across retries; the (varying) git error goes in the context.
- const conflictDesc = `Resolve git conflict in ${resolvedAppName || workspacePath} on branch ${pullResult.branch}. `
- + `The branch has diverged from origin and automatic rebase failed.`;
-
- await addTask({
- description: conflictDesc,
- priority: 'HIGH',
- app: appId,
- metadata: { gitConflictResolution: true },
- context: `Error: ${pullResult.error}\n`
- + `This conflict is blocking task ${task.id}: "${task.description}". `
- + `Resolve the conflict, commit, and push so the blocked task can proceed.`,
- position: 'top'
- }, 'internal').catch(err => {
- emitLog('warn', `Failed to create conflict resolution task: ${err.message}`, { taskId: task.id });
- });
-
- // A timed pause, not `pending`: a pending task is re-dequeued within
- // seconds and re-runs the same failing rebase in a hot loop until the
- // resolver lands. The cooldown sweeper revives it.
- await blockTask(task, `Git conflict in ${resolvedAppName || workspacePath} (branch ${pullResult.branch}); waiting for the resolver task`, 'git-conflict-wait', {
- cooldownUntil: new Date(Date.now() + GIT_CONFLICT_COOLDOWN_MS).toISOString(),
- });
- return {
- outcome: 'deferred',
- reason: 'Git conflict blocks task — conflict resolution task created',
- deferReason: 'git-conflict',
- branch: pullResult.branch
- };
- } else if (pullResult.success && !pullResult.upToDate && !pullResult.skipped) {
- emitLog('info', `📥 Pulled latest for ${resolvedAppName || 'workspace'} (branch: ${pullResult.branch})`, {
- taskId: task.id, workspace: workspacePath, branch: pullResult.branch
- });
- } else if (!pullResult.success) {
- emitLog('warn', `⚠️ Pre-task git pull error: ${pullResult.error}`, { taskId: task.id, workspace: workspacePath });
- }
-
- // JIRA integration: create ticket + feature branch if app has JIRA enabled and task opted in
- const appData = await getAppDataForTask(task);
-
- if (appData?.jira?.enabled && task.metadata?.createJiraTicket) {
- jiraTicket = await createJiraTicketForTask(task, appData);
-
- if (jiraTicket) {
- const slug = (task.description || 'task')
- .toLowerCase()
- .replace(/[^a-z0-9]+/g, '-')
- .replace(/^-|-$/g, '')
- .substring(0, 40);
- jiraBranchName = `feature/${jiraTicket.ticketId}-${slug}`;
-
- if (task.metadata?.app) {
- await git.fetchOrigin(workspacePath).catch(() => {});
- const { baseBranch: defaultBranch } = await git.getRepoBranches(workspacePath).catch(() => ({ baseBranch: null }));
- if (defaultBranch) {
- await git.checkout(workspacePath, defaultBranch).catch(() => {});
- await execGit(['merge', '--ff-only', `origin/${defaultBranch}`], workspacePath).catch(err => { emitLog('warn', `Fast-forward merge of ${defaultBranch} failed: ${err.message}`, { taskId: task.id }); });
- }
- }
-
- await git.createBranch(workspacePath, jiraBranchName)
- // `checkout -b` off a LOCAL branch doesn't auto-track under git's default
- // `branch.autoSetupMerge`, but a repo configured `always` records the base
- // branch as this one's upstream — and a config-derived push
- // (`git push <remote> HEAD:<merge>`) then lands the agent's work on the base
- // branch instead of opening a PR (#4172). Verify before handing it over.
- .then(() => enforceSafeBranchUpstream(workspacePath, jiraBranchName))
- .catch(err => {
- emitLog('warn', `Failed to create JIRA branch ${jiraBranchName}: ${err.message}`, { taskId: task.id });
- jiraBranchName = null;
- });
-
- if (jiraBranchName) {
- emitLog('success', `Created feature branch ${jiraBranchName}`, { taskId: task.id, ticketId: jiraTicket.ticketId });
- }
-
- task.metadata = {
- ...task.metadata,
- jiraTicketId: jiraTicket.ticketId,
- jiraTicketUrl: jiraTicket.ticketUrl,
- jiraBranch: jiraBranchName,
- jiraInstanceId: appData.jira.instanceId,
- jiraCreatePR: appData.jira.createPR !== false
- };
- }
- }
-
- // Feature agent tasks: use persistent worktree instead of creating a new one
- if (task.metadata?.featureAgentRun && task.metadata?.featureAgentId) {
- const { getFeatureAgent } = await import('./featureAgents.js');
- const fa = await getFeatureAgent(task.metadata.featureAgentId).catch(() => null);
- if (fa) {
- const faWorktreePath = join(PATHS.cos, 'feature-agents', fa.id, 'worktree');
- if (existsSync(faWorktreePath)) {
- workspacePath = faWorktreePath;
- worktreeInfo = {
- worktreePath: faWorktreePath,
- branchName: fa.git.branchName,
- baseBranch: fa.git.baseBranch || 'main',
- isPersistentWorktree: true
- };
- const { mergeBaseIntoFeatureWorktree } = await import('./worktreeManager.js');
- if (fa.git.autoMergeBase) {
- await mergeBaseIntoFeatureWorktree(fa.id, fa.git.baseBranch).catch(err => {
- emitLog('warn', `🌳 Feature agent base merge failed: ${err.message}`, { featureAgentId: fa.id });
- });
- }
- emitLog('info', `🌳 Feature agent ${fa.name} using persistent worktree: ${fa.git.branchName}`, {
- featureAgentId: fa.id, worktreePath: faWorktreePath
- });
- }
- }
- }
-
- } // end !isReadOnly
+ // A checked-out claim branch skips every later provisioner so it cannot fall
+ // through to the shared checkout. A remediation follow-up never continues one.
+ const claim = remediationPin === null ? await admitClaimWorkspace({ task, agentId, workspacePath: sourceWorkspace }) : null;
+ if (claim?.outcome) return claim;
+ if (claim) return ready(claim);
+
+ let jira = { jiraTicket: null, jiraBranchName: null };
+ let featureCheckout = null;
+ if (!isReadOnly) {
+ const deferred = await pullSharedCheckout({ task, workspacePath: sourceWorkspace, resolvedAppName, wantsWorktree });
+ if (deferred) return deferred;
+ jira = await prepareJiraBranch({ task, workspacePath: sourceWorkspace });
+ if (jira.metadataPatch) task.metadata = { ...task.metadata, ...jira.metadataPatch };
+ featureCheckout = await adoptFeatureAgentWorktree(task);
+ }
+ const current = { workspacePath: sourceWorkspace, worktreeInfo: null, ...featureCheckout, jiraTicket: jira.jiraTicket, jiraBranchName: jira.jiraBranchName };
+ // The JIRA feature branch was cut in the shared checkout; the agent works there.
+ if (current.jiraBranchName) return ready(current);
// A read-only public-review stage still needs a disposable checkout: it may
// run repository commands and the action stage's provider-specific sandbox
// needs it for tests/patch inspection. Never let `readOnly` turn an explicit
// isolation request into the live application checkout.
- if (wantsWorktree && !jiraBranchName && !claimWorkspace) {
+ if (wantsWorktree) {
const worktreeOutcome = await prepareRequestedWorktree({
agentId,
- workspacePath,
+ workspacePath: current.workspacePath,
task,
existingBranch,
- forkHead,
+ // Where that branch lives when the task points at a fork PR's head — read
+ // here rather than inside the worktree layer, which has no forge client.
+ forkHead: resolveTaskForkHead(task.metadata),
allowSharedWorkspaceFallback: !isReadOnly && !explicitWorktree,
});
if (worktreeOutcome.outcome !== 'ready') return worktreeOutcome;
- workspacePath = worktreeOutcome.workspacePath;
- worktreeInfo = worktreeOutcome.worktreeInfo;
- } else if (!claimWorkspace && !isReadOnly && !jiraBranchName && !isFalsyMeta(task.metadata?.useWorktree)) {
- const { getAgents } = await import('./cos.js');
- const allAgents = await getAgents();
- const runningAgents = allAgents.filter(a => a.status === 'running');
-
- const conflictResult = await detectConflicts(task, workspacePath, runningAgents).catch(err => {
- emitLog('warn', `Conflict detection failed: ${err.message}`, { taskId: task.id });
- return { hasConflict: false, recommendation: 'proceed' };
- });
-
- if (conflictResult.recommendation === 'worktree') {
- emitLog('info', `🌳 Conflict detected for task ${task.id}: ${conflictResult.reason} — creating worktree`, {
- taskId: task.id,
- conflictingAgents: conflictResult.conflictingAgents,
- reason: conflictResult.reason
- });
-
- worktreeInfo = await createWorktree(agentId, workspacePath, task.id, {
- planId: task.metadata?.planId || undefined,
- linkDependencies: resolveTaskHookType(task) !== 'dependency-updates',
- }).catch(err => {
- emitLog('warn', `🌳 Worktree creation failed, using shared workspace: ${err.message}`, { taskId: task.id });
- return null;
- });
-
- if (worktreeInfo) {
- workspacePath = worktreeInfo.worktreePath;
- emitLog('success', `🌳 Agent ${agentId} will work in worktree: ${worktreeInfo.branchName}`, {
- agentId, worktreePath: worktreeInfo.worktreePath, branchName: worktreeInfo.branchName
- });
- }
- } else if (conflictResult.recommendation === 'proceed') {
- emitLog('debug', `No conflicts for task ${task.id}, using shared workspace`, { taskId: task.id });
- }
- }
-
- // Announce the FINAL cwd — emitted here, after any worktree reassignment
- // above, so the task log names the directory the agent actually runs in
- // rather than the repo it was cut from (#3180).
- emitLog('info', `📂 Agent workspace: ${workspacePath}`, { taskId: task.id, workspace: workspacePath });
+ return ready({ ...current, workspacePath: worktreeOutcome.workspacePath, worktreeInfo: worktreeOutcome.worktreeInfo });
+ }
- return {
- outcome: 'ready',
- workspacePath,
- resolvedApp,
- resolvedAppName,
- worktreeInfo,
- jiraTicket,
- jiraBranchName,
- explicitWorktree
- };
+ if (!isReadOnly && !isFalsyMeta(task.metadata?.useWorktree)) {
+ const conflictWorktree = await provisionConflictWorktree({ agentId, task, workspacePath: current.workspacePath });
+ if (conflictWorktree) return ready({ ...current, workspacePath: conflictWorktree.worktreePath, worktreeInfo: conflictWorktree });
+ }
+ return ready(current);
}
diff --git a/server/services/agentWorkspacePrep.test.js b/server/services/agentWorkspacePrep.test.js
index fa7cd6a542..9a36eeac29 100644
--- a/server/services/agentWorkspacePrep.test.js
+++ b/server/services/agentWorkspacePrep.test.js
@@ -33,10 +33,10 @@ vi.mock('./git.js', () => ({
ensureLatest: vi.fn(),
isRepo: vi.fn().mockResolvedValue(true),
notGitRepoMessage: (name) => `${name} is not a git repository — run \`git init\``,
- fetchOrigin: vi.fn(),
+ fetchOrigin: vi.fn().mockResolvedValue(undefined),
getRepoBranches: vi.fn().mockResolvedValue({ baseBranch: 'main' }),
- checkout: vi.fn(),
- createBranch: vi.fn(),
+ checkout: vi.fn().mockResolvedValue(undefined),
+ createBranch: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./taskConflict.js', () => ({ detectConflicts: vi.fn().mockResolvedValue({ recommendation: 'proceed' }) }));
// `isBranchCheckedOutElsewhereError` is imported from the REAL module: it is a
@@ -59,7 +59,7 @@ vi.mock('./worktreeManager.js', async (importOriginal) => ({
releaseIdleSiblingNextHolder: vi.fn().mockResolvedValue(null),
releaseOwnerlessForeignHolder: vi.fn().mockResolvedValue(null),
listWorktrees: vi.fn().mockResolvedValue([]),
- mergeBaseIntoFeatureWorktree: vi.fn(),
+ mergeBaseIntoFeatureWorktree: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./agentAppWorkspace.js', () => ({
getAppWorkspace: vi.fn().mockResolvedValue('/repos/app-x'),
@@ -80,16 +80,26 @@ const handBackPrRemediationMock = vi.fn().mockResolvedValue(true);
vi.mock('./prRemediationFollowUp.js', () => ({ handBackPrRemediation: (...args) => handBackPrRemediationMock(...args) }));
vi.mock('./deepAudit.js', () => ({ getDeepAuditSourceRevision: vi.fn().mockResolvedValue('a'.repeat(40)) }));
+vi.mock('./featureAgents.js', () => ({ getFeatureAgent: vi.fn().mockResolvedValue(null) }));
+vi.mock('fs', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, existsSync: vi.fn(actual.existsSync) };
+});
import { prepareAgentWorkspace, resolveTaskExistingBranch } from './agentWorkspacePrep.js';
import { claimContinuationWorkspace } from '../lib/claimContinuation.js';
import { updateTask, addTask, getAgents } from './cos.js';
import { emitLog } from './cosEvents.js';
-import { ensureLatest, isRepo, fetchOrigin } from './git.js';
+import { ensureLatest, isRepo, fetchOrigin, createBranch } from './git.js';
+import { getAppDataForTask } from './agentAppWorkspace.js';
+import { createJiraTicketForTask } from './promptSections/appContext.js';
+import { getFeatureAgent } from './featureAgents.js';
+import { existsSync } from 'fs';
+import { join } from 'path';
import { execGit } from '../lib/execGit.js';
import { detectConflicts } from './taskConflict.js';
import { getAppWorkspace } from './agentAppWorkspace.js';
-import { PINNED_HEAD_MOVED, createWorktree, adoptWorktree, findAdoptableWorktreeForBranch, listWorktrees, releaseIdleSiblingNextHolder, releaseOwnerlessForeignHolder, unlinkWorktreeDependencies } from './worktreeManager.js';
+import { PINNED_HEAD_MOVED, createWorktree, adoptWorktree, findAdoptableWorktreeForBranch, listWorktrees, mergeBaseIntoFeatureWorktree, releaseIdleSiblingNextHolder, releaseOwnerlessForeignHolder, unlinkWorktreeDependencies } from './worktreeManager.js';
import { ensureDir, PATHS } from '../lib/fileUtils.js';
import { creativeDirectorScratchCwd } from '../lib/spawnCwd.js';
@@ -347,6 +357,77 @@ describe('prepareAgentWorkspace', () => {
expect(r.worktreeInfo).toBeNull();
expect(detectConflicts).toHaveBeenCalled();
});
+
+ describe('a shared-checkout task the conflict scan isolates', () => {
+ const task = () => ({ id: 't-busy', taskType: 'user', metadata: {} });
+ beforeEach(() => {
+ ensureLatest.mockResolvedValue({ success: true, upToDate: true });
+ detectConflicts.mockResolvedValueOnce({ hasConflict: true, recommendation: 'worktree', reason: 'workspace-has-uncommitted-changes' });
+ });
+
+ it('cuts a worktree when another agent is already working in the checkout', async () => {
+ createWorktree.mockResolvedValue({ worktreePath: '/mock/worktrees/agent-busy', branchName: 'cos/t-busy/agent-busy', baseBranch: 'main' });
+ const r = await prepareAgentWorkspace({ agentId: 'agent-busy', task: task() });
+ expect(r).toMatchObject({ outcome: 'ready', workspacePath: '/mock/worktrees/agent-busy', explicitWorktree: false });
+ expect(r.worktreeInfo.branchName).toBe('cos/t-busy/agent-busy');
+ });
+
+ it('stays in the shared checkout when that worktree cannot be created', async () => {
+ createWorktree.mockRejectedValue(new Error('disk full'));
+ const r = await prepareAgentWorkspace({ agentId: 'agent-busy', task: task() });
+ expect(r).toMatchObject({ outcome: 'ready', worktreeInfo: null, workspacePath: PATHS.root });
+ });
+ });
+
+ describe('a JIRA-enabled app', () => {
+ const jiraTask = () => ({ id: 't-jira', taskType: 'user', description: 'Fix the Widget!', metadata: { app: 'app-x', createJiraTicket: true } });
+ beforeEach(() => {
+ getAppWorkspace.mockResolvedValue(process.cwd());
+ ensureLatest.mockResolvedValue({ success: true, upToDate: true });
+ getAppDataForTask.mockResolvedValueOnce({ jira: { enabled: true, instanceId: 'jira-1', createPR: false } });
+ createJiraTicketForTask.mockResolvedValueOnce({ ticketId: 'EX-7', ticketUrl: 'https://jira.example.com/browse/EX-7' });
+ });
+
+ it('creates the ticket and its feature branch in the app checkout instead of a worktree', async () => {
+ const task = jiraTask();
+ const r = await prepareAgentWorkspace({ agentId: 'agent-jira', task });
+ expect(r).toMatchObject({ outcome: 'ready', jiraBranchName: 'feature/EX-7-fix-the-widget', worktreeInfo: null });
+ expect(r.jiraTicket.ticketId).toBe('EX-7');
+ expect(createBranch).toHaveBeenCalledWith(process.cwd(), 'feature/EX-7-fix-the-widget');
+ expect(task.metadata).toMatchObject({
+ jiraTicketId: 'EX-7', jiraBranch: 'feature/EX-7-fix-the-widget', jiraInstanceId: 'jira-1', jiraCreatePR: false,
+ });
+ expect(detectConflicts).not.toHaveBeenCalled();
+ expect(createWorktree).not.toHaveBeenCalled();
+ });
+
+ it('keeps the ticket but falls back to the ordinary shared-checkout path when the branch cannot be created', async () => {
+ createBranch.mockRejectedValueOnce(new Error('branch exists'));
+ const task = jiraTask();
+ const r = await prepareAgentWorkspace({ agentId: 'agent-jira', task });
+ expect(r).toMatchObject({ outcome: 'ready', jiraBranchName: null });
+ expect(r.jiraTicket.ticketId).toBe('EX-7');
+ expect(task.metadata).toMatchObject({ jiraTicketId: 'EX-7', jiraBranch: null });
+ expect(detectConflicts).toHaveBeenCalled();
+ });
+ });
+
+ it('runs a feature-agent task in its persistent worktree and merges its base first', async () => {
+ ensureLatest.mockResolvedValue({ success: true, upToDate: true });
+ getFeatureAgent.mockResolvedValueOnce({ id: 'fa-1', name: 'Example Agent', git: { branchName: 'feature/fa-1', baseBranch: 'dev', autoMergeBase: true } });
+ const faWorktree = join(PATHS.cos, 'feature-agents', 'fa-1', 'worktree');
+ const realExistsSync = existsSync.getMockImplementation();
+ existsSync.mockImplementation(path => path === faWorktree || realExistsSync(path));
+ const task = { id: 't-fa', taskType: 'internal', metadata: { featureAgentRun: true, featureAgentId: 'fa-1' } };
+
+ const r = await prepareAgentWorkspace({ agentId: 'agent-fa', task })
+ .finally(() => existsSync.mockImplementation(realExistsSync));
+
+ expect(r).toMatchObject({ outcome: 'ready', workspacePath: faWorktree });
+ expect(r.worktreeInfo).toEqual({ worktreePath: faWorktree, branchName: 'feature/fa-1', baseBranch: 'dev', isPersistentWorktree: true });
+ expect(mergeBaseIntoFeatureWorktree).toHaveBeenCalledWith('fa-1', 'dev');
+ expect(createWorktree).not.toHaveBeenCalled();
+ });
});
describe('prepareAgentWorkspace — workspace validation (#3180)', () => {