worktree.status

One worktree — the repository's own, or the one holding the directory the caller names — with its standing, its branch, its canonical path, its uncommitted work counted, whether it is where it belongs, and how many errors the whole topology carries. What an agent reads before it starts, and what the guard decides on.

query
behaviorally_verified
module worktree
#worktree
#git
#topology

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_worktree_status
HTTP	GET /api/v1/worktrees/status operationId worktree.status
command line	majordomus worktree status

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · StatusInput

Where to answer from.

property	type	required	description
path	string \| null	no	A directory inside one of this repository's worktrees; the answer is about that worktree. Relative to the primary checkout when relative (`.` is the primary checkout itself). Default: the repository the server was started for. A path in another repository is refused: the topology answers only about its own.

JSON Schema

{
  "additionalProperties": false,
  "description": "Where to answer from.",
  "properties": {
    "path": {
      "description": "A directory inside one of this repository's worktrees; the answer is about that\nworktree. Relative to the primary checkout when relative (`.` is the primary\ncheckout itself). Default: the repository the server was started for. A path in\nanother repository is refused: the topology answers only about its own.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "StatusInput",
  "type": "object"
}

output · StatusReport

The answer to "where am I, and is that where I belong".

property	type	required	description
canonical	boolean	yes	Whether this work tree is where it belongs: canonical, or the primary checkout on the trunk, or detached.
container	reference	yes	The container.
repository	reference	yes	The repository.
repository_errors	integer	yes	How many error-level diagnostics the whole topology carries.
schema	string	yes	[`SCHEMA`].
trunk	reference	yes	The trunk.
worktree	reference	yes	The work tree the call came from, with its uncommitted work counted.

JSON Schema

{
  "$defs": {
    "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"
    },
    "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 answer to \"where am I, and is that where I belong\".",
  "properties": {
    "canonical": {
      "description": "Whether this work tree is where it belongs: canonical, or the primary checkout on\nthe trunk, or detached.",
      "type": "boolean"
    },
    "container": {
      "$ref": "#/$defs/ContainerView",
      "description": "The container."
    },
    "repository": {
      "$ref": "#/$defs/RepositoryView",
      "description": "The repository."
    },
    "repository_errors": {
      "description": "How many error-level diagnostics the whole topology carries.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "schema": {
      "description": "[`SCHEMA`].",
      "type": "string"
    },
    "trunk": {
      "$ref": "#/$defs/TrunkView",
      "description": "The trunk."
    },
    "worktree": {
      "$ref": "#/$defs/WorktreeState",
      "description": "The work tree the call came from, with its uncommitted work counted."
    }
  },
  "required": [
    "schema",
    "repository",
    "container",
    "trunk",
    "worktree",
    "canonical",
    "repository_errors"
  ],
  "title": "StatusReport",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	2	default primary-checkout
mcp	covered	2	default primary-checkout
http	covered	2	default primary-checkout