Yeachan-Heo/oh-my-codex · error · Error

scale_down_cleanup_debt_invalid_worktree_target:${worker.nam

Error message

scale_down_cleanup_debt_invalid_worktree_target:${worker.name}

What it means

A worker's worktree target metadata has invalid types or an invalid combination: worktree_path must be an absolute normalized path matching the expected location, and repo_root/branch must be strings, detached/created booleans; worktree_created=true requires repo_root string and detached boolean. Message embeds worker name.

Source

Thrown at src/team/scaling.ts:1605

        throw new Error(`scale_down_cleanup_debt_invalid_worktree_metadata:${worker.name}`);
      }
      continue;
    }

    const expectedWorktreePath = join(repoRoot, '.omx', 'team', teamName, 'worktrees', worker.name);
    if (!isAbsolute(worker.worktree_path) || worker.worktree_path !== resolve(worker.worktree_path)
      || resolve(worker.worktree_path) !== expectedWorktreePath
      || (worker.worktree_repo_root !== undefined && (
        !isAbsolute(worker.worktree_repo_root)
        || worker.worktree_repo_root !== resolve(worker.worktree_repo_root)
        || resolve(worker.worktree_repo_root) !== repoRoot
      ))
      || (worker.worktree_detached !== undefined && typeof worker.worktree_detached !== 'boolean')
      || (worker.worktree_created !== undefined && typeof worker.worktree_created !== 'boolean')
      || (worker.worktree_created === true && (
        typeof worker.worktree_repo_root !== 'string' || typeof worker.worktree_detached !== 'boolean'
      ))) {
      throw new Error(`scale_down_cleanup_debt_invalid_worktree_target:${worker.name}`);
    }
    await assertExistingPathParentContained(expectedWorktreePath, repoRoot);
    if (existsSync(expectedWorktreePath) && await realpath(expectedWorktreePath) !== expectedWorktreePath) {
      throw new Error(`scale_down_cleanup_debt_worktree_symlink:${worker.name}`);
    }
  }
}

async function cleanupScaleDownResources(
  teamName: string,
  teamStateRoot: string,
  workers: readonly ScaleDownCleanupDebtResource[],
): Promise<void> {
  for (const worker of workers) {
    // An absent exact worktree means a prior cleanup completed before crashing.
    // Do not replay a restoration or git removal against a replacement path.
    if (worker.worktree_path && existsSync(worker.worktree_path)) {
      await removeWorkerWorktreeRootAgentsFile(

View on GitHub (pinned to 3ad79a8a6f)

Solutions

  1. Compare the recorded worktree_path against <repoRoot>/.omx/team/<team>/worktrees/<worker> and correct the config or move the repo back
  2. Fix type inconsistencies (branch as non-string, detached as non-boolean) in the worker record
  3. Delete the stale worker record and re-add the worker via scaleUp to regenerate valid metadata
Defensive patterns

Strategy: validation

Validate before calling

import { isAbsolute, join, resolve } from 'node:path';
function validWorktreeTarget(w: WorkerInfo, repoRoot: string, teamName: string): boolean {
  const expected = join(repoRoot, '.omx', 'team', teamName, 'worktrees', w.name);
  return w.worktree_path === expected && isAbsolute(w.worktree_path) && w.worktree_path === resolve(w.worktree_path);
}

Try / catch

catch (e) {
  const m = /scale_down_cleanup_debt_invalid_worktree_target:(.+)$/.exec(String((e as Error).message));
  if (m) { await repairWorktreeRecord(team, m[1]); return retryScaleDown(); }
  throw e;
}

Prevention

When it happens

Trigger: validateScaleDownCleanupResources finds worktree_path defined but wrong type/shape, not matching join(repoRoot,'.omx','team',teamName,'worktrees',worker.name), or the created/repo_root/detached combination is inconsistent.

Common situations: Repo moved so the recorded absolute worktree_path no longer matches the expected location; hand-edited or corrupted team config; version upgrade changing worktree layout conventions.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/0250ee02e7e1d934. Report an issue: GitHub.