worktree.trunk

The checkout's `HEAD` and the local trunk branch, each counted against the remote-tracking trunk — commits behind and ahead, a merge in progress counting what it brings in — as of the last fetch, whose time is part of the answer; judged against the policy's `checkout.trunk_distance` as `current`, `lagging`, `stale`, `unjudged` (no threshold declared) or `unmeasured` (no remote trunk), with the commands that bring it current. What doctor renders and what `server.status` and the MCP instructions say about the tree a server serves (`project.a-checkout-serves-the-current-trunk`). Fetches nothing and writes nothing.

query
behaviorally_verified
module worktree
#worktree
#git
#freshness
#introspection

Exposure

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

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

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 · TrunkDistance

A checkout's distance from the remote trunk, judged.

use majordomus_cli::worktree::trunk::{Distance, TrunkDistance, TrunkStanding};
let d: TrunkDistance = serde_json::from_value(serde_json::json!({
    "standing": "stale", "local_trunk_standing": "stale",
    "worktree": "/repo", "on_trunk": true,
    "checkout": {"behind": 779, "ahead": 0},
    "thresholds": {"warn_behind": 50, "fail_behind": 300},
    "message": "779 commits behind origin/master",
})).unwrap();
assert_eq!(d.standing, TrunkStanding::Stale);
assert_eq!(d.checkout, Some(Distance { behind: 779, ahead: 0 }));
// what is absent stays absent in the answer
assert!(serde_json::to_value(&d).unwrap().get("remedy").is_none());

property	type	required	description
checkout	one of 2	no	The checkout's `HEAD` against the remote trunk. While a merge is in progress, the commits it brings in count as present: the commit being made will hold them, so the merge that brings a checkout current is never judged by the tree it is replacing.
fetched_at	string \| null	no	When the repository last fetched (the time of `FETCH_HEAD`), RFC 3339: the moment this answer is true as of. Absent when it never fetched.
local_trunk	one of 2	no	The local trunk branch against the remote trunk: what a branch made from the local trunk starts from.
local_trunk_standing	reference	yes	Where the local trunk branch stands, judged the same way: what a branch made from it starts from. The same as `standing` when the checkout holds the trunk.
message	string	yes	What the standing means here, in one line.
on_trunk	boolean	yes	The work tree holds the trunk branch itself.
remedy	string \| null	no	The commands that bring the checkout and the local trunk current, when either is behind. Suggested, never run.
remote_head	string \| null	no	The commit the remote-tracking trunk names.
remote_trunk	string \| null	no	The remote-tracking trunk counted against (`origin/master`).
standing	reference	yes	Where the checkout stands: its `HEAD` — with the commit a merge in progress brings in — judged against the thresholds. This is what its server serves.
thresholds	reference	yes	The thresholds judged against, as `checkout.trunk_distance` declares them.
trunk	string \| null	no	The trunk branch, short.
worktree	string	yes	The work tree measured.

JSON Schema

{
  "$defs": {
    "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"
    },
    "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"
    }
  },
  "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"
  ],
  "title": "TrunkDistance",
  "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