{"record":{"id":"9d7165ab30e7ee20","repo":"coleam00/Archon","slug":"worktree-branch-env-branch-name-is-not-based","errorCode":null,"errorMessage":"Worktree branch '${env.branch_name}' is not based on '${baseBranch}'. Recreate with: archon complete ${env.branch_name} --force","messagePattern":"Worktree branch '(.+?)' is not based on '(.+?)'\\. Recreate with: archon complete (.+?) --force","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/isolation/src/resolver.ts","lineNumber":253,"sourceCode":"   * Returns a warning string if mismatched, empty array otherwise.\n   * Never throws — validation errors are non-blocking.\n   */\n  private async collectBaseBranchWarnings(\n    env: IsolationEnvironmentRow,\n    baseBranch: BranchName | undefined,\n    logContext: Record<string, unknown>\n  ): Promise<string[]> {\n    if (!baseBranch) return [];\n    try {\n      const isValid = await isAncestorOf(toWorktreePath(env.working_path), `origin/${baseBranch}`);\n      if (!isValid) {\n        getLog().warn(\n          { ...logContext, branchName: env.branch_name, baseBranch },\n          'isolation.reuse_base_branch_mismatch'\n        );\n        return [\n          `Worktree branch '${env.branch_name}' is not based on '${baseBranch}'. ` +\n            `Recreate with: archon complete ${env.branch_name} --force`,\n        ];\n      }\n    } catch (err) {\n      getLog().warn(\n        { err, ...logContext, branchName: env.branch_name, baseBranch },\n        'isolation.reuse_base_branch_check_failed'\n      );\n    }\n    return [];\n  }\n\n  /**\n   * Check if an existing environment reference is still valid.\n   */\n  private async checkExisting(\n    envId: string,\n    baseBranch?: BranchName\n  ): Promise<IsolationResolution | null> {","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/isolation/src/resolver.ts#L235-L271","documentation":"resolver.collectBaseBranchWarnings checks whether an existing environment's worktree branch is actually based on the workflow's expected base branch. If the merge-base check shows it is not, the environment is reused only with this warning telling the operator the branch lineage diverges from the requested base and how to force a recreation.","triggerScenarios":"Reusing an environment whose branch_name was created from a different base than baseBranch (e.g. repo default changed, or the branch predates a workflow-base switch).","commonSituations":"Changing the workflow's base branch config while old environments exist; long-lived branches created before a rebase or default-branch rename; running `archon complete <branch>` normally instead of --force.","solutions":["Recreate the environment as the message says: `archon complete <branch> --force`.","Verify the intended base with `git merge-base <branch> <baseBranch>` and rebase the branch onto it.","Update the workflow's base-branch configuration if the expectation, not the branch, is wrong."],"exampleFix":"// before\narchon complete fix-auth   # reuses env, warns base mismatch\n// after\narchon complete fix-auth --force   # recreates branch from current base","handlingStrategy":"validation","validationCode":"const base = await git(['merge-base', branchName, baseBranch], repoPath);\nconst tip = await git(['rev-parse', baseBranch], repoPath);\nconst isBased = (await git(['rev-parse', `${base}^{commit}`], repoPath)) !== '' ;\n// lineage check: ensure branch fork point is an ancestor of current base tip\nconst ok = await git(['merge-base', '--is-ancestor', base.trim(), tip.trim()]);","typeGuard":null,"tryCatchPattern":"const warnings = resolver.warnings(env);\nif (warnings.some(w => w.includes('is not based on'))) {\n  // recreate: archon complete <branch> --force\n}","preventionTips":["Recreate environments after changing the workflow base branch.","Run `archon complete <branch> --force` when in doubt about lineage.","Keep environment branches short-lived and derived from the current base."],"tags":["git","worktree","branch-lineage","environment-reuse"],"backgroundTag":"branch-base-mismatch","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}