worktree.inspect

{
  "additionalProperties": false,
  "description": "A branch to inspect.",
  "properties": {
    "branch": {
      "description": "The branch, full name (`feature/improve-cli`). It need not exist: the canonical path\nderives from the name alone.",
      "type": "string"
    }
  },
  "required": [
    "branch"
  ],
  "title": "InspectInput",
  "type": "object"
}

{
  "$defs": {
    "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"
    },
    "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"
    },
    "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": "One branch, inspected: where its work tree belongs and what is there.",
  "properties": {
    "branch": {
      "description": "The branch asked about.",
      "type": "string"
    },
    "branch_exists": {
      "description": "The branch exists locally.",
      "type": "boolean"
    },
    "canonical": {
      "description": "The branch is checked out at its canonical path.",
      "type": "boolean"
    },
    "destination_exists": {
      "description": "Something exists at that path.",
      "type": "boolean"
    },
    "diagnostics": {
      "description": "What stands in the way, if anything.",
      "items": {
        "$ref": "#/$defs/TopologyDiagnostic"
      },
      "type": "array"
    },
    "expected_path": {
      "description": "Where its work tree belongs.",
      "type": "string"
    },
    "worktree": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorktreeState"
        },
        {
          "type": "null"
        }
      ],
      "description": "The work tree that holds the branch, when one does."
    }
  },
  "required": [
    "branch",
    "branch_exists",
    "expected_path",
    "destination_exists",
    "canonical",
    "diagnostics"
  ],
  "title": "InspectReport",
  "type": "object"
}