worktree.status

{
  "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"
}

{
  "$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"
    },
    "Distance": {
      "description": "How many commits two refs have that the other lacks.\n\n```\nuse majordomus_cli::worktree::trunk::Distance;\nlet d = Distance { behind: 779, ahead: 0 };\nassert_eq!(serde_json::to_value(d).unwrap(), serde_json::json!({\"behind\": 779, \"ahead\": 0}));\n```",
      "properties": {
        "ahead": {
          "description": "Commits of this ref the remote trunk lacks.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "behind": {
          "description": "Commits of the remote trunk this ref lacks.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "behind",
        "ahead"
      ],
      "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"
    },
    "TrunkDistance": {
      "description": "A checkout's distance from the remote trunk, judged.\n\n```\nuse majordomus_cli::worktree::trunk::{Distance, TrunkDistance, TrunkStanding};\nlet d: TrunkDistance = serde_json::from_value(serde_json::json!({\n    \"standing\": \"stale\", \"local_trunk_standing\": \"stale\",\n    \"worktree\": \"/repo\", \"on_trunk\": true,\n    \"checkout\": {\"behind\": 779, \"ahead\": 0},\n    \"thresholds\": {\"warn_behind\": 50, \"fail_behind\": 300},\n    \"message\": \"779 commits behind origin/master\",\n})).unwrap();\nassert_eq!(d.standing, TrunkStanding::Stale);\nassert_eq!(d.checkout, Some(Distance { behind: 779, ahead: 0 }));\n// what is absent stays absent in the answer\nassert!(serde_json::to_value(&d).unwrap().get(\"remedy\").is_none());\n```",
      "properties": {
        "checkout": {
          "anyOf": [
            {
              "$ref": "#/$defs/Distance"
            },
            {
              "type": "null"
            }
          ],
          "description": "The checkout's `HEAD` against the remote trunk. While a merge is in progress, the\ncommits it brings in count as present: the commit being made will hold them, so the\nmerge that brings a checkout current is never judged by the tree it is replacing."
        },
        "fetched_at": {
          "description": "When the repository last fetched (the time of `FETCH_HEAD`), RFC 3339: the moment\nthis answer is true as of. Absent when it never fetched.",
          "type": [
            "string",
            "null"
          ]
        },
        "local_trunk": {
          "anyOf": [
            {
              "$ref": "#/$defs/Distance"
            },
            {
              "type": "null"
            }
          ],
          "description": "The local trunk branch against the remote trunk: what a branch made from the local\ntrunk starts from."
        },
        "local_trunk_standing": {
          "$ref": "#/$defs/TrunkStanding",
          "description": "Where the local trunk branch stands, judged the same way: what a branch made from it\nstarts from. The same as `standing` when the checkout holds the trunk."
        },
        "message": {
          "description": "What the standing means here, in one line.",
          "type": "string"
        },
        "on_trunk": {
          "description": "The work tree holds the trunk branch itself.",
          "type": "boolean"
        },
        "remedy": {
          "description": "The commands that bring the checkout and the local trunk current, when either is\nbehind. Suggested, never run.",
          "type": [
            "string",
            "null"
          ]
        },
        "remote_head": {
          "description": "The commit the remote-tracking trunk names.",
          "type": [
            "string",
            "null"
          ]
        },
        "remote_trunk": {
          "description": "The remote-tracking trunk counted against (`origin/master`).",
          "type": [
            "string",
            "null"
          ]
        },
        "standing": {
          "$ref": "#/$defs/TrunkStanding",
          "description": "Where the checkout stands: its `HEAD` — with the commit a merge in progress brings\nin — judged against the thresholds. This is what its server serves."
        },
        "thresholds": {
          "$ref": "#/$defs/TrunkThresholds",
          "description": "The thresholds judged against, as `checkout.trunk_distance` declares them."
        },
        "trunk": {
          "description": "The trunk branch, short.",
          "type": [
            "string",
            "null"
          ]
        },
        "worktree": {
          "description": "The work tree measured.",
          "type": "string"
        }
      },
      "required": [
        "standing",
        "local_trunk_standing",
        "worktree",
        "on_trunk",
        "thresholds",
        "message"
      ],
      "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"
        }
      ]
    },
    "TrunkStanding": {
      "description": "Where a checkout stands against the remote trunk.\n\n```\nuse majordomus_cli::worktree::trunk::TrunkStanding;\nlet s: TrunkStanding = serde_json::from_str(r#\"\"lagging\"\"#).unwrap();\nassert_eq!(s, TrunkStanding::Lagging);\nassert_eq!(serde_json::to_value(TrunkStanding::Unmeasured).unwrap(), \"unmeasured\");\n```",
      "oneOf": [
        {
          "const": "current",
          "description": "Behind by less than the warn threshold, or not behind at all.",
          "type": "string"
        },
        {
          "const": "lagging",
          "description": "At or past the warn threshold: what it serves is old enough to mislead.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "At or past the fail threshold: what it serves is the wrong tree.",
          "type": "string"
        },
        {
          "const": "unjudged",
          "description": "Behind, and the policy declares no threshold to judge the distance by.",
          "type": "string"
        },
        {
          "const": "unmeasured",
          "description": "The distance could not be measured: no trunk, no remote-tracking trunk, no `HEAD`.",
          "type": "string"
        }
      ]
    },
    "TrunkThresholds": {
      "description": "The thresholds `checkout.trunk_distance` declares, in commits behind the remote trunk.\nAbsent is absent: the reader supplies no default, and a distance with nothing to judge\nit against is reported as `unjudged`.\n\n```\nuse majordomus_cli::worktree::trunk::TrunkThresholds;\nlet t: TrunkThresholds = serde_json::from_str(r#\"{\"warn_behind\": 50, \"fail_behind\": 300}\"#).unwrap();\nassert_eq!((t.warn_behind, t.fail_behind), (Some(50), Some(300)));\nassert_eq!(TrunkThresholds::default().warn_behind, None, \"absent is not a default\");\n```",
      "properties": {
        "fail_behind": {
          "description": "At or past this many commits behind, the checkout is `stale`: a failure.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "warn_behind": {
          "description": "At or past this many commits behind, the checkout is `lagging`: a warning.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "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."
    },
    "trunk_distance": {
      "$ref": "#/$defs/TrunkDistance",
      "description": "How far this work tree and the local trunk are from the remote trunk, judged against\nthe policy's `checkout.trunk_distance`: what it would serve, and how old that is."
    },
    "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",
    "trunk_distance"
  ],
  "title": "StatusReport",
  "type": "object"
}