@fitlab-ai/agent-infra 0.9.11 → 0.9.12

package/lib/task/delivery-target.ts

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export type DeliveryTarget = Readonly<{
+  remote: string;
+  baseRef: string;
+}>;
+
+export type DeliveryTargetBindingInput = Readonly<{
+  defaults?: Partial<DeliveryTarget>;
+  existing?: Partial<DeliveryTarget>;
+  explicit?: Partial<DeliveryTarget>;
+}>;
+
+export type DeliveryTargetResult =
+  | { ok: true; value: DeliveryTarget }
+  | { ok: false; code: string; message: string };
+
+export type DiffBaseResult =
+  | { ok: true; diffBase: string }
+  | { ok: false; code: string; message: string };
+
+const REMOTE_RE = /^(?!-)(?!.*\.\.)(?!.*[~^:?*\\\s])[A-Za-z0-9._/-]+$/;
+const REF_RE = /^(?!-)(?!.*\.\.)(?!.*(?:^|\/)\.)(?!.*[~^:?*\\\s])[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+
+function validateRemote(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && REMOTE_RE.test(value);
+}
+
+function validateBaseRef(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('refs/') && REF_RE.test(value);
+}
+
+function invalid(field: string, value: unknown): DeliveryTargetResult {
+  return { ok: false, code: 'DELIVERY_TARGET_INVALID', message: `${field} is invalid: ${String(value ?? '')}` };
+}
+
+function bindDeliveryTarget(input: DeliveryTargetBindingInput): DeliveryTargetResult {
+  const remote = input.existing?.remote ?? input.explicit?.remote ?? input.defaults?.remote;
+  const baseRef = input.existing?.baseRef ?? input.explicit?.baseRef ?? input.defaults?.baseRef;
+  if (input.existing?.remote !== undefined && input.explicit?.remote !== undefined && input.existing.remote !== input.explicit.remote) {
+    return { ok: false, code: 'DELIVERY_TARGET_CONFLICT', message: 'Explicit delivery remote does not match the task binding' };
+  }
+  if (input.existing?.baseRef !== undefined && input.explicit?.baseRef !== undefined && input.existing.baseRef !== input.explicit.baseRef) {
+    return { ok: false, code: 'DELIVERY_TARGET_CONFLICT', message: 'Explicit delivery base ref does not match the task binding' };
+  }
+  if (!validateRemote(remote)) return invalid('delivery remote', remote);
+  if (!validateBaseRef(baseRef)) return invalid('delivery base ref', baseRef);
+  return { ok: true, value: { remote, baseRef } };
+}
+
+function readDeliveryDefaults(repoRoot: string): DeliveryTargetResult {
+  try {
+    const configPath = path.join(repoRoot, '.agents', '.airc.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Record<string, unknown>;
+    if (!config.delivery || typeof config.delivery !== 'object' || Array.isArray(config.delivery)) {
+      return { ok: false, code: 'DELIVERY_CONFIG_INVALID', message: 'delivery config must declare remote and baseRef' };
+    }
+    const delivery = config.delivery as Record<string, unknown>;
+    if (typeof delivery.remote !== 'string' || typeof delivery.baseRef !== 'string') {
+      return { ok: false, code: 'DELIVERY_CONFIG_INVALID', message: 'delivery config must declare remote and baseRef' };
+    }
+    return bindDeliveryTarget({
+      defaults: {
+        remote: delivery.remote,
+        baseRef: delivery.baseRef
+      }
+    });
+  } catch (error) {
+    return { ok: false, code: 'DELIVERY_CONFIG_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function resolveDeliveryTarget(
+  repoRoot: string,
+  existing: Partial<DeliveryTarget> = {},
+  explicit: Partial<DeliveryTarget> = {}
+): DeliveryTargetResult {
+  const defaults = readDeliveryDefaults(repoRoot);
+  if (!defaults.ok) return defaults;
+  return bindDeliveryTarget({ defaults: defaults.value, existing, explicit });
+}
+
+function gitText(repoRoot: string, args: readonly string[]): string {
+  return execFileSync('git', [...args], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
+}
+
+function resolveTargetHead(repoRoot: string, target: DeliveryTarget): DeliveryTargetResult & { head?: string } {
+  try {
+    const output = gitText(repoRoot, ['ls-remote', '--refs', target.remote, `refs/heads/${target.baseRef}`]);
+    const head = output.split(/\s+/)[0] ?? '';
+    if (!/^[a-f0-9]{40}$/i.test(head)) {
+      return { ok: false, code: 'DELIVERY_TARGET_UNAVAILABLE', message: `Delivery target ${target.remote}/${target.baseRef} is unavailable` };
+    }
+    try { gitText(repoRoot, ['cat-file', '-e', `${head}^{commit}`]); }
+    catch {
+      return { ok: false, code: 'DELIVERY_TARGET_OBJECT_MISSING', message: `Delivery target commit ${head} is not available locally` };
+    }
+    return { ok: true, value: target, head };
+  } catch (error) {
+    return { ok: false, code: 'DELIVERY_TARGET_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function resolveDiffBase(repoRoot: string, reviewedHead: string, targetHead: string): DiffBaseResult {
+  try {
+    const diffBase = gitText(repoRoot, ['merge-base', reviewedHead, targetHead]);
+    if (!/^[a-f0-9]{40}$/i.test(diffBase)) {
+      return { ok: false, code: 'DELIVERY_DIFF_BASE_UNAVAILABLE', message: 'Git returned an invalid diff base' };
+    }
+    return { ok: true, diffBase };
+  } catch (error) {
+    return { ok: false, code: 'DELIVERY_DIFF_BASE_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export {
+  bindDeliveryTarget,
+  readDeliveryDefaults,
+  resolveDeliveryTarget,
+  resolveTargetHead,
+  resolveDiffBase,
+  validateBaseRef,
+  validateRemote
+};

package/lib/task/delivery.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { parseTaskFrontmatter } from './frontmatter.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead, validateBaseRef, validateRemote } from './delivery-target.ts';
+import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead, findAuthoritativeReviewCodeArtifact } from './review-fingerprint.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import { withRepositoryMutationLock, withTaskExecutionLock } from './task-execution-lock.ts';
+
+export type DeliveryState = 'absent' | 'same' | 'known-old' | 'unknown-drift';
+
+export type DeliveryClassification = Readonly<{
+  state: DeliveryState;
+  shouldPush: boolean;
+}>;
+
+export type TaskBranchDeliveryResult = Readonly<{
+  status: 'applied' | 'no-op' | 'failed' | 'blocked' | 'planned';
+  changed: boolean;
+  taskId: string | null;
+  remoteHead: string | null;
+  localHead: string | null;
+  state: DeliveryState | null;
+  error: { code: string; message: string; retryable: boolean } | null;
+}>;
+
+function classifyDeliveryState(localHead: string, remoteHead: string | null, lastDelivered: string | null): DeliveryClassification {
+  if (remoteHead === null) return { state: 'absent', shouldPush: true };
+  if (remoteHead === localHead) return { state: 'same', shouldPush: false };
+  if (lastDelivered && remoteHead === lastDelivered) return { state: 'known-old', shouldPush: true };
+  return { state: 'unknown-drift', shouldPush: false };
+}
+
+function git(cwd: string, args: readonly string[]): { status: number | null; stdout: string; stderr: string } {
+  const result = spawnSync('git', [...args], { cwd, encoding: 'utf8' });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+function gitValue(cwd: string, args: readonly string[]): string | null {
+  const result = git(cwd, args);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function validateBranch(cwd: string, branch: string): boolean {
+  return git(cwd, ['check-ref-format', `refs/heads/${branch}`]).status === 0;
+}
+
+function validateReviewTargetCompatibility(
+  repoRoot: string,
+  taskDir: string,
+  target: { remote: string; baseRef: string },
+  reviewedHead: string
+): { ok: true } | { ok: false; code: string; message: string } {
+  const artifact = findAuthoritativeReviewCodeArtifact(taskDir);
+  if (!artifact.ok || !artifact.path) return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: 'A current review-code artifact is required before delivery' };
+  let content: string;
+  try { content = fs.readFileSync(artifact.path, 'utf8'); }
+  catch (error) { return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: error instanceof Error ? error.message : String(error) }; }
+  const savedReviewedHead = extractReviewedHead(content) || extractReviewBaseline(content);
+  const savedTargetHead = extractReviewTargetHead(content);
+  const savedDiffBase = extractReviewDiffBase(content);
+  if (!savedReviewedHead || !savedTargetHead || !savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_INVALID', message: 'review-code must save reviewed head, target head, and diff base before delivery' };
+  }
+  if (savedReviewedHead !== reviewedHead) {
+    return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: 'review-code reviewed head does not match last_reviewed_commit' };
+  }
+  const saved = resolveDiffBase(repoRoot, reviewedHead, savedTargetHead);
+  if (!saved.ok || saved.diffBase !== savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_INVALID', message: saved.ok ? 'saved review diff base does not match saved target head' : saved.message };
+  }
+  const currentTarget = resolveTargetHead(repoRoot, target);
+  if (!currentTarget.ok) return { ok: false, code: currentTarget.code, message: currentTarget.message };
+  const current = resolveDiffBase(repoRoot, reviewedHead, currentTarget.head!);
+  if (!current.ok) return { ok: false, code: current.code, message: current.message };
+  if (current.diffBase !== savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_CHANGED', message: 'current delivery target changed the reviewed diff base; re-run review-code' };
+  }
+  return { ok: true };
+}
+
+function failure(taskId: string | null, code: string, message: string, retryable = false, status: 'failed' | 'blocked' = retryable ? 'blocked' : 'failed'): TaskBranchDeliveryResult {
+  return { status, changed: false, taskId, remoteHead: null, localHead: null, state: null, error: { code, message, retryable } };
+}
+
+function deliverUnlocked(
+  taskId: string,
+  taskDir: string,
+  repoRoot: string,
+  options: { agent: string; remote?: string; baseRef?: string; dryRun?: boolean }
+): TaskBranchDeliveryResult {
+  let frontmatter: ReturnType<typeof parseTaskFrontmatter>;
+  try { frontmatter = parseTaskFrontmatter(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8')); }
+  catch (error) { return failure(taskId, 'TASK_CONTEXT_UNREADABLE', error instanceof Error ? error.message : String(error)); }
+  if (frontmatter.status !== 'active') return failure(taskId, 'TASK_STATE_INVALID', 'task branch delivery requires an active task');
+  const branch = frontmatter.branch ?? '';
+  if (!branch) return failure(taskId, 'DELIVERY_BRANCH_MISSING', 'task branch is missing');
+  if (!validateBranch(repoRoot, branch)) return failure(taskId, 'DELIVERY_BRANCH_INVALID', 'task branch is invalid');
+  if (!frontmatter.delivery_remote || !frontmatter.delivery_base_ref) {
+    return failure(taskId, 'DELIVERY_TARGET_MISSING', 'task delivery target is not bound; recreate or repair task metadata before delivery');
+  }
+  const target = resolveDeliveryTarget(repoRoot, {
+    remote: frontmatter.delivery_remote,
+    baseRef: frontmatter.delivery_base_ref
+  }, {
+    ...(options.remote === undefined ? {} : { remote: options.remote }),
+    ...(options.baseRef === undefined ? {} : { baseRef: options.baseRef })
+  });
+  if (!target.ok) return failure(taskId, target.code, target.message);
+  if (!validateRemote(target.value.remote) || !validateBaseRef(target.value.baseRef)) return failure(taskId, 'DELIVERY_TARGET_INVALID', 'task delivery target is invalid');
+  const localHead = gitValue(repoRoot, ['rev-parse', 'HEAD']);
+  if (!localHead) return failure(taskId, 'DELIVERY_LOCAL_HEAD_UNAVAILABLE', 'Unable to resolve local HEAD');
+  const status = git(repoRoot, ['status', '--porcelain=v1']);
+  if (status.status !== 0) return failure(taskId, 'DELIVERY_GIT_INSPECT_FAILED', status.stderr.trim() || 'Unable to inspect Git state');
+  if (status.stdout.trim()) return failure(taskId, 'DELIVERY_WORKTREE_DIRTY', 'Working tree must be clean before branch delivery');
+  const reviewed = frontmatter.last_reviewed_commit ?? '';
+  if (reviewed !== localHead) return failure(taskId, 'DELIVERY_REVIEW_REQUIRED', 'Local HEAD must equal last_reviewed_commit before delivery');
+  const reviewTarget = validateReviewTargetCompatibility(repoRoot, taskDir, target.value, reviewed);
+  if (!reviewTarget.ok) return failure(taskId, reviewTarget.code, reviewTarget.message, reviewTarget.code.includes('UNAVAILABLE'), reviewTarget.code.includes('UNAVAILABLE') ? 'blocked' : 'failed');
+  const ref = `refs/heads/${branch}`;
+  const remoteOutput = git(repoRoot, ['ls-remote', '--refs', target.value.remote, ref]);
+  if (remoteOutput.status !== 0) return failure(taskId, 'DELIVERY_REMOTE_UNAVAILABLE', remoteOutput.stderr.trim() || 'Unable to inspect the delivery remote', true);
+  const remoteHead = remoteOutput.stdout.trim().split(/\s+/)[0] || null;
+  const classification = classifyDeliveryState(localHead, remoteHead, frontmatter.delivery_remote_head ?? null);
+  if (classification.state === 'unknown-drift') return failure(taskId, 'DELIVERY_REMOTE_DRIFT', `Remote branch ${branch} has an unexpected head; refusing to overwrite it`);
+  if (options.dryRun) return { status: 'planned', changed: classification.shouldPush, taskId, remoteHead, localHead, state: classification.state, error: null };
+  if (classification.shouldPush) {
+    const args = classification.state === 'known-old'
+      ? ['push', `--force-with-lease=${ref}:${frontmatter.delivery_remote_head}`, target.value.remote, `HEAD:${ref}`]
+      : ['push', `--force-with-lease=${ref}:`, target.value.remote, `HEAD:${ref}`];
+    const pushed = git(repoRoot, args);
+    if (pushed.status !== 0) return failure(taskId, 'DELIVERY_PUSH_FAILED', pushed.stderr.trim() || 'Task branch delivery was rejected', true, 'blocked');
+  }
+  const verified = gitValue(repoRoot, ['ls-remote', '--refs', target.value.remote, ref])?.split(/\s+/)[0] ?? null;
+  if (verified !== localHead) return failure(taskId, 'DELIVERY_REMOTE_VERIFY_FAILED', `Expected remote head ${localHead}, received ${verified ?? 'unavailable'}`, true, 'blocked');
+  const written = writeTask({
+    taskRef: taskId,
+    expectedState: 'active',
+    mutations: [{ kind: 'frontmatter', set: { delivery_remote: target.value.remote, delivery_base_ref: target.value.baseRef, delivery_remote_head: localHead, assigned_to: options.agent } }]
+  }, { repoRoot, metadataProvider: captureTaskWriteMetadata });
+  if (written.status === 'failed') return failure(taskId, 'DELIVERY_TASK_SYNC_FAILED', written.error.message, true, 'blocked');
+  return { status: classification.shouldPush ? 'applied' : 'no-op', changed: classification.shouldPush || written.changed, taskId, remoteHead: localHead, localHead, state: classification.state, error: null };
+}
+
+function deliverTaskBranch(taskRef: string, options: { repoRoot?: string; agent: string; remote?: string; baseRef?: string; dryRun?: boolean }): TaskBranchDeliveryResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failure(resolved.taskId, resolved.code, resolved.message);
+  try {
+    return withRepositoryMutationLock(resolved.repoRoot, () => withTaskExecutionLock(
+      resolved.repoRoot, resolved.taskId, 'task-delivery',
+      () => deliverUnlocked(resolved.taskId, resolved.taskDir, resolved.repoRoot, options)
+    ));
+  } catch (error) {
+    return failure(resolved.taskId, 'DELIVERY_LOCK_FAILED', error instanceof Error ? error.message : String(error), true, 'blocked');
+  }
+}
+
+export { classifyDeliveryState, deliverTaskBranch };

package/lib/task/human-override.ts

@@ -24,6 +24,7 @@ import { verifyTaskEvent } from './verification.ts';
 import { verifyInProcess } from './verification-engine.ts';
 import { canonicalTimestamp, writeTask } from './write.ts';
 import type { TaskFileSystem, TaskWriteMetadata, TaskWriteResult } from './write.ts';
+import { readPrDeliveryFact } from './pr-delivery-fact.ts';
 
 type Eligibility = 'eligible' | 'repair-only' | 'runtime-recovery-only' | 'never-overridable';
 type OutcomeEffect = 'apply-target' | 'retry-same-intent' | 'record-only' | 'no-write';
@@ -614,7 +615,8 @@ function resourceForSnapshot(
     return number === null ? null : { kind: 'issue', number };
   }
   if (policy.producerId === 'platform.pull-request') {
-    const number = options.probePullRequestNumber ?? toPositiveInteger(frontmatter?.pr_number);
+    const fact = frontmatter ? readPrDeliveryFact(frontmatter) : null;
+    const number = options.probePullRequestNumber ?? (fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
     return number === null ? null : { kind: 'pull-request', number };
   }
   return null;
@@ -705,7 +707,8 @@ function probePlatformFailure(
     return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
   }
   const issueNumber = options.probeIssueNumber ?? toPositiveInteger(frontmatter.issue_number);
-  const pullRequestNumber = options.probePullRequestNumber ?? toPositiveInteger(frontmatter.pr_number);
+  const fact = readPrDeliveryFact(frontmatter);
+  const pullRequestNumber = options.probePullRequestNumber ?? (fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
   const operation = policy.producerId === 'platform.issue'
     ? issueNumber === null
       ? null

package/lib/task/lifecycle.ts

@@ -20,6 +20,7 @@ const lifecycleIntentCatalog = [
 ] as const;
 const lifecycleFailureCatalog = [
   'LIFECYCLE_DIRECTORY_RENAME_FAILED',
+  'LIFECYCLE_DIRECTORY_COPY_FAILED',
   'LIFECYCLE_DOCUMENT_INVALID',
   'LIFECYCLE_FINAL_STATE_INVALID',
   'LIFECYCLE_IDENTITY_CONFLICT',
@@ -336,6 +337,62 @@ function parseJournal(content: string): LifecycleJournal {
   return value as LifecycleJournal;
 }
 
+type DirectoryEntry = Readonly<{ relativePath: string; kind: 'file' | 'directory'; size: number; digest: string }>;
+
+function directoryManifest(root: string): DirectoryEntry[] {
+  const entries: DirectoryEntry[] = [];
+  const visit = (current: string, relative = '') => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = relative ? path.join(relative, entry.name) : entry.name;
+      const absolute = path.join(current, entry.name);
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error(`symbolic link is not allowed in lifecycle directory: ${relativePath}`);
+      if (entry.isDirectory()) {
+        entries.push({ relativePath, kind: 'directory', size: 0, digest: '' });
+        visit(absolute, relativePath);
+      } else if (entry.isFile()) {
+        const digest = createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+        entries.push({ relativePath, kind: 'file', size: stat.size, digest });
+      } else {
+        throw new Error(`unsupported lifecycle directory entry: ${relativePath}`);
+      }
+    }
+  };
+  visit(root);
+  return entries;
+}
+
+function copyDirectoryVerified(source: string, target: string): void {
+  if (fs.existsSync(target)) throw new Error(`target directory already exists: ${target}`);
+  const copy = (currentSource: string, currentTarget: string) => {
+    fs.mkdirSync(currentTarget);
+    for (const entry of fs.readdirSync(currentSource, { withFileTypes: true })) {
+      const sourcePath = path.join(currentSource, entry.name);
+      const targetPath = path.join(currentTarget, entry.name);
+      const stat = fs.lstatSync(sourcePath);
+      if (stat.isSymbolicLink()) throw new Error(`symbolic link is not allowed in lifecycle directory: ${entry.name}`);
+      if (entry.isDirectory()) copy(sourcePath, targetPath);
+      else if (entry.isFile()) fs.copyFileSync(sourcePath, targetPath);
+      else throw new Error(`unsupported lifecycle directory entry: ${entry.name}`);
+    }
+  };
+  copy(source, target);
+  const sourceManifest = directoryManifest(source);
+  const targetManifest = directoryManifest(target);
+  if (JSON.stringify(sourceManifest) !== JSON.stringify(targetManifest)) {
+    throw new Error('copied lifecycle directory failed manifest verification');
+  }
+}
+
+function removeCopiedSource(source: string, target: string): void {
+  const sourceManifest = directoryManifest(source);
+  const targetManifest = directoryManifest(target);
+  if (JSON.stringify(sourceManifest) !== JSON.stringify(targetManifest)) {
+    throw new Error('lifecycle source and target diverged before source cleanup');
+  }
+  fs.rmSync(source, { recursive: true, force: false });
+}
+
 function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLifecycleOptions = {}): TaskLifecycleResult {
   const normalized = normalizedRequest(requestInput);
   if ('code' in normalized) return failed(requestInput, normalized);
@@ -386,7 +443,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   if (!spec.sources.includes(sourceState) && !existingJournal && !allowsManualOverride(options, 'LIFECYCLE_SOURCE_INVALID')) {
     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)) {
+  if (sourcePath !== targetPath && fs.existsSync(targetPath) && !existingJournal) {
     return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   const content = io.readFileSync(currentTaskFile);
@@ -498,13 +555,45 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     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) {
+      if ((error as { code?: string }).code === 'EXDEV') {
+        try {
+          copyDirectoryVerified(sourcePath, targetPath);
+          completed.add('directory-moved');
+          journal.completedSteps = [...completed];
+          const copiedJournalPath = path.join(targetPath, '.task-lifecycle.json');
+          writeJournal(initialJournalPath, journal, io);
+          writeJournal(copiedJournalPath, journal, io);
+          removeCopiedSource(sourcePath, targetPath);
+          journalPath = copiedJournalPath;
+        } catch (copyError) {
+          if (fs.existsSync(targetPath)) fs.rmSync(targetPath, { recursive: true, force: false });
+          const failure = { code: 'LIFECYCLE_DIRECTORY_COPY_FAILED', message: String(copyError) } as const;
+          rememberJournalFailure(initialJournalPath, journal, io, failure);
+          return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+        }
+      } else {
       const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) } as const;
       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 }); }
+    }
+  }
+  if (completed.has('directory-moved') && sourcePath !== targetPath && fs.existsSync(sourcePath) && fs.existsSync(targetPath)) {
+    try {
+      removeCopiedSource(sourcePath, targetPath);
+      journalPath = path.join(targetPath, '.task-lifecycle.json');
+    } catch (error) {
+      const failure = { code: 'LIFECYCLE_DIRECTORY_COPY_FAILED', message: String(error) } as const;
+      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 });
     }
-    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 }); }
   }
   let shortId: TaskLifecycleResult['shortId'] = { effect: 'unchanged', shortId: null, changed: false };
   if (!completed.has('registry-committed')) {