worktree.topology

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

{
  "$defs": {
    "BranchState": {
      "description": "One local branch, with or without a work tree.",
      "properties": {
        "cleanup_eligible": {
          "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.",
          "type": "boolean"
        },
        "expected_path": {
          "description": "Where its work tree belongs.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "The commit it points at.",
          "type": "string"
        },
        "issue": {
          "description": "The issue this branch provably names.",
          "type": [
            "string",
            "null"
          ]
        },
        "merged_into_trunk": {
          "description": "Reachable from the trunk. Absent when the trunk is unknown.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "name": {
          "description": "The branch, short.",
          "type": "string"
        },
        "trunk": {
          "description": "This branch is the trunk.",
          "type": "boolean"
        },
        "upstream": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpstreamState"
            },
            {
              "type": "null"
            }
          ],
          "description": "The upstream and its distance."
        },
        "worktree": {
          "description": "Where it is checked out, when it is.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "head",
        "trunk",
        "cleanup_eligible"
      ],
      "type": "object"
    },
    "ContainerView": {
      "description": "The container, as the topology reports it.",
      "properties": {
        "exists": {
          "description": "It exists on disk. Created by the first worktree that needs it.",
          "type": "boolean"
        },
        "path": {
          "description": "The derived path.",
          "type": "string"
        },
        "suffix": {
          "description": "The suffix it was derived with.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "suffix",
        "exists"
      ],
      "type": "object"
    },
    "DiagnosticCode": {
      "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.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "DirtyState": {
      "description": "Uncommitted work in a work tree, counted from `git status --porcelain`. Untracked\ncontent counts: it is exactly what a careless move loses.",
      "properties": {
        "clean": {
          "description": "Nothing above is non-zero.",
          "type": "boolean"
        },
        "conflicted": {
          "description": "Entries with an unresolved merge conflict.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "in_progress": {
          "description": "A merge, rebase, cherry-pick, revert or bisect is in progress here.",
          "type": [
            "string",
            "null"
          ]
        },
        "staged": {
          "description": "Entries with a change in the index.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "unstaged": {
          "description": "Entries with a change in the work tree that is not in the index.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "untracked": {
          "description": "Untracked, not ignored, files.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "staged",
        "unstaged",
        "untracked",
        "conflicted",
        "clean"
      ],
      "type": "object"
    },
    "RepositoryView": {
      "description": "The repository's identity, as the topology reports it.",
      "properties": {
        "git_common_dir": {
          "description": "The common git directory: the repository's identity.",
          "type": "string"
        },
        "name": {
          "description": "The primary checkout's directory name.",
          "type": "string"
        },
        "primary_worktree": {
          "description": "The primary checkout: what the container is named after.",
          "type": "string"
        }
      },
      "required": [
        "primary_worktree",
        "git_common_dir",
        "name"
      ],
      "type": "object"
    },
    "Severity": {
      "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.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "Standing": {
      "description": "Where a work tree stands against the topology.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "TopologyDiagnostic": {
      "description": "One thing wrong with, or worth knowing about, the topology.",
      "properties": {
        "branch": {
          "description": "The branch involved.",
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "$ref": "#/$defs/DiagnosticCode",
          "description": "The stable code."
        },
        "expected": {
          "description": "Where the work tree belongs.",
          "type": [
            "string",
            "null"
          ]
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "path": {
          "description": "The work tree involved.",
          "type": [
            "string",
            "null"
          ]
        },
        "remedy": {
          "description": "The command that addresses it.",
          "type": "string"
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How serious it is."
        }
      },
      "required": [
        "code",
        "severity",
        "message",
        "remedy"
      ],
      "type": "object"
    },
    "TopologyTallies": {
      "description": "How many work trees and branches are in each state.",
      "properties": {
        "branches": {
          "description": "Local branches.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "branches_without_worktree": {
          "description": "Local branches with no work tree.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "canonical": {
          "description": "Linked work trees at their canonical path.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "cleanup_eligible": {
          "description": "Branches eligible for cleanup.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "detached": {
          "description": "Linked work trees without a branch.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "dirty": {
          "description": "Work trees with uncommitted work, when it was asked for.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "ephemeral": {
          "description": "Scratch checkouts of a session.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "errors": {
          "description": "Error-level diagnostics.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "locked": {
          "description": "Work trees git reports as locked.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "misplaced": {
          "description": "Linked work trees somewhere else.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "missing": {
          "description": "Registrations whose directory is gone.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "warnings": {
          "description": "Warning-level diagnostics.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "worktrees": {
          "description": "Every registered work tree, primary included.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "worktrees",
        "canonical",
        "misplaced",
        "detached",
        "ephemeral",
        "missing",
        "locked",
        "dirty",
        "branches",
        "branches_without_worktree",
        "cleanup_eligible",
        "errors",
        "warnings"
      ],
      "type": "object"
    },
    "TrunkSource": {
      "description": "Where the trunk was learned from, in the order it is looked for.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "TrunkView": {
      "description": "The trunk, as the topology reports it.",
      "properties": {
        "branch": {
          "description": "The branch, when known.",
          "type": [
            "string",
            "null"
          ]
        },
        "checked_out_at": {
          "description": "Where it is checked out.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "$ref": "#/$defs/TrunkSource",
          "description": "How it was decided."
        }
      },
      "required": [
        "source"
      ],
      "type": "object"
    },
    "UpstreamState": {
      "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.",
      "properties": {
        "ahead": {
          "description": "Commits here that the upstream lacks.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "behind": {
          "description": "Commits upstream that this branch lacks.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "gone": {
          "description": "The upstream ref no longer exists.",
          "type": "boolean"
        },
        "name": {
          "description": "The upstream ref, short (`origin/master`).",
          "type": "string"
        }
      },
      "required": [
        "name",
        "gone"
      ],
      "type": "object"
    },
    "WorktreeKind": {
      "description": "Whether a work tree is the repository's own checkout or one linked to it.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "WorktreeState": {
      "description": "One work tree, as the topology sees it.",
      "properties": {
        "branch": {
          "description": "The branch checked out here, short. Absent when detached.",
          "type": [
            "string",
            "null"
          ]
        },
        "current": {
          "description": "The call came from inside this work tree.",
          "type": "boolean"
        },
        "detached": {
          "description": "HEAD is detached here.",
          "type": "boolean"
        },
        "diagnostics": {
          "description": "What is wrong with this work tree, if anything.",
          "items": {
            "$ref": "#/$defs/TopologyDiagnostic"
          },
          "type": "array"
        },
        "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."
        },
        "exists": {
          "description": "The directory git registered still exists on disk.",
          "type": "boolean"
        },
        "expected_path": {
          "description": "Where this branch's work tree belongs. Absent when detached, or for the primary\ncheckout on the trunk.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "The commit checked out here.",
          "type": [
            "string",
            "null"
          ]
        },
        "issue": {
          "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.",
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "$ref": "#/$defs/WorktreeKind",
          "description": "Primary or linked."
        },
        "label": {
          "description": "The name it is shown under: the branch, or `detached/<short commit>`.",
          "type": "string"
        },
        "locked": {
          "description": "Locked, with git's reason; an empty string when it recorded none.",
          "type": [
            "string",
            "null"
          ]
        },
        "path": {
          "description": "Absolute, as git holds it.",
          "type": "string"
        },
        "prunable": {
          "description": "Prunable, with git's reason.",
          "type": [
            "string",
            "null"
          ]
        },
        "standing": {
          "$ref": "#/$defs/Standing",
          "description": "Where it stands against the topology."
        },
        "upstream": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpstreamState"
            },
            {
              "type": "null"
            }
          ],
          "description": "The branch's upstream and its distance from it."
        }
      },
      "required": [
        "path",
        "kind",
        "standing",
        "label",
        "detached",
        "exists",
        "current",
        "diagnostics"
      ],
      "type": "object"
    }
  },
  "description": "The whole topology: what `worktree list`, the MCP resource, the HTTP route and the\nCockpit all read.",
  "properties": {
    "branches": {
      "description": "Every local branch, by name.",
      "items": {
        "$ref": "#/$defs/BranchState"
      },
      "type": "array"
    },
    "container": {
      "$ref": "#/$defs/ContainerView",
      "description": "The container every linked work tree belongs under."
    },
    "diagnostics": {
      "description": "Everything wrong with the topology, work trees first, then repository-wide.",
      "items": {
        "$ref": "#/$defs/TopologyDiagnostic"
      },
      "type": "array"
    },
    "observed_from": {
      "description": "The work tree the call was answered from.",
      "type": "string"
    },
    "repository": {
      "$ref": "#/$defs/RepositoryView",
      "description": "The repository."
    },
    "schema": {
      "description": "`SCHEMA`.",
      "type": "string"
    },
    "tallies": {
      "$ref": "#/$defs/TopologyTallies",
      "description": "The counts."
    },
    "trunk": {
      "$ref": "#/$defs/TrunkView",
      "description": "The trunk."
    },
    "valid": {
      "description": "No error-level diagnostic stands.",
      "type": "boolean"
    },
    "worktrees": {
      "description": "Every registered work tree, primary first.",
      "items": {
        "$ref": "#/$defs/WorktreeState"
      },
      "type": "array"
    }
  },
  "required": [
    "schema",
    "repository",
    "container",
    "trunk",
    "observed_from",
    "worktrees",
    "branches",
    "diagnostics",
    "tallies",
    "valid"
  ],
  "title": "RepositoryTopology",
  "type": "object"
}