@fitlab-ai/agent-infra 0.11.12 → 0.11.14

package/dist/lib/task/lifecycle.js

@@ -18,6 +18,7 @@ const lifecycleIntentCatalog = [
     'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'
 ];
 const lifecycleFailureCatalog = [
+    'LIFECYCLE_DIRECTORY_TRANSFER_FAILED',
     'LIFECYCLE_DIRECTORY_RENAME_FAILED',
     'LIFECYCLE_DOCUMENT_INVALID',
     'LIFECYCLE_FINAL_STATE_INVALID',
@@ -46,6 +47,9 @@ const lifecycleProducerCatalog = lifecycleFailureCatalog.map((code) => ({
     code
 }));
 const STEPS = ['task-written', 'directory-moved', 'registry-committed'];
+function stepsForIntent(intent) {
+    return intent === 'complete' ? ['task-written', 'directory-moved'] : STEPS;
+}
 const DEFAULT_IO = {
     renameSync: (source, target) => fs.renameSync(source, target),
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
@@ -58,7 +62,7 @@ function failed(request, error, extra = {}) {
         intent: request.intent, sourceState: null, targetState: null, sourcePath: null,
         targetPath: null, task: { operations: [] }, directory: { effect: 'unchanged', changed: false },
         shortId: { effect: 'unchanged', shortId: null, changed: false }, timestamp: null,
-        agentInfraVersion: null, journalPath: null, completedSteps: [], pendingSteps: STEPS,
+        agentInfraVersion: null, journalPath: null, completedSteps: [], pendingSteps: stepsForIntent(request.intent),
         error, ...extra
     };
 }
@@ -134,8 +138,195 @@ function transition(request) {
         return { sources: ['active', 'blocked'], target: 'completed', registry: 'release' };
     if (request.intent === 'restore')
         return { sources: ['staging'], target: 'active', registry: 'alloc' };
+    if (request.intent === 'complete')
+        return { sources: ['active'], target: 'completed', registry: 'none' };
     return { sources: ['active'], target: 'completed', registry: 'release' };
 }
+function sameTaskEntry(source, target) {
+    const sourceStat = fs.lstatSync(source);
+    let targetStat;
+    try {
+        targetStat = fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (sourceStat.isSymbolicLink() || targetStat.isSymbolicLink()) {
+        return sourceStat.isSymbolicLink() && targetStat.isSymbolicLink()
+            && fs.readlinkSync(source) === fs.readlinkSync(target);
+    }
+    if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+        const sourceNames = fs.readdirSync(source).sort();
+        const targetNames = fs.readdirSync(target).sort();
+        return sourceNames.join('\0') === targetNames.join('\0')
+            && sourceNames.every((name) => sameTaskEntry(path.join(source, name), path.join(target, name)))
+            && (sourceStat.mode & 0o777) === (targetStat.mode & 0o777);
+    }
+    return sourceStat.isFile() && targetStat.isFile()
+        && (sourceStat.mode & 0o777) === (targetStat.mode & 0o777)
+        && fs.readFileSync(source).equals(fs.readFileSync(target));
+}
+function copyTaskEntry(source, target) {
+    const sourceStat = fs.lstatSync(source);
+    if (fs.existsSync(target)) {
+        const targetStat = fs.lstatSync(target);
+        if (sourceStat.isDirectory() && targetStat.isDirectory() && !targetStat.isSymbolicLink()) {
+            for (const name of fs.readdirSync(source).sort())
+                copyTaskEntry(path.join(source, name), path.join(target, name));
+            fs.chmodSync(target, sourceStat.mode & 0o777);
+            return;
+        }
+        if (sameTaskEntry(source, target))
+            return;
+        throw new Error(`task content conflict at ${path.relative(path.dirname(source), source)}`);
+    }
+    if (sourceStat.isSymbolicLink()) {
+        fs.symlinkSync(fs.readlinkSync(source), target);
+        return;
+    }
+    if (sourceStat.isDirectory()) {
+        fs.mkdirSync(target, { mode: sourceStat.mode & 0o777 });
+        for (const name of fs.readdirSync(source).sort())
+            copyTaskEntry(path.join(source, name), path.join(target, name));
+        fs.chmodSync(target, sourceStat.mode & 0o777);
+        return;
+    }
+    if (!sourceStat.isFile())
+        throw new Error(`unsupported task entry: ${source}`);
+    fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(target, sourceStat.mode & 0o777);
+}
+function transferTaskContents(sourcePath, targetPath) {
+    const sourceRoot = fs.lstatSync(sourcePath);
+    if (!sourceRoot.isDirectory() || sourceRoot.isSymbolicLink())
+        throw new Error('task source is not a real directory');
+    const targetRoot = fs.lstatSync(targetPath);
+    if (!targetRoot.isDirectory() || targetRoot.isSymbolicLink())
+        throw new Error('completed target is not a real directory');
+    for (const name of fs.readdirSync(sourcePath).sort()) {
+        copyTaskEntry(path.join(sourcePath, name), path.join(targetPath, name));
+    }
+    const sourceNames = fs.readdirSync(sourcePath).sort();
+    const targetNames = fs.readdirSync(targetPath).sort();
+    if (sourceNames.join('\0') !== targetNames.join('\0')
+        || !sourceNames.every((name) => sameTaskEntry(path.join(sourcePath, name), path.join(targetPath, name)))) {
+        throw new Error('completed target does not match task source after copy');
+    }
+}
+function pathExists(candidate) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function assertTaskControlRootPath(controlRoot, taskId, expectedProject) {
+    if (path.basename(controlRoot) !== taskId || path.basename(path.dirname(controlRoot)) !== 'tasks'
+        || (expectedProject !== undefined && path.basename(path.dirname(path.dirname(controlRoot))) !== expectedProject)) {
+        throw new Error('control root path does not match the task/project layout');
+    }
+    const managedBase = path.dirname(path.dirname(path.dirname(controlRoot)));
+    let current = managedBase;
+    for (const segment of path.relative(managedBase, controlRoot).split(path.sep).filter(Boolean)) {
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink())
+            throw new Error('control root ancestor is a symbolic link');
+        current = path.join(current, segment);
+    }
+    const stat = fs.lstatSync(controlRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('control root is not a real directory');
+}
+function assertTaskControlManifestIdentity(controlRoot, taskId, repoRoot, expectedProject) {
+    const controlManifest = path.join(controlRoot, 'manifest.json');
+    if (!fs.existsSync(controlManifest))
+        throw new Error('control manifest is missing');
+    const manifestStat = fs.lstatSync(controlManifest);
+    if (!manifestStat.isFile() || manifestStat.isSymbolicLink())
+        throw new Error('control manifest is not a real file');
+    const manifest = JSON.parse(fs.readFileSync(controlManifest, 'utf8'));
+    const project = expectedProject ?? path.basename(path.dirname(path.dirname(controlRoot)));
+    if (manifest.mode !== 'task-bound' || manifest.taskId !== taskId || manifest.project !== project
+        || typeof manifest.repoRoot !== 'string' || fs.realpathSync.native(manifest.repoRoot) !== fs.realpathSync.native(repoRoot)) {
+        throw new Error('control manifest identity does not match the task');
+    }
+}
+function taskBoundControlMoveSafety(request, controlRoot, options, taskId, repoRoot, validateManifestIdentity) {
+    if (!controlRoot)
+        return null;
+    const controlManifest = path.join(controlRoot, 'manifest.json');
+    const controlLease = path.join(controlRoot, 'lease.json');
+    const stateExists = pathExists(controlRoot) || pathExists(controlManifest) || pathExists(controlLease);
+    if (stateExists) {
+        try {
+            assertTaskControlRootPath(controlRoot, taskId, options.controlProject);
+            if (validateManifestIdentity) {
+                assertTaskControlManifestIdentity(controlRoot, taskId, repoRoot, options.controlProject);
+            }
+            else {
+                const manifestStat = fs.lstatSync(controlManifest);
+                if (!manifestStat.isFile() || manifestStat.isSymbolicLink())
+                    throw new Error('control manifest is not a real file');
+            }
+        }
+        catch {
+            return { code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE', message: 'task-bound sandbox control root is missing, malformed, or belongs to another task' };
+        }
+    }
+    if (request.intent !== 'complete' && (pathExists(controlManifest) || pathExists(controlLease))) {
+        return { code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE', message: 'task-bound sandbox control state exists; stop and remove the verified sandbox before moving the task directory' };
+    }
+    return null;
+}
+function orchestrationMoveSafety(sourcePath) {
+    const orchestrationPath = path.join(sourcePath, '.runtime', 'orchestration.json');
+    if (!pathExists(orchestrationPath))
+        return null;
+    try {
+        const run = JSON.parse(fs.readFileSync(orchestrationPath, 'utf8'));
+        if (run.status === 'running' || run.pendingDelegation !== null && run.pendingDelegation !== undefined) {
+            return { code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE', message: 'task orchestration has an active or pending delegation; settle it before moving the task directory' };
+        }
+    }
+    catch {
+        return { code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE', message: 'task orchestration state is unreadable; refusing to move the task directory' };
+    }
+    return null;
+}
+function runtimeMoveSafety(request, movingTaskDirectory, options, taskId, repoRoot, sourcePath, validateControlManifestIdentity) {
+    if (!movingTaskDirectory)
+        return null;
+    const controlSafety = taskBoundControlMoveSafety(request, options.controlRoot, options, taskId, repoRoot, validateControlManifestIdentity);
+    return controlSafety ?? orchestrationMoveSafety(sourcePath);
+}
+function targetContainsTask(targetPath, taskId, request) {
+    try {
+        const stat = fs.lstatSync(targetPath);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+        const entries = fs.readdirSync(targetPath);
+        if (entries.length === 0)
+            return true;
+        const taskPath = path.join(targetPath, 'task.md');
+        const journalPath = path.join(targetPath, '.task-lifecycle.json');
+        if (!fs.existsSync(taskPath) || !fs.existsSync(journalPath))
+            return false;
+        const frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(taskPath, 'utf8'));
+        const journal = parseJournal(fs.readFileSync(journalPath, 'utf8'));
+        return frontmatter.id === taskId && frontmatter.status === 'completed'
+            && journal.taskId === taskId && journal.intent === request.intent
+            && journal.intentDigest === intentIdentity(request, taskId);
+    }
+    catch {
+        return false;
+    }
+}
 function actionAndNote(request, restoredFiles = 0) {
     if (request.intent === 'block')
         return { action: 'Block Task', note: request.reason };
@@ -367,7 +558,7 @@ export function inspectTaskLifecycleProgress(repoRoot, taskId, agent) {
             || journal.intentDigest !== intentIdentity(request, taskId)
             || journal.sourceState !== 'active' || journal.targetState !== 'completed')
             return 'unknown';
-        if (journal.completedSteps.some((step, index) => STEPS[index] !== step))
+        if (journal.completedSteps.some((step, index) => stepsForIntent(journal.intent)[index] !== step))
             return 'unknown';
         const directoryMoved = journal.completedSteps.includes('directory-moved');
         const registryCommitted = journal.completedSteps.includes('registry-committed');
@@ -375,7 +566,7 @@ export function inspectTaskLifecycleProgress(repoRoot, taskId, agent) {
         if (state === 'active' && (directoryMoved || !hasShortId))
             return 'unknown';
         if (state === 'completed' && (!journal.completedSteps.includes('task-written')
-            || !matchingCompletion(content, request) || (registryCommitted && hasShortId)))
+            || !matchingCompletion(content, request) || registryCommitted || !hasShortId))
             return 'unknown';
         if (frontmatter.status !== state
             && !(state === 'active' && frontmatter.status === 'completed' && matchingCompletion(content, request))) {
@@ -411,7 +602,12 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
     }
     const spec = transition(request);
     const hot = locateHotTaskDirs(repoRoot, taskId);
-    if (hot.length > 1)
+    const activeSource = hot.find((candidate) => candidate.state === 'active');
+    const completedTarget = hot.find((candidate) => candidate.state === 'completed');
+    const transferInProgress = request.intent === 'complete' && Boolean(activeSource && completedTarget)
+        && targetContainsTask(completedTarget.taskDir, taskId, request)
+        && fs.existsSync(path.join(activeSource.taskDir, '.task-lifecycle.json'));
+    if (hot.length > 1 && !transferInProgress)
         return failed(request, { code: 'LIFECYCLE_IDENTITY_CONFLICT', message: `task ${taskId} exists in multiple hot states` }, { taskId });
     let sourceState;
     let sourcePath;
@@ -424,6 +620,11 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
         sourcePath = validation.stagingDir;
         restoredFiles = validation.fileCount;
     }
+    else if (activeSource && request.intent === 'complete') {
+        sourceState = activeSource.state;
+        sourcePath = activeSource.taskDir;
+        restoredFiles = fs.readdirSync(sourcePath).filter((name) => !name.startsWith('.')).length;
+    }
     else if (hot[0]) {
         sourceState = hot[0].state;
         sourcePath = hot[0].taskDir;
@@ -433,38 +634,8 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
         return failed(request, { code: 'LIFECYCLE_TASK_NOT_FOUND', message: `task ${taskId} has no lifecycle source` }, { taskId });
     }
     const targetPath = path.join(repoRoot, '.agents', 'workspace', spec.target, taskId);
+    const requiredSteps = stepsForIntent(request.intent);
     const movingTaskDirectory = sourcePath !== targetPath;
-    const assertRuntimeMoveSafe = () => {
-        if (!movingTaskDirectory)
-            return null;
-        const controlManifest = path.join(sourcePath, '.runtime', 'sandbox-control', 'manifest.json');
-        const controlLease = path.join(sourcePath, '.runtime', 'sandbox-control', 'lease.json');
-        if (fs.existsSync(controlManifest) || fs.existsSync(controlLease)) {
-            return {
-                code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE',
-                message: 'task-bound sandbox control state exists; stop and remove the verified sandbox before moving the task directory'
-            };
-        }
-        const orchestrationPath = path.join(sourcePath, '.runtime', 'orchestration.json');
-        if (fs.existsSync(orchestrationPath)) {
-            try {
-                const run = JSON.parse(fs.readFileSync(orchestrationPath, 'utf8'));
-                if (run.status === 'running' || run.pendingDelegation !== null && run.pendingDelegation !== undefined) {
-                    return {
-                        code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE',
-                        message: 'task orchestration has an active or pending delegation; settle it before moving the task directory'
-                    };
-                }
-            }
-            catch {
-                return {
-                    code: 'LIFECYCLE_RUNTIME_MOVE_UNSAFE',
-                    message: 'task orchestration state is unreadable; refusing to move the task directory'
-                };
-            }
-        }
-        return null;
-    };
     const currentTaskFile = path.join(sourcePath, 'task.md');
     const existingJournal = fs.existsSync(path.join(sourcePath, '.task-lifecycle.json'));
     if (sourceState === spec.target && !existingJournal) {
@@ -474,7 +645,7 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
             return {
                 ...failed(request, { code: '', message: '' }), status: 'no-op', error: null, taskId,
                 sourceState, targetState: spec.target, sourcePath, targetPath, pendingSteps: [],
-                completedSteps: STEPS, timestamp: typeof frontmatter.updated_at === 'string' ? frontmatter.updated_at : null,
+                completedSteps: requiredSteps, timestamp: typeof frontmatter.updated_at === 'string' ? frontmatter.updated_at : null,
                 agentInfraVersion: typeof frontmatter.agent_infra_version === 'string' ? frontmatter.agent_infra_version : null
             };
         }
@@ -483,10 +654,11 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
     if (!spec.sources.includes(sourceState) && !existingJournal) {
         return failed(request, { code: 'LIFECYCLE_SOURCE_INVALID', message: `${request.intent} is not allowed from ${sourceState}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
-    if (sourcePath !== targetPath && fs.existsSync(targetPath) && !existingJournal) {
+    if (sourcePath !== targetPath && fs.existsSync(targetPath) && !existingJournal
+        && !(request.intent === 'complete' && targetContainsTask(targetPath, taskId, request))) {
         return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
-    const moveSafety = assertRuntimeMoveSafe();
+    const moveSafety = runtimeMoveSafety(request, movingTaskDirectory, options, taskId, repoRoot, sourcePath, true);
     if (moveSafety)
         return failed(request, moveSafety, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     const content = io.readFileSync(currentTaskFile);
@@ -515,7 +687,7 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
     }
     const registry = JSON.parse(registryRequest.output || '{"version":1,"ids":{}}');
     const registeredKey = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId)?.[0];
-    if (spec.registry === 'release' && sourceState === 'active' && !registeredKey) {
+    if ((spec.registry === 'release' || request.intent === 'complete') && sourceState === 'active' && !registeredKey) {
         return failed(request, { code: 'LIFECYCLE_SHORT_ID_PRECONDITION', message: 'active source has no short-id registry entry' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
     }
     if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1) {
@@ -540,7 +712,7 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
         if (request.dryRun) {
             if (!journal.failure)
                 return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: 'existing lifecycle journal has no durable failure evidence for a read-only probe' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
-            return failed(request, journal.failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, completedSteps: journal.completedSteps, pendingSteps: STEPS.filter((step) => !journal.completedSteps.includes(step)) });
+            return failed(request, journal.failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, completedSteps: journal.completedSteps, pendingSteps: requiredSteps.filter((step) => !journal.completedSteps.includes(step)) });
         }
         if (journal.intentDigest !== digest)
             return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
@@ -591,7 +763,8 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
     if (sourceState === spec.target && journal.sourceState !== spec.target)
         completed.add('directory-moved');
     const currentMappings = loadShortIdByTaskId(repoRoot);
-    if ((spec.target === 'active' && currentMappings.has(taskId)) || (spec.target !== 'active' && !currentMappings.has(taskId))) {
+    if (requiredSteps.includes('registry-committed')
+        && ((spec.target === 'active' && currentMappings.has(taskId)) || (spec.target !== 'active' && !currentMappings.has(taskId)))) {
         if (completed.has('directory-moved'))
             completed.add('registry-committed');
     }
@@ -603,7 +776,7 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
             task: { operations: [] }, directory: { effect: 'unchanged', changed: false },
             shortId: { effect: 'unchanged', shortId: null, changed: false },
             timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion,
-            journalPath, completedSteps: [...completed], pendingSteps: STEPS.filter((step) => !completed.has(step))
+            journalPath, completedSteps: [...completed], pendingSteps: requiredSteps.filter((step) => !completed.has(step))
         };
     }
     if (matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles))
@@ -637,30 +810,42 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
             task: { operations: taskOperations }, directory: { effect: 'unchanged', changed: false },
             shortId: { effect: 'unchanged', shortId: null, changed: false },
             timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion,
-            journalPath, completedSteps: [...completed], pendingSteps: STEPS.filter((step) => !completed.has(step))
+            journalPath, completedSteps: [...completed], pendingSteps: requiredSteps.filter((step) => !completed.has(step))
         };
     }
-    if (fs.existsSync(targetPath) && !fs.existsSync(sourcePath))
+    if (fs.existsSync(targetPath) && !fs.existsSync(path.join(sourcePath, 'task.md')))
         completed.add('directory-moved');
     if (!completed.has('directory-moved')) {
-        const moveSafety = assertRuntimeMoveSafe();
+        const moveSafety = runtimeMoveSafety(request, movingTaskDirectory, options, taskId, repoRoot, sourcePath, false);
         if (moveSafety)
             return failed(request, moveSafety, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, completedSteps: [...completed], changed: completed.size > 0, timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
         fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-        if (fs.existsSync(targetPath))
-            return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
-        try {
-            (options.directoryRenameSync ?? io.renameSync)(sourcePath, targetPath);
-        }
-        catch (error) {
-            const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) };
-            rememberJournalFailure(journalPath, journal, io, failure);
-            return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
-        }
-        if (completed.has('directory-moved') && !fs.existsSync(sourcePath)) {
-            journalPath = path.join(targetPath, '.task-lifecycle.json');
-        }
-        else if (!completed.has('directory-moved')) {
+        if (request.intent === 'complete') {
+            try {
+                if (!fs.existsSync(targetPath))
+                    fs.mkdirSync(targetPath, { recursive: false, mode: 0o700 });
+                if (!targetContainsTask(targetPath, taskId, request)) {
+                    throw new Error('completed target has no matching task identity');
+                }
+                transferTaskContents(sourcePath, targetPath);
+                for (const name of fs.readdirSync(sourcePath).filter((entry) => entry !== '.task-lifecycle.json' && entry !== 'task.md').sort()) {
+                    fs.rmSync(path.join(sourcePath, name), { recursive: true, force: false });
+                }
+                fs.rmSync(path.join(sourcePath, 'task.md'), { force: false });
+                fs.rmSync(path.join(sourcePath, '.task-lifecycle.json'), { force: false });
+            }
+            catch (error) {
+                const failure = { code: 'LIFECYCLE_DIRECTORY_TRANSFER_FAILED', message: String(error) };
+                const sourceJournalPath = path.join(sourcePath, '.task-lifecycle.json');
+                rememberJournalFailure(sourceJournalPath, journal, io, failure);
+                return failed(request, failure, {
+                    taskId, sourceState, targetState: spec.target, sourcePath, targetPath,
+                    journalPath: sourceJournalPath, task: { operations: taskOperations },
+                    changed: true, completedSteps: [...completed].filter((step) => step !== 'directory-moved'),
+                    pendingSteps: requiredSteps.filter((step) => !completed.has(step) || step === 'directory-moved'),
+                    timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion
+                });
+            }
             completed.add('directory-moved');
             journal.completedSteps = [...completed];
             journalPath = path.join(targetPath, '.task-lifecycle.json');
@@ -668,12 +853,58 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
                 writeJournal(journalPath, journal, io);
             }
             catch (error) {
-                return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, directory: { effect: 'move', changed: true }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+                return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, {
+                    taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath,
+                    task: { operations: taskOperations }, directory: { effect: 'move', changed: true },
+                    changed: true, completedSteps: [...completed].filter((step) => step !== 'directory-moved'),
+                    pendingSteps: requiredSteps.filter((step) => step !== 'task-written'),
+                    timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion
+                });
+            }
+        }
+        else {
+            if (fs.existsSync(targetPath))
+                return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+            try {
+                (options.directoryRenameSync ?? io.renameSync)(sourcePath, targetPath);
+            }
+            catch (error) {
+                const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) };
+                rememberJournalFailure(journalPath, journal, io, failure);
+                return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
             }
+            if (completed.has('directory-moved') && !fs.existsSync(sourcePath)) {
+                journalPath = path.join(targetPath, '.task-lifecycle.json');
+            }
+            else if (!completed.has('directory-moved')) {
+                completed.add('directory-moved');
+                journal.completedSteps = [...completed];
+                journalPath = path.join(targetPath, '.task-lifecycle.json');
+                try {
+                    writeJournal(journalPath, journal, io);
+                }
+                catch (error) {
+                    return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, directory: { effect: 'move', changed: true }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+                }
+            }
+        }
+    }
+    const activeTaskPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+    if (request.intent === 'complete' && fs.existsSync(activeTaskPath)) {
+        try {
+            fs.rmdirSync(activeTaskPath);
+        }
+        catch (error) {
+            return failed(request, { code: 'LIFECYCLE_SOURCE_DIRECTORY_CLEANUP_FAILED', message: String(error) }, {
+                taskId, sourceState, targetState: spec.target, sourcePath: activeTaskPath, targetPath, journalPath,
+                task: { operations: taskOperations }, directory: { effect: 'move', changed: true },
+                changed: true, completedSteps: [...completed], pendingSteps: [],
+                timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion
+            });
         }
     }
-    let shortId = { effect: 'unchanged', shortId: null, changed: false };
-    if (!completed.has('registry-committed')) {
+    let shortId = { effect: 'unchanged', shortId: request.intent === 'complete' ? registeredKey ?? null : null, changed: false };
+    if (requiredSteps.includes('registry-committed') && !completed.has('registry-committed')) {
         try {
             shortId = mutateShortIdRegistry(repoRoot, taskId, spec.registry);
         }
@@ -692,7 +923,7 @@ function applyTaskLifecycleUnlocked(requestInput, options = {}) {
     const mappings = loadShortIdByTaskId(repoRoot);
     if (spec.target === 'active' && !mappings.has(taskId))
         return failed(request, { code: 'LIFECYCLE_FINAL_STATE_INVALID', message: 'active lifecycle target has no short id' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, changed: true, completedSteps: [...completed], pendingSteps: [], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
-    if (spec.target !== 'active' && mappings.has(taskId))
+    if (request.intent !== 'complete' && spec.target !== 'active' && mappings.has(taskId))
         return failed(request, { code: 'LIFECYCLE_FINAL_STATE_INVALID', message: 'non-active lifecycle target retained a short id' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, changed: true, completedSteps: [...completed], pendingSteps: [], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
     try {
         io.unlinkSync(journalPath);