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

scale_down_cleanup_debt_invalid_team_state_root:${worker.nam

Error message

scale_down_cleanup_debt_invalid_team_state_root:${worker.name}

What it means

A worker record's team_state_root fails validation: it must be an absolute, already-resolved path exactly equal to the canonical team state root. The message embeds the worker name.

Source

Thrown at src/team/scaling.ts:1582

  const repoRootResult = spawnSync('git', ['rev-parse', '--show-toplevel'], {
    cwd: leaderCwd,
    encoding: 'utf-8',
    windowsHide: true,
  });
  const reportedRepoRoot = (repoRootResult.stdout || '').trim();
  if (repoRootResult.status === 0 && reportedRepoRoot) {
    repoRoot = await realpath(resolve(reportedRepoRoot));
  }
  const canonicalTeamStateRoot = await realpath(resolve(teamStateRoot));
  const expectedWorkerRoot = join(canonicalTeamStateRoot, 'team', teamName, 'workers');

  for (const worker of workers) {
    const expectedWorkerDirectory = join(expectedWorkerRoot, worker.name);
    await assertExistingPathParentContained(expectedWorkerDirectory, canonicalTeamStateRoot);
    if (worker.team_state_root !== undefined
      && (!isAbsolute(worker.team_state_root) || worker.team_state_root !== resolve(worker.team_state_root)
        || resolve(worker.team_state_root) !== canonicalTeamStateRoot)) {
      throw new Error(`scale_down_cleanup_debt_invalid_team_state_root:${worker.name}`);
    }
    if (worker.worktree_path === undefined) {
      if (worker.worktree_repo_root !== undefined || worker.worktree_branch !== undefined
        || worker.worktree_detached !== undefined || worker.worktree_created !== undefined) {
        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')

View on GitHub (pinned to 3ad79a8a6f)

Solutions

  1. Inspect the worker record in the team config and fix team_state_root to the exact canonical absolute path
  2. If the team state root moved, update all worker records (or regenerate the config) to the new canonical path
  3. On macOS, watch for /var -> /private/var symlink resolution differences; store the realpath
Defensive patterns

Strategy: validation

Validate before calling

import { isAbsolute, resolve } from 'node:path';
import { realpathSync } from 'node:fs';
function validTeamStateRoot(workerRoot: string | undefined, canonicalRoot: string): boolean {
  return workerRoot === undefined
    || (isAbsolute(workerRoot) && workerRoot === resolve(workerRoot) && resolve(workerRoot) === realpathSync(canonicalRoot));
}

Try / catch

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

Prevention

When it happens

Trigger: validateScaleDownCleanupResources sees worker.team_state_root defined but non-absolute, non-normalized, or resolving to a different directory than the canonical root.

Common situations: Team state moved or the config was hand-edited; macOS /var vs /private/var or case differences (Windows) causing resolve() mismatch; stale config from an older version storing relative roots.

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/5a28c1a762385de0. Report an issue: GitHub.