worktree.topology

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "description": "`SCHEMA`."
    },
    "repository": {
      "$ref": "#/$defs/RepositoryView",
      "description": "The repository."
    },
    "container": {
      "$ref": "#/$defs/ContainerView",
      "description": "The container every linked work tree belongs under."
    },
    "trunk": {
      "$ref": "#/$defs/TrunkView",
      "description": "The trunk."
    },
    "observed_from": {
      "type": "string",
      "description": "The work tree the call was answered from."
    },
    "worktrees": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/WorktreeState"
      },
      "description": "Every registered work tree, primary first."
    },
    "branches": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BranchState"
      },
      "description": "Every local branch, by name."
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TopologyDiagnostic"
      },
      "description": "Everything wrong with the topology, work trees first, then repository-wide."
    },
    "tallies": {
      "$ref": "#/$defs/TopologyTallies",
      "description": "The counts."
    },
    "valid": {
      "type": "boolean",
      "description": "No error-level diagnostic stands."
    }
  },
  "required": [
    "schema",
    "repository",
    "container",
    "trunk",
    "observed_from",
    "worktrees",
    "branches",
    "diagnostics",
    "tallies",
    "valid"
  ],
  "description": "The whole topology: what `worktree list`, the MCP resource, the HTTP route and the\nCockpit all read.",
  "title": "RepositoryTopology",
  "$defs": {
    "RepositoryView": {
      "type": "object",
      "properties": {
        "primary_worktree": {
          "type": "string",
          "description": "The primary checkout: what the container is named after."
        },
        "git_common_dir": {
          "type": "string",
          "description": "The common git directory: the repository's identity."
        },
        "name": {
          "type": "string",
          "description": "The primary checkout's directory name."
        }
      },
      "required": [
        "primary_worktree",
        "git_common_dir",
        "name"
      ],
      "description": "The repository's identity, as the topology reports it."
    },
    "ContainerView": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "The derived path."
        },
        "suffix": {
          "type": "string",
          "description": "The suffix it was derived with."
        },
        "exists": {
          "type": "boolean",
          "description": "It exists on disk. Created by the first worktree that needs it."
        }
      },
      "required": [
        "path",
        "suffix",
        "exists"
      ],
      "description": "The container, as the topology reports it."
    },
    "TrunkView": {
      "type": "object",
      "properties": {
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The branch, when known."
        },
        "source": {
          "$ref": "#/$defs/TrunkSource",
          "description": "How it was decided."
        },
        "checked_out_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where it is checked out."
        }
      },
      "required": [
        "source"
      ],
      "description": "The trunk, as the topology reports it."
    },
    "TrunkSource": {
      "oneOf": [
        {
          "type": "string",
          "const": "remote_head",
          "description": "`refs/remotes/<remote>/HEAD`: what the remote calls its default branch."
        },
        {
          "type": "string",
          "const": "default_branch_config",
          "description": "`init.defaultBranch` in the git configuration, and that branch exists locally."
        },
        {
          "type": "string",
          "const": "conventional_name",
          "description": "Exactly one of `main` and `master` exists locally."
        },
        {
          "type": "string",
          "const": "primary_checkout",
          "description": "The branch the primary checkout holds, because nothing else said."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "Nothing said; the trunk is unknown and every check that needs it says so."
        }
      ],
      "description": "Where the trunk was learned from, in the order it is looked for."
    },
    "WorktreeState": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Absolute, as git holds it."
        },
        "kind": {
          "$ref": "#/$defs/WorktreeKind",
          "description": "Primary or linked."
        },
        "standing": {
          "$ref": "#/$defs/Standing",
          "description": "Where it stands against the topology."
        },
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The branch checked out here, short. Absent when detached."
        },
        "label": {
          "type": "string",
          "description": "The name it is shown under: the branch, or `detached/<short commit>`."
        },
        "head": {
          "type": [
            "string",
            "null"
          ],
          "description": "The commit checked out here."
        },
        "detached": {
          "type": "boolean",
          "description": "HEAD is detached here."
        },
        "expected_path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where this branch's work tree belongs. Absent when detached, or for the primary\ncheckout on the trunk."
        },
        "exists": {
          "type": "boolean",
          "description": "The directory git registered still exists on disk."
        },
        "current": {
          "type": "boolean",
          "description": "The call came from inside this work tree."
        },
        "locked": {
          "type": [
            "string",
            "null"
          ],
          "description": "Locked, with git's reason; an empty string when it recorded none."
        },
        "prunable": {
          "type": [
            "string",
            "null"
          ],
          "description": "Prunable, with git's reason."
        },
        "dirty": {
          "anyOf": [
            {
              "$ref": "#/$defs/DirtyState"
            },
            {
              "type": "null"
            }
          ],
          "description": "Uncommitted work here. Absent when it was not asked for: it costs one subprocess per\nwork tree, and a topology check does not need it."
        },
        "upstream": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpstreamState"
            },
            {
              "type": "null"
            }
          ],
          "description": "The branch's upstream and its distance from it."
        },
        "issue": {
          "type": [
            "string",
            "null"
          ],
          "description": "The issue this branch provably names: a path component of the branch equal to an\nissue id of `.ai/repo/project/issues/`, or beginning with it and a hyphen. Nothing\nis inferred from similarity."
        },
        "diagnostics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TopologyDiagnostic"
          },
          "description": "What is wrong with this work tree, if anything."
        }
      },
      "required": [
        "path",
        "kind",
        "standing",
        "label",
        "detached",
        "exists",
        "current",
        "diagnostics"
      ],
      "description": "One work tree, as the topology sees it."
    },
    "WorktreeKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "primary",
          "description": "The main work tree. It hosts the trunk, is never moved and is never removed."
        },
        {
          "type": "string",
          "const": "linked",
          "description": "A linked work tree. Belongs at its branch's canonical path."
        }
      ],
      "description": "Whether a work tree is the repository's own checkout or one linked to it."
    },
    "Standing": {
      "oneOf": [
        {
          "type": "string",
          "const": "primary",
          "description": "The primary checkout: exempt from the path rule, held to the trunk rule."
        },
        {
          "type": "string",
          "const": "canonical",
          "description": "A linked work tree at exactly its branch's canonical path."
        },
        {
          "type": "string",
          "const": "misplaced",
          "description": "A linked work tree somewhere else. Migration brings it home."
        },
        {
          "type": "string",
          "const": "detached",
          "description": "A linked work tree with no branch. It has no canonical path and is never moved."
        },
        {
          "type": "string",
          "const": "ephemeral",
          "description": "A linked work tree under the operating system's temporary directory or under the\nprimary checkout's `.claude/worktrees/`: a session's scratch checkout, owned and\nremoved by the harness that made it. Reported; migrated only on request."
        },
        {
          "type": "string",
          "const": "missing",
          "description": "A registration whose directory is gone. Repair drops it."
        }
      ],
      "description": "Where a work tree stands against the topology."
    },
    "DirtyState": {
      "type": "object",
      "properties": {
        "staged": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Entries with a change in the index."
        },
        "unstaged": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Entries with a change in the work tree that is not in the index."
        },
        "untracked": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Untracked, not ignored, files."
        },
        "conflicted": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Entries with an unresolved merge conflict."
        },
        "clean": {
          "type": "boolean",
          "description": "Nothing above is non-zero."
        },
        "in_progress": {
          "type": [
            "string",
            "null"
          ],
          "description": "A merge, rebase, cherry-pick, revert or bisect is in progress here."
        }
      },
      "required": [
        "staged",
        "unstaged",
        "untracked",
        "conflicted",
        "clean"
      ],
      "description": "Uncommitted work in a work tree, counted from `git status --porcelain`. Untracked\ncontent counts: it is exactly what a careless move loses."
    },
    "UpstreamState": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The upstream ref, short (`origin/master`)."
        },
        "ahead": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint",
          "minimum": 0,
          "description": "Commits here that the upstream lacks."
        },
        "behind": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint",
          "minimum": 0,
          "description": "Commits upstream that this branch lacks."
        },
        "gone": {
          "type": "boolean",
          "description": "The upstream ref no longer exists."
        }
      },
      "required": [
        "name",
        "gone"
      ],
      "description": "A branch's upstream and how far the two have moved apart, from `for-each-ref` in one\nsubprocess for every branch, never a fetch."
    },
    "TopologyDiagnostic": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/DiagnosticCode",
          "description": "The stable code."
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How serious it is."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "The work tree involved."
        },
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The branch involved."
        },
        "expected": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where the work tree belongs."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, in one line."
        },
        "remedy": {
          "type": "string",
          "description": "The command that addresses it."
        }
      },
      "required": [
        "code",
        "severity",
        "message",
        "remedy"
      ],
      "description": "One thing wrong with, or worth knowing about, the topology."
    },
    "DiagnosticCode": {
      "oneOf": [
        {
          "type": "string",
          "const": "worktree.path_mismatch",
          "description": "A linked work tree is not at its branch's canonical path."
        },
        {
          "type": "string",
          "const": "worktree.container_occupied",
          "description": "A linked work tree occupies the container path itself."
        },
        {
          "type": "string",
          "const": "worktree.nested",
          "description": "A linked work tree sits inside the primary checkout or inside another work tree."
        },
        {
          "type": "string",
          "const": "worktree.destination_conflict",
          "description": "The canonical path of a branch is occupied by something that is not its work tree."
        },
        {
          "type": "string",
          "const": "worktree.missing",
          "description": "A registered work tree's directory does not exist."
        },
        {
          "type": "string",
          "const": "worktree.stale_registration",
          "description": "Git reports the registration as prunable."
        },
        {
          "type": "string",
          "const": "worktree.branch_already_checked_out",
          "description": "A branch is checked out somewhere other than its canonical path."
        },
        {
          "type": "string",
          "const": "worktree.detached",
          "description": "A linked work tree has no branch."
        },
        {
          "type": "string",
          "const": "worktree.ephemeral",
          "description": "A linked work tree is a session's scratch checkout: under the temporary directory or\nunder the primary checkout's `.claude/worktrees/`."
        },
        {
          "type": "string",
          "const": "worktree.primary_on_non_trunk",
          "description": "The primary checkout holds a branch that is not the trunk."
        },
        {
          "type": "string",
          "const": "worktree.trunk_in_linked_worktree",
          "description": "The trunk is checked out in a linked work tree rather than the primary checkout."
        },
        {
          "type": "string",
          "const": "worktree.path_escape",
          "description": "A derived path would leave the container. Cannot happen for a valid branch name."
        },
        {
          "type": "string",
          "const": "worktree.invalid_branch_name",
          "description": "A branch name git accepted that this executable cannot derive a path for."
        },
        {
          "type": "string",
          "const": "worktree.locked",
          "description": "A work tree is locked, so it cannot be moved until it is unlocked."
        },
        {
          "type": "string",
          "const": "worktree.migration_verification_failed",
          "description": "A move happened and the fingerprint after it differs from the one before."
        },
        {
          "type": "string",
          "const": "worktree.trunk_unknown",
          "description": "The trunk could not be determined."
        },
        {
          "type": "string",
          "const": "worktree.case_collision",
          "description": "Two branch names map to one directory on a case-insensitive filesystem."
        },
        {
          "type": "string",
          "const": "worktree.cross_device",
          "description": "A move crossed devices and was made by copy, repair and verification."
        }
      ],
      "description": "The stable machine name of everything that can be wrong with the topology. One code per\ncondition, reused by the command line, the API, MCP, the Cockpit, the tests and the\ndocumentation; the prose beside a code is rendered from the typed state."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    },
    "BranchState": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The branch, short."
        },
        "head": {
          "type": "string",
          "description": "The commit it points at."
        },
        "trunk": {
          "type": "boolean",
          "description": "This branch is the trunk."
        },
        "expected_path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where its work tree belongs."
        },
        "worktree": {
          "type": [
            "string",
            "null"
          ],
          "description": "Where it is checked out, when it is."
        },
        "upstream": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpstreamState"
            },
            {
              "type": "null"
            }
          ],
          "description": "The upstream and its distance."
        },
        "merged_into_trunk": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Reachable from the trunk. Absent when the trunk is unknown."
        },
        "cleanup_eligible": {
          "type": "boolean",
          "description": "Merged into the trunk, not the trunk, and either not checked out or checked out in a\nwork tree known to be clean. Derived state, never acted on automatically."
        },
        "issue": {
          "type": [
            "string",
            "null"
          ],
          "description": "The issue this branch provably names."
        }
      },
      "required": [
        "name",
        "head",
        "trunk",
        "cleanup_eligible"
      ],
      "description": "One local branch, with or without a work tree."
    },
    "TopologyTallies": {
      "type": "object",
      "properties": {
        "worktrees": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Every registered work tree, primary included."
        },
        "canonical": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Linked work trees at their canonical path."
        },
        "misplaced": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Linked work trees somewhere else."
        },
        "detached": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Linked work trees without a branch."
        },
        "ephemeral": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Scratch checkouts of a session."
        },
        "missing": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Registrations whose directory is gone."
        },
        "locked": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Work trees git reports as locked."
        },
        "dirty": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Work trees with uncommitted work, when it was asked for."
        },
        "branches": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Local branches."
        },
        "branches_without_worktree": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Local branches with no work tree."
        },
        "cleanup_eligible": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Branches eligible for cleanup."
        },
        "errors": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Error-level diagnostics."
        },
        "warnings": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Warning-level diagnostics."
        }
      },
      "required": [
        "worktrees",
        "canonical",
        "misplaced",
        "detached",
        "ephemeral",
        "missing",
        "locked",
        "dirty",
        "branches",
        "branches_without_worktree",
        "cleanup_eligible",
        "errors",
        "warnings"
      ],
      "description": "How many work trees and branches are in each state."
    }
  }
}