feat(launcher): trusted client-instance identity for project-scoped launches

Issue #985. The production launcher could mint one trusted
GITEA_MCP_CLIENT_INSTANCE per launch, but two gaps kept real launches on
untrusted legacy-pid-* identities:

1. build_application_mcp_servers required a profile for all five sanctioned
   namespaces, so a project-scoped configuration exposing only author,
   reviewer, and merger could not use it without inventing controller and
   reconciler profiles that must not exist.
2. The module produced configuration data but had no runnable entry point, so
   every real launch bypassed it entirely.

Changes:

- resolve_launch_namespaces() validates an explicit namespace subset as an
  allow-list; unknown, duplicate, and empty selections are refused rather than
  silently narrowing a launch. Omitting it preserves five-namespace behaviour.
- build_application_mcp_servers() accepts that subset, requires profiles only
  for the launched namespaces, starts only those workers, and reports
  excluded_namespaces / project_scoped.
- collect_instance_ids_from_mcp_servers() inspects the launch's own namespaces
  instead of an assumed five, and reports missing_servers, so a three-namespace
  launch can prove shared attribution without reading as two absent workers.
- Runnable entry point: python3 -m mcp_application_launcher mints one trusted
  identity, writes a per-launch 0600 mcpServers config, and execs the client.
  CLIENT_LAUNCH_SPECS is a data-driven registry so other supported clients use
  the same mint-once/propagate-to-all mechanism. --dry-run prints the plan.
- Provenance sealing now fails closed. The inst- format is public and
  reproducible, so format alone could previously let anyone who set one
  environment variable manufacture a trusted identity. Trust now additionally
  requires GITEA_MCP_INSTANCE_PROVENANCE=trusted_launcher, which only the
  launcher writes; a well-formed but unsealed value is classified
  unsealed_launcher and refused, while still being reported for diagnosis.

Deliberate behaviour change: tests/test_issue_978_instance_fleet_snapshot.py
test_client_hints_trusted_when_set previously asserted that a well-formed ID
alone was trusted. It now supplies the launcher seal, and a new companion test
asserts the unsealed case fails closed. This tightens the contract; no
assertion was weakened.

No static or persistent per-project instance IDs are introduced, duplicate
worker and cohort detection are untouched, and no fleet or mutation gate is
relaxed.

Tests: tests/test_issue_985_project_scoped_launcher.py, 47 passed, 3 subtests.
Full suite from a branches/ worktree: 28 failed, 6252 passed, 6 skipped against
a master baseline at 32ab8392 of 28 failed, 6204 passed, 6 skipped; the failing
sets are byte-identical, so zero regressions and zero masked failures.

Closes #985

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

anti_stomp_preflight.py

@@ -355,6 +355,10 @@ def assess_anti_stomp_preflight(
     root_head_sha: str | None = None,
     root_porcelain: str | None = None,
     remote_master_sha: str | None = None,
+    # #983: the tracking integration ref the SHA above came from, so root-checkout
+    # contamination names the ref actually compared instead of a hardcoded
+    # 'prgs/master'. None preserves the previous generic wording.
+    remote_master_ref: str | None = None,
     check_root_checkout: bool = True,
     check_worktree: bool = True,
     create_issue_bootstrap_assessment: dict[str, Any] | None = None,
@@ -553,6 +557,7 @@ def assess_anti_stomp_preflight(
             remote_master_sha=remote_master_sha,
             resolved_role=req_role or role,
             actual_role=role,
+            remote_master_ref=remote_master_ref,
         )
         checks["root_checkout"] = {
             "block": bool(root_assessment.get("block")),

canonical_repository_root.py

@@ -37,6 +37,34 @@ CANONICAL_ROOT_ENV = "GITEA_CANONICAL_REPOSITORY_ROOT"
 # Candidate git remote names probed when deriving repository identity.
 _IDENTITY_REMOTE_CANDIDATES = ("prgs", "origin", "dadeschools", "mdcps")
 
+# Fallback integration-branch names, probed only when the checkout declares no
+# configured upstream (#983). Mirrors the stable base branches recognised
+# elsewhere in the workflow (``stacked_pr_support``, ``root_checkout_guard``).
+# The fallback is deliberately *not* ordered-first-wins: when more than one of
+# these refs exists and the checkout records no upstream, the integration branch
+# is genuinely ambiguous and resolution fails closed instead of guessing.
+INTEGRATION_BRANCH_CANDIDATES: tuple[str, ...] = ("master", "main", "dev")
+
+# Sources for a *proven* base-ref derivation (#983 B1).
+#
+# ``refs/remotes/<remote>/HEAD`` is deliberately absent from this list. It is a
+# local symbolic-ref *cache* written once at clone time and refreshed only by an
+# explicit ``git remote set-head``; an ordinary fetch never updates it. When the
+# upstream default branch changes afterwards the cache keeps naming the old
+# branch, so trusting it derives the wrong integration branch for a checkout
+# that is sitting exactly on its tip. The cache is still read, but only as a
+# corroborating observation reported back to the caller — never as an authority,
+# and never as a tie-breaker between otherwise ambiguous candidates.
+BASE_REF_SOURCE_CONFIGURED_UPSTREAM = "configured_branch_upstream"
+BASE_REF_SOURCE_UNIQUE_CANDIDATE = "unique_integration_branch_ref"
+
+# Reason codes for base-ref derivation outcomes (#983), so callers and tests can
+# assert the refusal cause instead of string-matching prose.
+DENY_NO_IDENTITY_REMOTE = "no_identity_remote"
+DENY_AMBIGUOUS_REMOTE = "ambiguous_identity_remote"
+DENY_AMBIGUOUS_BASE_BRANCH = "ambiguous_integration_branch"
+DENY_NO_BASE_BRANCH = "no_integration_branch_ref"
+
 # Repository-authority modes (#973 B10). Exactly two values are supported.
 # ``mode`` selects how repository authority is established, so an unrecognised
 # value must never be normalised onto one of these: aliasing a trusted mode is
@@ -120,17 +148,15 @@ def resolve_repo_toplevel(path: str) -> str | None:
     return os.path.realpath(top) if top else None
 
 
-def repository_identity_slug(path: str, *, remote: str | None = None) -> str | None:
-    """``owner/repository`` derived from a git remote configured at *path*.
+def _identity_remote_candidates(path: str, remote: str | None) -> list[str]:
+    """Ordered remote names to probe for identity at *path*.
 
-    Tries the caller-named remote first, then a small set of known remote names,
-    then whatever remote the repository actually has. Returns None when no remote
-    URL is parseable (identity cannot be proven).
+    Names are used verbatim — never case-folded. Git config subsection names are
+    case-sensitive, so a repository whose remote is ``MDCPS`` is reached only by
+    the exact string ``MDCPS``; the lowercase entry in
+    :data:`_IDENTITY_REMOTE_CANDIDATES` simply does not resolve, and the exact
+    name arrives from ``git remote`` below (#983).
     """
-    text = (path or "").strip()
-    if not text:
-        return None
-
     ordered: list[str] = []
     for name in (remote, *_IDENTITY_REMOTE_CANDIDATES):
         clean = (name or "").strip()
@@ -139,7 +165,7 @@ def repository_identity_slug(path: str, *, remote: str | None = None) -> str | N
 
     try:
         listed = subprocess.run(
-            ["git", "-C", text, "remote"],
+            ["git", "-C", path, "remote"],
             capture_output=True,
             text=True,
             check=True,
@@ -149,11 +175,20 @@ def repository_identity_slug(path: str, *, remote: str | None = None) -> str | N
     for name in listed:
         if name and name not in ordered:
             ordered.append(name)
+    return ordered
 
-    for name in ordered:
+
+def _configured_remote_identities(path: str, remote: str | None) -> list[tuple[str, str]]:
+    """``(remote_name, owner/repository)`` for every probe name that resolves.
+
+    Remote names are returned exactly as configured so downstream tracking refs
+    (``refs/remotes/<remote>/<branch>``) address the real ref (#983).
+    """
+    found: list[tuple[str, str]] = []
+    for name in _identity_remote_candidates(path, remote):
         try:
             url = subprocess.run(
-                ["git", "-C", text, "remote", "get-url", name],
+                ["git", "-C", path, "remote", "get-url", name],
                 capture_output=True,
                 text=True,
                 check=True,
@@ -162,8 +197,415 @@ def repository_identity_slug(path: str, *, remote: str | None = None) -> str | N
             continue
         parsed = remote_repo_guard.parse_org_repo_from_remote_url(url)
         if parsed:
-            return f"{parsed[0]}/{parsed[1]}"
-    return None
+            found.append((name, f"{parsed[0]}/{parsed[1]}"))
+    return found
+
+
+def _configured_branch_upstream(path: str) -> tuple[str | None, str | None]:
+    """``(remote_name, branch)`` the checked-out branch is configured to track.
+
+    Reads ``branch.<current>.remote`` and ``branch.<current>.merge`` — the
+    checkout's own explicitly configured integration target, equivalent to
+    ``@{upstream}``. Unlike ``refs/remotes/<remote>/HEAD`` this is not a
+    clone-time cache: it is written when the branch is set up to track an
+    upstream and rewritten whenever that tracking changes, so it states what the
+    checkout actually integrates onto today (#983 B1).
+
+    Returns ``(None, None)`` on a detached HEAD or an untracked branch. Names are
+    returned verbatim; git remote names are case-sensitive.
+    """
+    text = (path or "").strip()
+    if not text:
+        return None, None
+
+    branch = _git_read(text, "symbolic-ref", "--quiet", "--short", "HEAD")
+    if not branch:
+        return None, None
+
+    remote = _git_read(text, "config", "--get", f"branch.{branch}.remote")
+    merge = _git_read(text, "config", "--get", f"branch.{branch}.merge")
+    if not remote or not merge:
+        return None, None
+
+    prefix = "refs/heads/"
+    upstream_branch = merge[len(prefix):].strip() if merge.startswith(prefix) else merge.strip()
+    if not upstream_branch:
+        return None, None
+    return remote, upstream_branch
+
+
+def _cached_remote_head_branch(path: str, remote: str) -> str | None:
+    """Branch named by the *cached* ``refs/remotes/<remote>/HEAD`` symref.
+
+    Read for observability only. This value is never authoritative (see
+    :data:`BASE_REF_SOURCE_CONFIGURED_UPSTREAM`); it is surfaced so an operator
+    can see that the local cache disagrees with the configured upstream, and so
+    a refusal can name the misleading signal explicitly.
+    """
+    prefix = f"refs/remotes/{remote}/"
+    symref = _git_read(path, "symbolic-ref", "--quiet", f"{prefix}HEAD")
+    if not symref or not symref.startswith(prefix):
+        return None
+    branch = symref[len(prefix):].strip()
+    return branch or None
+
+
+def assess_identity_remote(
+    path: str, *, explicit_remote: str | None = None
+) -> dict:
+    """Resolve the identity remote, failing closed when the target is ambiguous.
+
+    This is the ambiguity-aware counterpart to :func:`resolve_identity_remote`,
+    and the reason gating and reporting can no longer disagree (#983 B2).
+
+    *explicit_remote* is a **caller-supplied disambiguation** and nothing else.
+    It must come from an operator or an explicitly sanctioned repository
+    context; a value this module inferred while probing must never be handed
+    back in through it, because doing so re-labels an internal first-wins guess
+    as deliberate caller intent and silently suppresses the ambiguity gate.
+
+    Decision table:
+
+    * No remote yields a parseable identity -> :data:`DENY_NO_IDENTITY_REMOTE`.
+    * *explicit_remote* names one of the resolving remotes -> that remote is
+      authoritative, ``explicit`` True.
+    * Otherwise, when every resolving remote claims the **same** repository the
+      target is unambiguous and is accepted, ``explicit`` False. The remote
+      named by the checkout's configured upstream is preferred among equals so
+      the choice is deterministic rather than probe-order dependent.
+    * Otherwise distinct remotes claim different repositories and there is no
+      sanctioned disambiguation -> :data:`DENY_AMBIGUOUS_REMOTE`.
+
+    Returns a dict with ``remote``, ``slug``, ``identities``, ``ambiguous``,
+    ``explicit``, ``reason_code`` and ``reasons``. ``remote``/``slug`` are None
+    on any refusal, so a caller cannot report a repository the gate refuses.
+    """
+    text = (path or "").strip()
+    result: dict = {
+        "remote": None,
+        "slug": None,
+        "identities": [],
+        "ambiguous": False,
+        "explicit": False,
+        "reason_code": None,
+        "reasons": [],
+    }
+    if not text:
+        result["reason_code"] = DENY_NO_IDENTITY_REMOTE
+        result["reasons"].append(
+            "no repository path supplied for identity-remote resolution (fail closed)"
+        )
+        return result
+
+    named = (explicit_remote or "").strip() or None
+    identities = _configured_remote_identities(text, named)
+    result["identities"] = list(identities)
+    if not identities:
+        result["reason_code"] = DENY_NO_IDENTITY_REMOTE
+        result["reasons"].append(
+            f"no git remote at '{text}' yields a parseable repository identity "
+            "(fail closed)"
+        )
+        return result
+
+    if named:
+        for name, slug in identities:
+            if name == named:
+                result["remote"] = name
+                result["slug"] = slug
+                result["explicit"] = True
+                return result
+
+    distinct = {slug for _, slug in identities}
+    if len(distinct) > 1:
+        listed = ", ".join(f"{name} -> {slug}" for name, slug in identities)
+        result["ambiguous"] = True
+        result["reason_code"] = DENY_AMBIGUOUS_REMOTE
+        detail = (
+            f"explicitly named remote '{named}' does not resolve a repository identity "
+            "there, so it cannot disambiguate; "
+            if named
+            else ""
+        )
+        result["reasons"].append(
+            f"ambiguous repository identity at '{text}': {detail}remotes resolve to "
+            f"different repositories ({listed}); no single authoritative target can "
+            "be established (fail closed)"
+        )
+        return result
+
+    # One repository, possibly reachable through several remote names (a mirror).
+    # Prefer the remote the checkout is actually configured to track so the
+    # choice is deterministic instead of probe-order dependent.
+    upstream_remote, _ = _configured_branch_upstream(text)
+    chosen = identities[0]
+    if upstream_remote:
+        for entry in identities:
+            if entry[0] == upstream_remote:
+                chosen = entry
+                break
+    result["remote"], result["slug"] = chosen
+    return result
+
+
+def resolve_identity_remote(
+    path: str, *, remote: str | None = None
+) -> tuple[str | None, str | None]:
+    """``(remote_name, owner/repository)`` for the remote that proves identity.
+
+    The remote *name* is the piece historically thrown away by
+    :func:`repository_identity_slug`, even though resolving the slug already
+    required discovering it. Cross-repository base-ref derivation needs that
+    name to build ``refs/remotes/<remote>/<branch>``, so it is now returned
+    rather than discarded (#983). Returns ``(None, None)`` when no remote URL is
+    parseable (identity cannot be proven).
+
+    First-wins by design: this is the identity lookup behind
+    :func:`repository_identity_slug` and the #706/#973 canonical-root
+    validation, which compare an observed slug against an independently trusted
+    expected slug and therefore do not need an ambiguity verdict. Callers that
+    *derive* a target rather than validate one — the mutation guard and the
+    parity report — must use :func:`assess_identity_remote`, which fails closed
+    on ambiguity (#983 B2).
+    """
+    text = (path or "").strip()
+    if not text:
+        return None, None
+    for name, slug in _configured_remote_identities(text, remote):
+        return name, slug
+    return None, None
+
+
+def repository_identity_slug(path: str, *, remote: str | None = None) -> str | None:
+    """``owner/repository`` derived from a git remote configured at *path*.
+
+    Tries the caller-named remote first, then a small set of known remote names,
+    then whatever remote the repository actually has. Returns None when no remote
+    URL is parseable (identity cannot be proven).
+    """
+    return resolve_identity_remote(path, remote=remote)[1]
+
+
+def _base_ref_result(
+    *,
+    proven: bool,
+    reasons: list[str],
+    remote: str | None = None,
+    branch: str | None = None,
+    repository_slug: str | None = None,
+    source: str | None = None,
+    reason_code: str | None = None,
+    identity_explicit: bool = False,
+    configured_upstream_remote: str | None = None,
+    configured_upstream_branch: str | None = None,
+    cached_remote_head_branch: str | None = None,
+) -> dict:
+    """Build the base-ref derivation payload.
+
+    ``tracking_refs`` is the ordered probe tuple downstream guards hand to
+    ``git rev-parse``: the ``<remote>/<branch>`` shorthand first, then the fully
+    qualified ``refs/remotes/<remote>/<branch>``. It is empty whenever the
+    derivation is not ``proven``, so an unresolved target can never be probed
+    against some other repository's ref.
+
+    ``cached_remote_head_branch`` reports what the local
+    ``refs/remotes/<remote>/HEAD`` cache claims, and
+    ``cached_remote_head_conflicts`` whether that claim disagrees with the branch
+    actually derived. Both are observability only: the cache never decides the
+    outcome (#983 B1).
+    """
+    tracking_ref = f"refs/remotes/{remote}/{branch}" if proven and remote and branch else None
+    tracking_refs: tuple[str, ...] = (
+        (f"{remote}/{branch}", tracking_ref) if tracking_ref else ()
+    )
+    return {
+        "proven": proven,
+        "block": not proven,
+        "remote": remote,
+        "branch": branch,
+        "repository_slug": repository_slug,
+        "tracking_ref": tracking_ref,
+        "tracking_refs": tracking_refs,
+        "source": source,
+        "reason_code": reason_code,
+        "identity_explicit": identity_explicit,
+        "configured_upstream_remote": configured_upstream_remote,
+        "configured_upstream_branch": configured_upstream_branch,
+        "cached_remote_head_branch": cached_remote_head_branch,
+        "cached_remote_head_conflicts": bool(
+            cached_remote_head_branch and branch and cached_remote_head_branch != branch
+        ),
+        "reasons": list(reasons),
+    }
+
+
+def _git_read(path: str, *args: str) -> str | None:
+    """Run a read-only git command in *path*; ``None`` on any failure."""
+    try:
+        res = subprocess.run(
+            ["git", "-C", path, *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except Exception:
+        return None
+    if res.returncode != 0:
+        return None
+    return (res.stdout or "").strip() or None
+
+
+def _ref_exists(path: str, ref: str) -> bool:
+    """Whether *ref* resolves in the checkout at *path*."""
+    try:
+        res = subprocess.run(
+            ["git", "-C", path, "rev-parse", "--verify", "--quiet", ref],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except Exception:
+        return False
+    return res.returncode == 0 and bool((res.stdout or "").strip())
+
+
+def resolve_target_base_ref(path: str, *, explicit_remote: str | None = None) -> dict:
+    """Derive the authoritative integration base ref for the checkout at *path*.
+
+    This is the single resolved target shared by cross-repository mutation
+    gating and parity reporting, so the two can never disagree about which
+    commit a checkout is supposed to match (#983).
+
+    *explicit_remote* is a caller-supplied disambiguation only; see
+    :func:`assess_identity_remote` for why an internally inferred remote must
+    never be passed back in here (#983 B2).
+
+    Resolution order:
+
+    1. **Identity remote** — via :func:`assess_identity_remote`, with its exact
+       configured case preserved (``MDCPS`` stays ``MDCPS``). Ambiguous identity
+       fails closed here rather than resolving to whichever remote probed first.
+    2. **The checkout's configured upstream** — ``branch.<current>.remote`` plus
+       ``branch.<current>.merge``, accepted when it names the identity remote
+       and its remote-tracking ref actually exists. This is the checkout's own
+       declaration of what it integrates onto, and unlike the remote-HEAD cache
+       it is rewritten whenever that tracking changes.
+    3. **Fallback** — only when the checkout declares no usable upstream,
+       exactly one of :data:`INTEGRATION_BRANCH_CANDIDATES` present as a
+       remote-tracking ref.
+
+    ``refs/remotes/<remote>/HEAD`` is **not** a step. It is read for reporting
+    (``cached_remote_head_branch`` / ``cached_remote_head_conflicts``) and never
+    decides the branch, because it is a clone-time cache that an ordinary fetch
+    does not refresh: a checkout whose upstream default moved on still has the
+    old branch cached, and trusting it gates that checkout against a ref it does
+    not integrate onto (#983 B1).
+
+    Fails closed — ``proven`` False, empty ``tracking_refs``, and a
+    ``reason_code`` — when identity is unprovable, when distinct remotes claim
+    different repositories, when several candidate branches exist with no
+    configured upstream, or when no candidate exists at all. Nothing here
+    invents a branch, writes a ref, runs a fetch, or falls back to another
+    repository's base. Every ``proven`` result names a tracking ref that
+    resolves in this checkout.
+    """
+    text = (path or "").strip()
+    if not text:
+        return _base_ref_result(
+            proven=False,
+            reasons=["no repository path supplied for base-ref derivation (fail closed)"],
+            reason_code=DENY_NO_IDENTITY_REMOTE,
+        )
+
+    identity = assess_identity_remote(text, explicit_remote=explicit_remote)
+    remote_name, slug = identity["remote"], identity["slug"]
+    if not remote_name:
+        return _base_ref_result(
+            proven=False,
+            reasons=list(identity["reasons"]),
+            reason_code=identity["reason_code"],
+            identity_explicit=bool(identity["explicit"]),
+        )
+
+    prefix = f"refs/remotes/{remote_name}/"
+    cached = _cached_remote_head_branch(text, remote_name)
+    upstream_remote, upstream_branch = _configured_branch_upstream(text)
+    common = {
+        "repository_slug": slug,
+        "identity_explicit": bool(identity["explicit"]),
+        "configured_upstream_remote": upstream_remote,
+        "configured_upstream_branch": upstream_branch,
+        "cached_remote_head_branch": cached,
+    }
+
+    # 2. The checkout's configured upstream, when it belongs to the identity
+    #    remote and its tracking ref is actually present. Requiring the ref to
+    #    exist keeps 'proven' honest: a proven target is always resolvable.
+    if (
+        upstream_remote == remote_name
+        and upstream_branch
+        and _ref_exists(text, f"{prefix}{upstream_branch}")
+    ):
+        return _base_ref_result(
+            proven=True,
+            reasons=[],
+            remote=remote_name,
+            branch=upstream_branch,
+            source=BASE_REF_SOURCE_CONFIGURED_UPSTREAM,
+            **common,
+        )
+
+    # 3. Exactly one known integration branch present as a remote-tracking ref.
+    present = [
+        candidate
+        for candidate in INTEGRATION_BRANCH_CANDIDATES
+        if _ref_exists(text, f"{prefix}{candidate}")
+    ]
+    if len(present) == 1:
+        return _base_ref_result(
+            proven=True,
+            reasons=[],
+            remote=remote_name,
+            branch=present[0],
+            source=BASE_REF_SOURCE_UNIQUE_CANDIDATE,
+            **common,
+        )
+
+    # The cached remote HEAD is named in the refusal so the operator can see the
+    # signal that looks authoritative but is not, and is told the read-only fix.
+    cache_note = (
+        f" the cached '{prefix}HEAD' names '{cached}', but that cache is written at "
+        "clone time and is not refreshed by fetch, so it cannot break the tie;"
+        if cached
+        else ""
+    )
+    remedy = (
+        f" Configure the checkout's upstream (git branch --set-upstream-to={remote_name}/"
+        "<branch>) so the integration target is declared rather than guessed."
+    )
+    if len(present) > 1:
+        return _base_ref_result(
+            proven=False,
+            reasons=[
+                f"the checkout at '{text}' declares no upstream on remote "
+                f"'{remote_name}' and several integration branches exist "
+                f"({', '.join(present)});{cache_note} the integration base ref is "
+                f"ambiguous (fail closed).{remedy}"
+            ],
+            reason_code=DENY_AMBIGUOUS_BASE_BRANCH,
+            **common,
+        )
+    return _base_ref_result(
+        proven=False,
+        reasons=[
+            f"the checkout at '{text}' declares no upstream on remote '{remote_name}' "
+            f"and none of {'/'.join(INTEGRATION_BRANCH_CANDIDATES)} exists as a "
+            f"remote-tracking ref under '{prefix}';{cache_note} the integration base "
+            f"ref cannot be derived (fail closed; no fetch is performed here).{remedy}"
+        ],
+        reason_code=DENY_NO_BASE_BRANCH,
+        **common,
+    )
 
 
 def assess_canonical_repository_root(

docs/instance-fleet-identity.md

@@ -34,8 +34,10 @@ namespaces.
 
 1. Multiple active instances **may** share the same `client_type`.
 2. Every application launch receives a **distinct** `client_instance_id`.
-3. All five namespace workers of one launch report the **same**
-   `client_instance_id`.
+3. All namespace workers of one launch report the **same**
+   `client_instance_id`. For a whole-fleet launch that is five workers; for a
+   project-scoped launch it is exactly the namespaces that launch started
+   (#985).
 4. Each namespace worker has a **distinct** `worker_identity`, process
    identity, generation, and PID.
 5. Instance identity is **never** inferred from PID proximity, timestamps, or
@@ -46,6 +48,92 @@ namespaces.
 This deliberately **replaces** any permanent `exactly_one_per_profile` fleet
 model (#949 assumption) as the operating rule for multi-instance fleets.
 
+## Project-scoped launches and the runnable entry point (#985)
+
+Not every project exposes all five namespaces. A project-scoped configuration
+such as Weekly Briefings intentionally has **author, reviewer, and merger
+only**, and has no controller or reconciler profile to supply. Requiring all
+five would force operators to invent profiles that must not exist, so the
+launcher accepts an explicitly validated subset.
+
+### Running a launch
+
+```bash
+python3 -m mcp_application_launcher \
+    --client claude_code \
+    --namespaces author,reviewer,merger \
+    --profile author=prgs-author \
+    --profile reviewer=prgs-reviewer \
+    --profile merger=prgs-merger
+```
+
+That mints one trusted `client_instance_id`, writes a per-launch `mcpServers`
+config, and executes:
+
+```text
+claude --mcp-config <per-launch.json> --strict-mcp-config
+```
+
+Add `--dry-run` to print the plan (namespaces, excluded namespaces, minted ID,
+argv, config path) as JSON and start nothing. Omit `--namespaces` to launch all
+five exactly as before. Arguments after the flags are forwarded to the client.
+
+Other supported clients register one entry in
+`mcp_application_launcher.CLIENT_LAUNCH_SPECS`; because the argv builder only
+ever receives a config this module wrote, every client necessarily goes through
+the same mint-once/propagate-to-all mechanism.
+
+### Why the config is per-launch and never `.mcp.json`
+
+Persisting a trusted ID into a shared, reused `.mcp.json` would give two
+concurrent sessions **the same** trusted identity — precisely the reuse case
+the duplicate gate must reject. The launcher therefore writes a fresh
+owner-readable-only (`0600`) config per launch. Do not commit one, and do not
+copy a minted `GITEA_MCP_CLIENT_INSTANCE` into any checked-in configuration.
+
+### Provenance sealing
+
+The `inst-…` format is public and reproducible, so format alone cannot
+establish trust: anyone able to set one environment variable could otherwise
+hand-write a valid-looking ID and be believed. Trust therefore requires **both**
+the format and `GITEA_MCP_INSTANCE_PROVENANCE=trusted_launcher`, which only the
+launcher writes. A well-formed but unsealed identity is classified
+`unsealed_launcher` and **fails closed** — it is still reported for diagnosis,
+but never authorizes trusted attribution. Manually asserted trust is not
+possible.
+
+### Migration and coordinated relaunch
+
+Existing configurations that predate this work set no instance key at all, so
+their workers register under `legacy-pid-*` (`legacy_incomplete`) and remain
+mutually indistinguishable when two launches share a profile.
+
+Migrating is a **coordinated relaunch**, not an in-place edit — a running
+worker cannot acquire an identity it was not started with:
+
+1. Stop every LLM client currently running Gitea MCP workers. A single
+   surviving legacy cohort keeps the fleet ambiguous.
+2. Relaunch each application through the command above.
+3. Repeat per application. Concurrent launches are expected and safe: each
+   receives its own trusted ID.
+
+### Post-launch verification
+
+* `gitea_get_runtime_context` → `provenance_assessment.attachment` should show
+  an `inst-…` `client_instance_id` with
+  `instance_id_provenance: trusted_launcher`, not `legacy-pid-*` /
+  `legacy_incomplete`.
+* Every namespace of the same launch must report that **same** ID; two
+  different launches must report different IDs.
+* `gitea_resolve_task_capability` should return
+  `exact_safe_next_action: "None; ready for operations."` with no
+  `blocker_kind`. A `runtime_reconnect_required` naming duplicate PIDs per
+  profile means at least one cohort is still on legacy identity, or a second
+  cohort is genuinely running.
+* `mcp_application_launcher.collect_instance_ids_from_mcp_servers(servers,
+  namespaces=[...])` returns `shared_single_trusted_id` for a built config, and
+  reports `missing_servers` when an expected namespace entry is absent.
+
 ## How five workers join one instance
 
 1. The host starts one application instance (for example one Codex session).

gitea_config.py

@@ -1286,16 +1286,19 @@ def multi_namespace_launcher_entries(
     profile_by_namespace,
     *,
     client_type,
+    namespaces=None,
     config_path=None,
     client_instance_id=None,
     fleet_run_id=None,
     session_id=None,
     launch_nonce=None,
 ):
-    """Build production mcpServers for all five namespaces of one application launch.
+    """Build production mcpServers for the namespaces of one application launch.
 
     One shared trusted ``client_instance_id`` is minted (or reused) and
-    propagated to every namespace worker env. See
+    propagated to every namespace worker env. *namespaces* selects a validated
+    project-scoped subset (#985); omitting it launches all five sanctioned
+    namespaces as before. See
     :func:`mcp_application_launcher.build_application_mcp_servers`.
     """
     import mcp_application_launcher as app_launcher
@@ -1303,6 +1306,7 @@ def multi_namespace_launcher_entries(
     return app_launcher.build_application_mcp_servers(
         profile_by_namespace,
         client_type=client_type,
+        namespaces=namespaces,
         config_path=config_path or DEFAULT_CONFIG_PATH,
         client_instance_id=client_instance_id,
         fleet_run_id=fleet_run_id,

gitea_mcp_server.py

@@ -1052,9 +1052,16 @@ def _create_issue_bootstrap_assessment(
         git_state = issue_lock_worktree.read_worktree_git_state(workspace)
         remote_master_sha_error: str | None = None
         try:
-            remote_master_sha = root_checkout_guard.resolve_remote_master_sha(
+            # #983: consume the resolved-target state so an *underivable* base ref
+            # reaches the assessor as named missing evidence rather than a bare
+            # None, which the bootstrap would otherwise report only as "live
+            # master tip is unknown" with no cause.
+            _base_state = root_checkout_guard.resolve_remote_master_ref_state(
                 ctx["canonical_repo_root"]
             )
+            remote_master_sha = _base_state["sha"]
+            if not remote_master_sha and _base_state.get("reasons"):
+                remote_master_sha_error = "; ".join(_base_state["reasons"])
         except Exception as exc:
             remote_master_sha = None
             remote_master_sha_error = (
@@ -1082,9 +1089,14 @@ def _create_issue_bootstrap_assessment(
     # closed instead of proceeding without base-equivalence proof.
     remote_master_sha_error: str | None = None
     try:
-        remote_master_sha = root_checkout_guard.resolve_remote_master_sha(
+        # #983: same resolved-target consumption as the author bootstrap above —
+        # a target whose base ref cannot be derived must say why.
+        _base_state = root_checkout_guard.resolve_remote_master_ref_state(
             ctx["canonical_repo_root"]
         )
+        remote_master_sha = _base_state["sha"]
+        if not remote_master_sha and _base_state.get("reasons"):
+            remote_master_sha_error = "; ".join(_base_state["reasons"])
     except Exception as exc:
         remote_master_sha = None
         remote_master_sha_error = f"{type(exc).__name__}: {exc}".strip() or "resolver failed"
@@ -1303,7 +1315,12 @@ def _run_anti_stomp_preflight(
     workspace = ctx["workspace_path"]
     canonical_root = ctx["canonical_repo_root"]
     git_state = issue_lock_worktree.read_worktree_git_state(canonical_root)
-    remote_master_sha = root_checkout_guard.resolve_remote_master_sha(canonical_root)
+    # #983: derive the target base ref for this repository and carry the ref
+    # itself alongside the SHA, so the anti-stomp root-checkout check reports the
+    # ref it actually compared.
+    _root_base_state = root_checkout_guard.resolve_remote_master_ref_state(canonical_root)
+    remote_master_sha = _root_base_state["sha"]
+    remote_master_ref = _root_base_state.get("ref")
 
     # Repo/org facts (best-effort; explicit org/repo when provided).
     resolved_org = org
@@ -1432,6 +1449,7 @@ def _run_anti_stomp_preflight(
         root_head_sha=git_state.get("head_sha"),
         root_porcelain=git_state.get("porcelain_status") or "",
         remote_master_sha=remote_master_sha,
+        remote_master_ref=remote_master_ref,
         startup_head=startup_head,
         current_code_head=current_code_head,
         lease_required=lease_required,
@@ -1987,7 +2005,11 @@ def _enforce_root_checkout_guard(worktree_path: str | None = None) -> None:
     canonical_root = ctx["canonical_repo_root"]
     workspace = ctx["workspace_path"]
     git_state = issue_lock_worktree.read_worktree_git_state(canonical_root)
-    remote_master_sha = root_checkout_guard.resolve_remote_master_sha(canonical_root)
+    # #983: consume the resolved target so the contamination message names the
+    # ref that was actually compared (refs/remotes/<remote>/<branch>) instead of
+    # a hardcoded 'prgs/master' the target repository may not have.
+    base_state = root_checkout_guard.resolve_remote_master_ref_state(canonical_root)
+    remote_master_sha = base_state["sha"]
     assessment = root_checkout_guard.assess_root_checkout_guard(
         workspace_path=workspace,
         canonical_repo_root=canonical_root,
@@ -1997,6 +2019,7 @@ def _enforce_root_checkout_guard(worktree_path: str | None = None) -> None:
         remote_master_sha=remote_master_sha,
         resolved_role=_preflight_resolved_role,
         actual_role=_actual_profile_role(),
+        remote_master_ref=base_state.get("ref"),
     )
     if assessment["block"]:
         raise RuntimeError(root_checkout_guard.format_root_checkout_guard_error(assessment))

master_parity_gate.py

@@ -378,6 +378,11 @@ def format_parity(assessment: dict) -> str:
 # feeds the mutation gate and never changes startup_head/current_head.
 # ---------------------------------------------------------------------------
 
+# Legacy hardcoded target tracking ref. Retained for callers that still pass an
+# explicit ref, but no longer the default: assuming a remote named ``origin``
+# read an unrelated (often orphaned) remote-tracking ref in any checkout whose
+# remote is named something else, and reported the target stale against a commit
+# from a remote that may no longer even be configured (#983).
 DEFAULT_TARGET_TRACKING_REF = "refs/remotes/origin/master"
 
 
@@ -408,7 +413,7 @@ def assess_target_repository_parity(
     *,
     canonical_root: str | None,
     source: str | None,
-    tracking_ref: str = DEFAULT_TARGET_TRACKING_REF,
+    tracking_ref: str | None = None,
 ) -> dict:
     """Assess the configured cross-repository target checkout.
 
@@ -421,6 +426,11 @@ def assess_target_repository_parity(
     An unconfigured namespace is ``configured=False`` and never ``stale`` — the
     single-repository default has no second dimension to be stale about. A
     configured root that cannot be read is ``determinable=False`` with reasons.
+
+    *tracking_ref* defaults to None, meaning **derive the target from the
+    repository itself** through the same resolver the mutation guard uses, so
+    gating and reporting can never disagree about which ref is authoritative
+    (#983). Passing an explicit ref preserves the previous behaviour verbatim.
     """
     result = {
         "configured": bool(canonical_root),
@@ -429,9 +439,13 @@ def assess_target_repository_parity(
         "repository_slug": None,
         "checkout_head": None,
         "tracking_ref": tracking_ref,
+        "base_remote": None,
+        "base_branch": None,
+        "tracking_ref_source": "explicit_tracking_ref" if tracking_ref else None,
         "remote_tracking_head": None,
         "determinable": False,
         "stale": False,
+        "reason_code": None,
         "reasons": [],
     }
     if not canonical_root:
@@ -463,18 +477,53 @@ def assess_target_repository_parity(
     result["checkout_head"] = head
     result["determinable"] = True
 
-    remote_url = _git_capture(canonical_root, "remote", "get-url", "origin")
-    if remote_url:
-        # Local import keeps this module dependency-light for its startup role.
-        import remote_repo_guard
+    # Local import keeps this module dependency-light for its startup role.
+    import canonical_repository_root as _crr
 
-        parsed = remote_repo_guard.parse_org_repo_from_remote_url(remote_url)
-        if parsed:
-            result["repository_slug"] = f"{parsed[0]}/{parsed[1]}"
-    if not result["repository_slug"]:
-        result["reasons"].append(
-            "target repository identity could not be derived from its git remote"
+    # #983: identity comes from whichever remote actually proves it, not from a
+    # remote assumed to be named 'origin'. In a checkout whose only remote is
+    # 'prgs', the old lookup failed outright and reported the identity as
+    # underivable while a leftover refs/remotes/origin/master still resolved.
+    #
+    # #983 B2: this must be the *ambiguity-aware* resolver. The first-wins
+    # `resolve_identity_remote` picks whichever remote probes first, so on a
+    # target where distinct remotes claim different repositories the report
+    # confidently named one of them while the mutation gate refused the same
+    # target — gating and reporting evaluating different repositories, which is
+    # precisely the divergence this issue exists to end.
+    identity = _crr.assess_identity_remote(canonical_root)
+    result["repository_slug"] = identity["slug"]
+    if not identity["slug"]:
+        result["reason_code"] = identity["reason_code"]
+        result["reasons"].extend(
+            identity["reasons"]
+            or ["target repository identity could not be derived from its git remote"]
         )
+    if identity["ambiguous"]:
+        # An ambiguous target has no single authoritative base, so reporting one
+        # would be a guess. Fail closed here exactly as the gate does.
+        return result
+
+    # Identity is otherwise resolved independently of the base ref: a target that
+    # has never been fetched still has a provable repository identity, and
+    # reporting it as unidentifiable would lose real information over an
+    # unrelated missing ref.
+    if not tracking_ref:
+        # No remote argument. The identity remote resolved just above was
+        # *inferred here*, and feeding it back in would tell the resolver a
+        # caller had explicitly disambiguated the repository, suppressing its
+        # ambiguity gate (#983 B2). Only an operator-supplied remote may do that,
+        # and this call site has none.
+        base = _crr.resolve_target_base_ref(canonical_root)
+        if not base.get("proven"):
+            result["reason_code"] = base.get("reason_code")
+            result["reasons"].extend(base.get("reasons") or [])
+            return result
+        tracking_ref = base["tracking_ref"]
+        result["tracking_ref"] = tracking_ref
+        result["tracking_ref_source"] = base.get("source")
+        result["base_remote"] = base.get("remote")
+        result["base_branch"] = base.get("branch")
 
     tracking_head = _git_capture(canonical_root, "rev-parse", tracking_ref)
     if not tracking_head:

mcp_application_launcher.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 import os
 import secrets
-from typing import Any, Mapping
+from typing import Any, Mapping, Sequence
 
 import mcp_fleet_snapshot as fleet
 import mcp_worker_identity as mwi
@@ -152,10 +152,54 @@ def namespace_worker_env(
     return env
 
 
+def resolve_launch_namespaces(
+    namespaces: "Sequence[str] | None" = None,
+) -> tuple[str, ...]:
+    """Validate an explicit project-scoped namespace subset (#985).
+
+    ``None`` keeps the historical whole-fleet behaviour and resolves to all five
+    sanctioned namespaces. An explicit sequence is validated against
+    :data:`SANCTIONED_NAMESPACES` and returned in canonical fleet order, so a
+    project-scoped configuration (for example author/reviewer/merger only) can
+    launch without inventing controller or reconciler profiles.
+
+    This is an allow-list, not a filter: anything outside the sanctioned set is
+    refused rather than silently dropped, so a typo can never quietly shrink a
+    launch to fewer workers than the operator intended.
+    """
+    if namespaces is None:
+        return tuple(SANCTIONED_NAMESPACES)
+
+    requested = [str(ns).strip().lower() for ns in namespaces]
+    if not requested or any(not ns for ns in requested):
+        raise ValueError(
+            "namespaces must be a non-empty sequence of sanctioned namespace "
+            f"names; choose from {list(SANCTIONED_NAMESPACES)}"
+        )
+
+    unknown = sorted({ns for ns in requested if ns not in SANCTIONED_NAMESPACES})
+    if unknown:
+        raise ValueError(
+            f"unsanctioned namespace(s) {unknown} requested; sanctioned "
+            f"namespaces are {list(SANCTIONED_NAMESPACES)}"
+        )
+
+    duplicates = sorted({ns for ns in requested if requested.count(ns) > 1})
+    if duplicates:
+        raise ValueError(
+            f"duplicate namespace(s) {duplicates} requested; each sanctioned "
+            "namespace may appear at most once in one launch"
+        )
+
+    selected = set(requested)
+    return tuple(ns for ns in SANCTIONED_NAMESPACES if ns in selected)
+
+
 def build_application_mcp_servers(
     profile_by_namespace: Mapping[str, str],
     *,
     client_type: str | None,
+    namespaces: "Sequence[str] | None" = None,
     config_path: str | None = None,
     client_instance_id: str | None = None,
     fleet_run_id: str | None = None,
@@ -175,14 +219,22 @@ def build_application_mcp_servers(
 
     Every namespace server entry receives the **same** instance ID. Separate
     calls with no supplied ID receive distinct IDs.
+
+    *namespaces* selects an explicitly validated project-scoped subset (#985).
+    Omitting it preserves the original whole-fleet behaviour, so existing
+    five-namespace callers are unaffected. Only the resolved namespaces need a
+    profile, and only they are started; excluded namespaces are reported so a
+    caller can prove a controller/reconciler worker was never launched.
     """
+    resolved_namespaces = resolve_launch_namespaces(namespaces)
+
     missing = [
-        ns for ns in SANCTIONED_NAMESPACES if not profile_by_namespace.get(ns)
+        ns for ns in resolved_namespaces if not profile_by_namespace.get(ns)
     ]
     if missing:
         raise ValueError(
             "build_application_mcp_servers requires a profile for every "
-            f"sanctioned namespace; missing: {missing}"
+            f"requested namespace; missing: {missing}"
         )
 
     if client_instance_id is None:
@@ -213,6 +265,13 @@ def build_application_mcp_servers(
             "namespace_server_names": list(NAMESPACE_SERVER_NAMES),
         }
 
+    # The launch record describes only the namespaces this launch actually
+    # starts, so downstream attribution never implies an unstarted worker.
+    launch["namespaces"] = list(resolved_namespaces)
+    launch["namespace_server_names"] = [
+        f"gitea-{ns}" for ns in resolved_namespaces
+    ]
+
     # Resolve command/args from the production server entry when not provided.
     if command is None or args is None:
         import gitea_config
@@ -223,7 +282,7 @@ def build_application_mcp_servers(
 
     servers: dict[str, Any] = {}
     shared_id = launch["client_instance_id"]
-    for namespace in SANCTIONED_NAMESPACES:
+    for namespace in resolved_namespaces:
         server_name = f"gitea-{namespace}"
         profile = profile_by_namespace[namespace]
         env = namespace_worker_env(
@@ -240,14 +299,17 @@ def build_application_mcp_servers(
             "env": env,
         }
 
+    excluded = [ns for ns in SANCTIONED_NAMESPACES if ns not in resolved_namespaces]
     return {
         "mcpServers": servers,
         "launch": launch,
         "client_instance_id": shared_id,
         "client_type": launch["client_type"],
-        "namespaces": list(SANCTIONED_NAMESPACES),
+        "namespaces": list(resolved_namespaces),
+        "excluded_namespaces": excluded,
+        "project_scoped": bool(excluded),
         "shared_instance_id_across_namespaces": True,
-        "namespace_count": len(SANCTIONED_NAMESPACES),
+        "namespace_count": len(resolved_namespaces),
     }
 
 
@@ -316,15 +378,33 @@ def launcher_entry_for_profile(
 
 def collect_instance_ids_from_mcp_servers(
     mcp_servers: Mapping[str, Any],
+    *,
+    namespaces: "Sequence[str] | None" = None,
 ) -> dict[str, Any]:
     """Inspect a production mcpServers map for shared instance attribution.
 
-    Returns the unique set of client_instance_id values across gitea-* servers
-    and whether all five namespaces share exactly one trusted ID.
+    Returns the unique set of client_instance_id values across the gitea-*
+    servers of one launch and whether every worker of that launch shares
+    exactly one trusted ID.
+
+    The inspected set is the launch's own namespaces, not an assumed five
+    (#985): a project-scoped author/reviewer/merger launch must be able to
+    prove shared attribution without a controller or reconciler entry counting
+    as a missing worker. Pass *namespaces* to assert an exact expected subset;
+    omit it to inspect whichever sanctioned namespace servers are present.
     """
+    if namespaces is None:
+        expected_servers = [
+            name for name in NAMESPACE_SERVER_NAMES if name in mcp_servers
+        ]
+    else:
+        expected_servers = [
+            f"gitea-{ns}" for ns in resolve_launch_namespaces(namespaces)
+        ]
+
     ids: list[str] = []
     by_server: dict[str, str | None] = {}
-    for name in NAMESPACE_SERVER_NAMES:
+    for name in expected_servers:
         entry = mcp_servers.get(name) or {}
         env = entry.get("env") or {}
         raw = (env.get(CLIENT_INSTANCE_ENV) or "").strip() or None
@@ -337,14 +417,19 @@ def collect_instance_ids_from_mcp_servers(
         for i in unique
         if fleet.assess_instance_identity(i)["trusted"]
     ]
+    missing_servers = [n for n in expected_servers if n not in mcp_servers]
     return {
         "server_instance_ids": by_server,
         "unique_instance_ids": unique,
         "trusted_instance_ids": trusted,
+        "inspected_servers": list(expected_servers),
+        "missing_servers": missing_servers,
         "shared_single_trusted_id": (
-            len(unique) == 1
+            bool(expected_servers)
+            and not missing_servers
+            and len(unique) == 1
             and len(trusted) == 1
-            and all(by_server.get(n) == unique[0] for n in NAMESPACE_SERVER_NAMES)
+            and all(by_server.get(n) == unique[0] for n in expected_servers)
         ),
         "namespace_server_count": sum(
             1 for n in NAMESPACE_SERVER_NAMES if n in mcp_servers
@@ -365,20 +450,23 @@ def inherit_or_refuse_client_instance(
     source = dict(env if env is not None else os.environ)
     raw = (source.get(CLIENT_INSTANCE_ENV) or "").strip() or None
     provenance_marker = (source.get(INSTANCE_PROVENANCE_ENV) or "").strip()
-    assessment = fleet.assess_instance_identity(raw)
-    # Ordinary user-supplied values without launcher provenance marker are
-    # still format-checked by assess_instance_identity. When the format is
-    # trusted but the launcher marker is absent, keep the ID but note that
-    # provenance is not launcher-sealed (operator hand-set or legacy config).
+    assessment = dict(fleet.assess_instance_identity(raw))
+    # The ``inst-…`` format is public and reproducible, so format alone cannot
+    # establish trust: anyone able to set one env var could otherwise hand-write
+    # a well-formed ID and be believed. Trust therefore requires the launcher's
+    # own seal as well, and a well-formed but unsealed identity fails closed
+    # rather than degrading to a mere annotation (#985).
     if assessment["trusted"] and provenance_marker != LAUNCHER_PROVENANCE_VALUE:
-        assessment = dict(assessment)
         assessment["launcher_sealed"] = False
+        assessment["trusted"] = False
+        assessment["complete"] = False
+        assessment["provenance"] = fleet.INSTANCE_ID_PROVENANCE_UNSEALED
         assessment["reasons"] = list(assessment.get("reasons") or []) + [
             f"{INSTANCE_PROVENANCE_ENV} is not {LAUNCHER_PROVENANCE_VALUE!r}; "
-            "identity format is valid but not sealed by the production launcher"
+            "identity format is valid but not sealed by the production "
+            "launcher, so trusted attribution is refused"
         ]
     else:
-        assessment = dict(assessment)
         assessment["launcher_sealed"] = bool(
             assessment["trusted"]
             and provenance_marker == LAUNCHER_PROVENANCE_VALUE
@@ -391,3 +479,275 @@ def inherit_or_refuse_client_instance(
         (source.get("GITEA_MCP_CLIENT") or "").strip() or None
     )
     return assessment
+
+
+# ---------------------------------------------------------------------------
+# Runnable launch path (#985)
+# ---------------------------------------------------------------------------
+
+#: How each supported LLM client is started with a per-launch MCP config.
+#:
+#: The launch interface is deliberately a data-driven registry rather than a
+#: Claude-specific code path: adding another supported client is one entry, and
+#: every client necessarily goes through the same mint-once/propagate-to-all
+#: identity mechanism because the argv builder only ever receives a config file
+#: this module wrote.
+CLIENT_LAUNCH_SPECS: dict[str, dict[str, Any]] = {
+    "claude_code": {
+        "command": "claude",
+        "config_args": lambda path: ["--mcp-config", path, "--strict-mcp-config"],
+        "docs": "claude --mcp-config <per-launch.json> --strict-mcp-config",
+    },
+}
+
+
+def supported_launch_clients() -> tuple[str, ...]:
+    """Client types with a sanctioned runnable launch path."""
+    return tuple(sorted(CLIENT_LAUNCH_SPECS))
+
+
+def build_client_launch_argv(
+    client_type: str,
+    config_path: str,
+    *,
+    extra_args: "Sequence[str] | None" = None,
+) -> list[str]:
+    """Build the argv that starts *client_type* against a per-launch config."""
+    client = mwi.normalize_client_name(client_type)
+    spec = CLIENT_LAUNCH_SPECS.get(client)
+    if spec is None:
+        raise ValueError(
+            f"no sanctioned runnable launch path for client {client!r}; "
+            f"supported clients: {list(supported_launch_clients())}"
+        )
+    argv = [str(spec["command"])] + list(spec["config_args"](str(config_path)))
+    if extra_args:
+        argv.extend(str(a) for a in extra_args)
+    return argv
+
+
+def write_launch_config(
+    mcp_servers: Mapping[str, Any],
+    *,
+    directory: str | None = None,
+) -> str:
+    """Write one launch's ``mcpServers`` config to a fresh per-launch file.
+
+    The file is per-launch and owner-readable only. #985 explicitly rules out
+    persisting an instance ID into a shared, reused ``.mcp.json``: two
+    concurrent sessions reading one static trusted ID is precisely the reuse
+    case the duplicate guard must reject. A distinct file per launch keeps the
+    minted identity bound to the launch that minted it.
+    """
+    import json
+    import tempfile
+
+    fd, path = tempfile.mkstemp(
+        prefix="gitea-mcp-launch-", suffix=".json", dir=directory
+    )
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump({"mcpServers": dict(mcp_servers)}, handle, indent=2)
+            handle.write("\n")
+    except Exception:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+        raise
+    return path
+
+
+def prepare_application_launch(
+    profile_by_namespace: Mapping[str, str],
+    *,
+    client_type: str,
+    namespaces: "Sequence[str] | None" = None,
+    config_path: str | None = None,
+    fleet_run_id: str | None = None,
+    session_id: str | None = None,
+    launch_nonce: str | None = None,
+    extra_args: "Sequence[str] | None" = None,
+    config_directory: str | None = None,
+    now=None,
+) -> dict[str, Any]:
+    """Mint one launch and produce everything needed to exec the client.
+
+    Returns the built servers, the per-launch config file path, the argv to
+    exec, and the shared trusted identity — without starting anything, so the
+    same preparation is testable and inspectable via ``--dry-run``.
+    """
+    built = build_application_mcp_servers(
+        profile_by_namespace,
+        client_type=client_type,
+        namespaces=namespaces,
+        config_path=config_path,
+        fleet_run_id=fleet_run_id,
+        session_id=session_id,
+        launch_nonce=launch_nonce,
+        now=now,
+    )
+    # Fail before writing anything if this client has no runnable path.
+    argv_probe = build_client_launch_argv(
+        client_type, "<pending>", extra_args=extra_args
+    )
+    launch_config_path = write_launch_config(
+        built["mcpServers"], directory=config_directory
+    )
+    argv = build_client_launch_argv(
+        client_type, launch_config_path, extra_args=extra_args
+    )
+    proof = collect_instance_ids_from_mcp_servers(
+        built["mcpServers"], namespaces=built["namespaces"]
+    )
+    return {
+        "client_type": built["client_type"],
+        "client_instance_id": built["client_instance_id"],
+        "namespaces": built["namespaces"],
+        "excluded_namespaces": built["excluded_namespaces"],
+        "project_scoped": built["project_scoped"],
+        "launch_config_path": launch_config_path,
+        "argv": argv,
+        "argv_template": argv_probe,
+        "mcpServers": built["mcpServers"],
+        "launch": built["launch"],
+        "shared_single_trusted_id": proof["shared_single_trusted_id"],
+        "attribution_proof": proof,
+    }
+
+
+def _parse_profile_assignments(values: "Sequence[str]") -> dict[str, str]:
+    """Parse ``namespace=profile`` CLI pairs into a mapping."""
+    profiles: dict[str, str] = {}
+    for raw in values or ():
+        text = str(raw)
+        if "=" not in text:
+            raise ValueError(
+                f"invalid --profile {text!r}; expected namespace=profile-name"
+            )
+        namespace, _, profile = text.partition("=")
+        namespace = namespace.strip().lower()
+        profile = profile.strip()
+        if not namespace or not profile:
+            raise ValueError(
+                f"invalid --profile {text!r}; expected namespace=profile-name"
+            )
+        if namespace in profiles:
+            raise ValueError(f"duplicate --profile entry for namespace {namespace!r}")
+        profiles[namespace] = profile
+    return profiles
+
+
+def main(argv: "Sequence[str] | None" = None) -> int:
+    """Runnable entry point: start a supported LLM client for one launch.
+
+    Example (project-scoped, three namespaces)::
+
+        python3 -m mcp_application_launcher \\
+            --client claude_code \\
+            --namespaces author,reviewer,merger \\
+            --profile author=prgs-author \\
+            --profile reviewer=prgs-reviewer \\
+            --profile merger=prgs-merger
+    """
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(
+        prog="mcp_application_launcher",
+        description=(
+            "Start a supported LLM client with one trusted, per-launch "
+            "GITEA_MCP_CLIENT_INSTANCE shared by every MCP namespace worker."
+        ),
+    )
+    parser.add_argument(
+        "--client",
+        default="claude_code",
+        help=f"client to launch; supported: {list(supported_launch_clients())}",
+    )
+    parser.add_argument(
+        "--namespaces",
+        default=None,
+        help=(
+            "comma-separated sanctioned namespace subset (e.g. "
+            "'author,reviewer,merger'); omit to launch all five"
+        ),
+    )
+    parser.add_argument(
+        "--profile",
+        action="append",
+        default=[],
+        metavar="NAMESPACE=PROFILE",
+        help="profile for one namespace; repeat once per launched namespace",
+    )
+    parser.add_argument("--config-path", default=None, help="profiles.json path")
+    parser.add_argument("--fleet-run-id", default=None)
+    parser.add_argument("--session-id", default=None)
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the launch plan as JSON and exit without starting anything",
+    )
+    parser.add_argument(
+        "client_args",
+        nargs=argparse.REMAINDER,
+        help="arguments forwarded to the client after '--'",
+    )
+    ns = parser.parse_args(list(argv) if argv is not None else None)
+
+    try:
+        profiles = _parse_profile_assignments(ns.profile)
+        requested = (
+            [part.strip() for part in ns.namespaces.split(",") if part.strip()]
+            if ns.namespaces
+            else None
+        )
+        resolved = resolve_launch_namespaces(requested)
+        # Profiles for namespaces that are not being launched are almost always
+        # a mistake (a stale five-namespace invocation), so refuse rather than
+        # silently ignore them.
+        stray = sorted(set(profiles) - set(resolved))
+        if stray:
+            raise ValueError(
+                f"--profile given for namespace(s) {stray} that this launch "
+                f"does not start; launched namespaces are {list(resolved)}"
+            )
+        forwarded = [a for a in (ns.client_args or []) if a != "--"]
+        prepared = prepare_application_launch(
+            profiles,
+            client_type=ns.client,
+            namespaces=requested,
+            config_path=ns.config_path,
+            fleet_run_id=ns.fleet_run_id,
+            session_id=ns.session_id,
+            extra_args=forwarded,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))
+        return 2  # pragma: no cover - argparse.error raises SystemExit
+
+    if ns.dry_run:
+        plan = {
+            key: prepared[key]
+            for key in (
+                "client_type",
+                "client_instance_id",
+                "namespaces",
+                "excluded_namespaces",
+                "project_scoped",
+                "launch_config_path",
+                "argv",
+                "shared_single_trusted_id",
+            )
+        }
+        print(json.dumps(plan, indent=2))
+        return 0
+
+    argv_to_exec = prepared["argv"]
+    os.execvp(argv_to_exec[0], argv_to_exec)
+    return 0  # pragma: no cover - execvp does not return
+
+
+if __name__ == "__main__":  # pragma: no cover - process entry point
+    raise SystemExit(main())

mcp_fleet_snapshot.py

@@ -84,6 +84,10 @@ SANCTIONED_NAMESPACES = frozenset(
 INSTANCE_ID_PROVENANCE_TRUSTED = "trusted_launcher"
 INSTANCE_ID_PROVENANCE_LEGACY = "legacy_incomplete"
 INSTANCE_ID_PROVENANCE_MISSING = "missing"
+#: Well-formed ``inst-…`` identity presented without the launcher's own
+#: provenance seal (#985). The format alone is public and reproducible, so an
+#: unsealed value is treated as manually asserted trust and fails closed.
+INSTANCE_ID_PROVENANCE_UNSEALED = "unsealed_launcher"
 
 CLIENT_INSTANCE_ENV = "GITEA_MCP_CLIENT_INSTANCE"
 FLEET_RUN_ENV = "GITEA_MCP_FLEET_RUN_ID"

root_checkout_guard.py

@@ -1,9 +1,16 @@
 """Root checkout guard (#475).
 
-The project root checkout is the stable control checkout on master/prgs/master.
-Author/reviewer/merge flows must fail closed when the control checkout is
-contaminated (wrong branch, detached HEAD, dirty, or HEAD behind/ahead of
-prgs/master). Isolated ``branches/...`` worktrees remain allowed.
+The project root checkout is the stable control checkout on its integration
+branch. Author/reviewer/merge flows must fail closed when the control checkout
+is contaminated (wrong branch, detached HEAD, dirty, or HEAD behind/ahead of the
+tracking integration ref). Isolated ``branches/...`` worktrees remain allowed.
+
+The tracking ref is *derived per repository* (#983) rather than assumed to be
+``prgs/master``: a namespace bound to another repository — say remote ``MDCPS``
+on branch ``dev`` — is gated against ``refs/remotes/MDCPS/dev``. Derivation is
+delegated to :mod:`canonical_repository_root`, the authoritative
+repository/context resolver, so gating and parity reporting share one resolved
+target instead of maintaining two disagreeing hardcoded defaults.
 """
 
 from __future__ import annotations
@@ -11,6 +18,7 @@ from __future__ import annotations
 import os
 import subprocess
 
+import canonical_repository_root
 from author_mutation_worktree import is_path_under_branches
 from reviewer_worktree import parse_dirty_tracked_files
 
@@ -20,19 +28,65 @@ REMEDIATION = (
 )
 
 BASE_BRANCHES = frozenset({"master", "main", "dev"})
+
+# Legacy PRGS-specific probe order. Retained only for callers that pass an
+# explicit ``remote_refs`` override; it is no longer the silent default, because
+# inheriting it in a non-PRGS checkout compared that checkout against a ref it
+# can never have (#983).
 REMOTE_MASTER_REFS = ("prgs/master", "refs/remotes/prgs/master")
 
 
+def _derive_probe_refs(root: str, explicit_remote: str | None) -> dict:
+    """Derive the ordered tracking refs to probe for *root*.
+
+    Returns the derivation payload from :mod:`canonical_repository_root` plus a
+    ``refs`` tuple, which is empty when the target is not provable.
+    """
+    derived = canonical_repository_root.resolve_target_base_ref(
+        root, explicit_remote=explicit_remote
+    )
+    return {
+        "refs": tuple(derived.get("tracking_refs") or ()),
+        "remote": derived.get("remote"),
+        "branch": derived.get("branch"),
+        "source": derived.get("source"),
+        "proven": bool(derived.get("proven")),
+        "reason_code": derived.get("reason_code"),
+        "reasons": list(derived.get("reasons") or []),
+        "cached_remote_head_branch": derived.get("cached_remote_head_branch"),
+        "cached_remote_head_conflicts": bool(derived.get("cached_remote_head_conflicts")),
+    }
+
+
 def resolve_remote_master_sha(
     canonical_repo_root: str,
     *,
     remote_refs: tuple[str, ...] | None = None,
+    explicit_remote: str | None = None,
 ) -> str | None:
-    """Return the commit SHA for the tracking master ref when available."""
+    """Return the commit SHA for the tracking integration ref when available.
+
+    This remains the single place that turns a ref into a SHA. Returns None when
+    the target cannot be derived or resolved — exactly what this function already
+    returned when ``rev-parse`` failed. Callers that must fail closed on missing
+    evidence (the #749/#757 bootstrap path) surface that None as *missing
+    evidence*, never as "no constraint".
+
+    *explicit_remote* is a caller-supplied disambiguation and is named that way
+    deliberately: an internally inferred remote handed back in would suppress the
+    resolver's ambiguity gate (#983 B2). No production caller supplies it.
+    """
     root = (canonical_repo_root or "").strip()
     if not root:
         return None
-    for ref in remote_refs or REMOTE_MASTER_REFS:
+    if remote_refs:
+        probe: tuple[str, ...] = tuple(remote_refs)
+    else:
+        derived = _derive_probe_refs(root, explicit_remote)
+        if not derived["proven"]:
+            return None
+        probe = derived["refs"]
+    for ref in probe:
         res = subprocess.run(
             ["git", "-C", root, "rev-parse", "--verify", ref],
             capture_output=True,
@@ -46,6 +100,84 @@ def resolve_remote_master_sha(
     return None
 
 
+def resolve_remote_master_ref_state(
+    canonical_repo_root: str,
+    *,
+    remote_refs: tuple[str, ...] | None = None,
+    explicit_remote: str | None = None,
+) -> dict:
+    """Resolve the tracking integration ref together with its commit SHA.
+
+    Returns ``sha``, the ``ref`` it came from, the derived ``remote`` /
+    ``branch``, a machine-checkable ``reason_code``, and ``reasons``. ``sha`` is
+    None whenever the target cannot be resolved — never a fallback to some other
+    repository's commit.
+
+    The SHA itself is obtained through :func:`resolve_remote_master_sha` rather
+    than by re-probing here, so one public function stays authoritative for
+    ref-to-SHA resolution. An explicit *remote_refs* keeps the historical
+    behaviour exactly: those refs are probed in order and no derivation happens.
+    """
+    root = (canonical_repo_root or "").strip()
+    state: dict = {
+        "sha": None,
+        "ref": None,
+        "remote": None,
+        "branch": None,
+        "source": None,
+        "reason_code": None,
+        "reasons": [],
+        "cached_remote_head_branch": None,
+        "cached_remote_head_conflicts": False,
+    }
+    if not root:
+        state["reasons"].append("no canonical repository root supplied (fail closed)")
+        return state
+
+    if remote_refs:
+        probe: tuple[str, ...] = tuple(remote_refs)
+        state["source"] = "explicit_remote_refs"
+    else:
+        derived = _derive_probe_refs(root, explicit_remote)
+        state["remote"] = derived["remote"]
+        state["branch"] = derived["branch"]
+        state["source"] = derived["source"]
+        state["cached_remote_head_branch"] = derived["cached_remote_head_branch"]
+        state["cached_remote_head_conflicts"] = derived["cached_remote_head_conflicts"]
+        if not derived["proven"]:
+            state["reason_code"] = derived["reason_code"]
+            state["reasons"] = derived["reasons"]
+            return state
+        probe = derived["refs"]
+
+    sha = resolve_remote_master_sha(root, remote_refs=probe, explicit_remote=explicit_remote)
+    if not sha:
+        state["reasons"].append(
+            "tracking integration ref "
+            f"{' / '.join(probe) if probe else '(none derived)'} does not resolve in "
+            f"'{root}' (fail closed)"
+        )
+        return state
+
+    state["sha"] = sha
+    # Name the ref that actually carries this commit. When the SHA comes from a
+    # test double no probe will match, so fall back to the first derived ref,
+    # which is the one the guard is conceptually comparing against.
+    for ref in probe:
+        res = subprocess.run(
+            ["git", "-C", root, "rev-parse", "--verify", ref],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if res.returncode == 0 and (res.stdout or "").strip() == sha:
+            state["ref"] = ref
+            break
+    else:
+        state["ref"] = probe[0] if probe else None
+    return state
+
+
 resolve_tracking_master_sha = resolve_remote_master_sha
 
 
@@ -59,8 +191,9 @@ def assess_root_checkout_guard(
     remote_master_sha: str | None,
     resolved_role: str | None = None,
     actual_role: str | None = None,
+    remote_master_ref: str | None = None,
 ) -> dict:
-    """Fail closed when the control checkout is not clean master/prgs/master.
+    """Fail closed when the control checkout is not clean on its integration ref.
 
     ``resolved_role`` is the preflight-resolved *task* role and ``actual_role``
     is the *active profile* role (#540). The reconciler exemption honours either
@@ -102,9 +235,13 @@ def assess_root_checkout_guard(
         )
 
     if remote_master_sha and head_sha and head_sha != remote_master_sha:
+        # #983: name the ref that was actually compared. Reporting a literal
+        # 'prgs/master' in a checkout gated against refs/remotes/MDCPS/dev sends
+        # the operator to inspect a ref that repository does not have.
+        ref_label = (remote_master_ref or "").strip() or "the tracking integration ref"
         reasons.append(
-            "control checkout HEAD does not match prgs/master "
-            f"(HEAD {head_sha[:12]}, prgs/master {remote_master_sha[:12]})"
+            f"control checkout HEAD does not match {ref_label} "
+            f"(HEAD {head_sha[:12]}, {ref_label} {remote_master_sha[:12]})"
         )
 
     proven = not reasons

tests/test_issue_978_instance_fleet_snapshot.py

@@ -1032,9 +1032,43 @@ class ClientHintsTests(unittest.TestCase):
         )
 
     def test_client_hints_trusted_when_set(self):
+        """Trusted requires the launcher seal as well as the format (#985).
+
+        Before #985 a well-formed ``inst-…`` value alone was accepted as
+        trusted. The format is public and reproducible, so anyone able to set
+        one environment variable could hand-write a valid-looking ID; #985
+        therefore additionally requires the provenance marker that only the
+        production launcher writes. This case now supplies the full sealed env
+        the launcher actually emits.
+        """
         import gitea_mcp_server as server
 
         inst = fleet.generate_client_instance_id("codex", launch_nonce="t", now=NOW)
+        with mock.patch.dict(
+            os.environ,
+            {
+                "GITEA_MCP_CLIENT": "codex",
+                "GITEA_MCP_CLIENT_INSTANCE": inst,
+                "GITEA_MCP_INSTANCE_PROVENANCE": (
+                    fleet.INSTANCE_ID_PROVENANCE_TRUSTED
+                ),
+                "GITEA_MCP_FLEET_RUN_ID": "run-1",
+            },
+            clear=False,
+        ):
+            hints = server._client_identity_hints()
+        self.assertTrue(hints["instance_identity_trusted"])
+        self.assertTrue(hints["instance_launcher_sealed"])
+        self.assertEqual(hints["client_instance_id"], inst)
+        self.assertEqual(hints["fleet_run_id"], "run-1")
+
+    def test_client_hints_wellformed_but_unsealed_not_trusted(self):
+        """#985: a valid-looking ID without the launcher seal fails closed."""
+        import gitea_mcp_server as server
+
+        inst = fleet.generate_client_instance_id(
+            "codex", launch_nonce="unsealed", now=NOW
+        )
         with mock.patch.dict(
             os.environ,
             {
@@ -1044,10 +1078,16 @@ class ClientHintsTests(unittest.TestCase):
             },
             clear=False,
         ):
+            os.environ.pop("GITEA_MCP_INSTANCE_PROVENANCE", None)
             hints = server._client_identity_hints()
-        self.assertTrue(hints["instance_identity_trusted"])
+        self.assertFalse(hints["instance_identity_trusted"])
+        self.assertFalse(hints["instance_launcher_sealed"])
+        # Still reported for diagnosis rather than silently discarded.
         self.assertEqual(hints["client_instance_id"], inst)
-        self.assertEqual(hints["fleet_run_id"], "run-1")
+        self.assertEqual(
+            hints["instance_id_provenance"],
+            fleet.INSTANCE_ID_PROVENANCE_UNSEALED,
+        )
 
     def test_malformed_user_supplied_instance_not_trusted(self):
         import gitea_mcp_server as server

tests/test_issue_983_cross_repo_base_ref.py

@@ -0,0 +1,692 @@
+"""Regression tests for Issue #983: derived target base ref for cross-repository checkouts.
+
+The mutation guard previously assumed ``prgs/master`` and the parity report
+assumed ``origin/master``. Any repository using neither — for example remote
+``MDCPS`` on integration branch ``dev`` — could not prove base equivalence, so
+every gated mutation failed closed with no reachable remedy.
+
+Two further defects were found by review at head ``2d5d5c9d`` and are covered
+here:
+
+* **B1** — the first fix derived the integration branch from
+  ``refs/remotes/<remote>/HEAD``. That symref is a *local cache* written at clone
+  time and never refreshed by fetch, so on the real Weekly Briefings target it
+  still named ``main`` while the checkout tracked and sat exactly on ``dev``. The
+  authoritative signal is the checkout's own configured upstream. The fixtures
+  below therefore reproduce the **disagreement**: the cache says ``main``, the
+  configured upstream says ``dev``, and ``dev`` must win.
+* **B2** — the parity report passed its internally inferred identity remote back
+  into the resolver, which reads a caller-supplied remote as "the caller already
+  disambiguated" and skips its ambiguity gate. Gating and reporting could then
+  evaluate different repositories. An inferred remote is now never laundered into
+  explicit caller intent, and ambiguity fails closed on both sides.
+
+These tests build hermetic git repositories on disk (no network, no fetch) and
+assert the derived target end to end: identity remote, integration branch,
+tracking ref, fail-closed refusals, and agreement between the mutation guard and
+the parity report.
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+import subprocess
+import tempfile
+import unittest
+
+import anti_stomp_preflight
+import canonical_repository_root as crr
+import master_parity_gate
+import root_checkout_guard
+
+MDCPS_URL = "https://gitea.example.net/MDCPS/WeeklyBriefings-Meta.git"
+MDCPS_SLUG = "MDCPS/WeeklyBriefings-Meta"
+PRGS_URL = "https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools.git"
+PRGS_SLUG = "Scaled-Tech-Consulting/Gitea-Tools"
+
+
+def _git(root: str, *args: str) -> str:
+    res = subprocess.run(
+        ["git", "-C", root, *args],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return (res.stdout or "").strip()
+
+
+def _make_repo(root: str, *, remote: str | None, url: str | None) -> str:
+    """Initialise a repository with one commit and an optional named remote."""
+    os.makedirs(root, exist_ok=True)
+    _git(root, "init", "--quiet")
+    _git(root, "config", "user.email", "[email protected]")
+    _git(root, "config", "user.name", "Issue983 Test")
+    _git(root, "config", "commit.gpgsign", "false")
+    with open(os.path.join(root, "seed.txt"), "w", encoding="utf-8") as fh:
+        fh.write("seed\n")
+    _git(root, "add", "seed.txt")
+    _git(root, "commit", "--quiet", "-m", "seed")
+    if remote and url:
+        _git(root, "remote", "add", remote, url)
+    return _git(root, "rev-parse", "HEAD")
+
+
+def _set_remote_branch(root: str, remote: str, branch: str, sha: str) -> None:
+    """Create refs/remotes/<remote>/<branch> without contacting a network."""
+    _git(root, "update-ref", f"refs/remotes/{remote}/{branch}", sha)
+
+
+def _set_remote_head(root: str, remote: str, branch: str) -> None:
+    """Write the *cached* refs/remotes/<remote>/HEAD symref.
+
+    This is the signal B1 proved untrustworthy. Fixtures use it to reproduce a
+    stale cache, never to manufacture the answer under test.
+    """
+    _git(
+        root,
+        "symbolic-ref",
+        f"refs/remotes/{remote}/HEAD",
+        f"refs/remotes/{remote}/{branch}",
+    )
+
+
+def _set_upstream(root: str, remote: str, branch: str) -> None:
+    """Configure the current branch's upstream, exactly as git tracking does.
+
+    Writes ``branch.<current>.remote`` / ``branch.<current>.merge`` directly
+    rather than via ``--set-upstream-to`` so no ref is required to pre-exist and
+    no network is touched.
+    """
+    current = _git(root, "symbolic-ref", "--short", "HEAD")
+    _git(root, "config", f"branch.{current}.remote", remote)
+    _git(root, "config", f"branch.{current}.merge", f"refs/heads/{branch}")
+
+
+def _checkout_new_branch(root: str, branch: str) -> None:
+    _git(root, "checkout", "--quiet", "-b", branch)
+
+
+def _advance(root: str, message: str) -> str:
+    with open(os.path.join(root, "seed.txt"), "a", encoding="utf-8") as fh:
+        fh.write(message + "\n")
+    _git(root, "add", "seed.txt")
+    _git(root, "commit", "--quiet", "-m", message)
+    return _git(root, "rev-parse", "HEAD")
+
+
+class _RepoCase(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.root = os.path.join(self._tmp.name, "repo")
+
+    def _weekly_briefings_shape(self) -> str:
+        """The real Weekly Briefings target, including its stale cache.
+
+        Remote ``MDCPS``; checked out on ``dev``; upstream configured to
+        ``MDCPS/dev``; both ``dev`` and ``main`` present as tracking refs; and
+        ``refs/remotes/MDCPS/HEAD`` still cached at ``main`` from clone time.
+        """
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _checkout_new_branch(self.root, "dev")
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        stale = _advance(self.root, "main diverged long ago")
+        _set_remote_branch(self.root, "MDCPS", "main", stale)
+        _git(self.root, "reset", "--hard", "--quiet", head)
+        _set_remote_head(self.root, "MDCPS", "main")  # stale clone-time cache
+        _set_upstream(self.root, "MDCPS", "dev")  # authoritative
+        return head
+
+
+class TestPrgsBehaviourPreserved(_RepoCase):
+    """Required coverage 1: PRGS prgs/master compatibility."""
+
+    def _prgs(self) -> str:
+        head = _make_repo(self.root, remote="prgs", url=PRGS_URL)
+        _set_remote_branch(self.root, "prgs", "master", head)
+        _set_remote_head(self.root, "prgs", "master")
+        _set_upstream(self.root, "prgs", "master")
+        return head
+
+    def test_prgs_master_resolves_unchanged(self):
+        head = self._prgs()
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["remote"], "prgs")
+        self.assertEqual(got["branch"], "master")
+        self.assertEqual(got["tracking_ref"], "refs/remotes/prgs/master")
+        self.assertEqual(got["repository_slug"], PRGS_SLUG)
+        self.assertEqual(got["source"], crr.BASE_REF_SOURCE_CONFIGURED_UPSTREAM)
+        # Cache and upstream agree here, which is the ordinary PRGS state.
+        self.assertFalse(got["cached_remote_head_conflicts"])
+        self.assertEqual(root_checkout_guard.resolve_remote_master_sha(self.root), head)
+
+    def test_prgs_resolves_without_a_configured_upstream(self):
+        """A PRGS checkout with no tracking config still resolves master."""
+        head = _make_repo(self.root, remote="prgs", url=PRGS_URL)
+        _set_remote_branch(self.root, "prgs", "master", head)
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["tracking_ref"], "refs/remotes/prgs/master")
+        self.assertEqual(got["source"], crr.BASE_REF_SOURCE_UNIQUE_CANDIDATE)
+
+    def test_legacy_explicit_remote_refs_path_is_untouched(self):
+        """An explicit remote_refs override still short-circuits derivation."""
+        head = _make_repo(self.root, remote="prgs", url=PRGS_URL)
+        _set_remote_branch(self.root, "prgs", "master", head)
+
+        state = root_checkout_guard.resolve_remote_master_ref_state(
+            self.root, remote_refs=root_checkout_guard.REMOTE_MASTER_REFS
+        )
+        self.assertEqual(state["sha"], head)
+        self.assertEqual(state["source"], "explicit_remote_refs")
+
+
+class TestStaleCachedRemoteHead(_RepoCase):
+    """Required coverage 3: configured upstream MDCPS/dev vs stale cache -> main.
+
+    This is B1. The fixture deliberately does **not** point
+    ``refs/remotes/MDCPS/HEAD`` at ``dev``; it reproduces the disagreement that
+    was live on ``/Users/jasonwalker/Development/weekly-briefings``.
+    """
+
+    def test_configured_upstream_beats_stale_cached_remote_head(self):
+        head = self._weekly_briefings_shape()
+
+        # Precondition: the fixture really is in the defective state.
+        self.assertEqual(
+            _git(self.root, "symbolic-ref", "refs/remotes/MDCPS/HEAD"),
+            "refs/remotes/MDCPS/main",
+        )
+        self.assertEqual(_git(self.root, "config", "--get", "branch.dev.merge"), "refs/heads/dev")
+        self.assertNotEqual(
+            _git(self.root, "rev-parse", "refs/remotes/MDCPS/main"),
+            _git(self.root, "rev-parse", "refs/remotes/MDCPS/dev"),
+        )
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["branch"], "dev")
+        self.assertEqual(got["tracking_ref"], "refs/remotes/MDCPS/dev")
+        self.assertEqual(got["source"], crr.BASE_REF_SOURCE_CONFIGURED_UPSTREAM)
+        # The stale cache is reported, never obeyed.
+        self.assertEqual(got["cached_remote_head_branch"], "main")
+        self.assertTrue(got["cached_remote_head_conflicts"])
+        self.assertEqual(root_checkout_guard.resolve_remote_master_sha(self.root), head)
+
+    def test_checkout_on_its_integration_tip_is_not_blocked(self):
+        """The live symptom: a checkout exactly on its tip was reported stale."""
+        head = self._weekly_briefings_shape()
+
+        state = root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        self.assertEqual(state["sha"], head)
+        self.assertTrue(state["cached_remote_head_conflicts"])
+
+        assessment = root_checkout_guard.assess_root_checkout_guard(
+            workspace_path=self.root,
+            canonical_repo_root=self.root,
+            current_branch="dev",
+            head_sha=head,
+            porcelain_status="",
+            remote_master_sha=state["sha"],
+            remote_master_ref=state["ref"],
+        )
+        self.assertTrue(assessment["proven"], assessment["reasons"])
+
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertFalse(report["stale"])
+        self.assertEqual(report["base_branch"], "dev")
+        self.assertEqual(report["reasons"], [])
+
+    def test_cached_remote_head_alone_never_proves_a_target(self):
+        """With no configured upstream, the cache cannot supply the branch."""
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        # Only a non-candidate branch exists, and only the cache names it.
+        _set_remote_branch(self.root, "MDCPS", "trunk", head)
+        _set_remote_head(self.root, "MDCPS", "trunk")
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_NO_BASE_BRANCH)
+        self.assertEqual(got["tracking_refs"], ())
+        self.assertEqual(got["cached_remote_head_branch"], "trunk")
+        # The refusal names the misleading signal so an operator is not sent
+        # chasing a ref that looks authoritative.
+        self.assertIn("trunk", " ".join(got["reasons"]))
+
+    def test_cached_remote_head_never_breaks_a_tie(self):
+        """Two candidates, no upstream: the cache must not decide."""
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "MDCPS", "main", head)
+        _set_remote_head(self.root, "MDCPS", "dev")
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_AMBIGUOUS_BASE_BRANCH)
+        self.assertIsNone(root_checkout_guard.resolve_remote_master_sha(self.root))
+
+    def test_no_proven_source_is_the_remote_head_cache(self):
+        """Structural guard: the cache is not in the set of proving sources."""
+        sources = {
+            crr.BASE_REF_SOURCE_CONFIGURED_UPSTREAM,
+            crr.BASE_REF_SOURCE_UNIQUE_CANDIDATE,
+        }
+        self.assertNotIn("remote_head_symref", sources)
+        self.assertFalse(hasattr(crr, "BASE_REF_SOURCE_REMOTE_HEAD"))
+
+
+class TestCrossRepositoryTarget(_RepoCase):
+    """Required coverage 2/4/5: MDCPS/dev, no origin remote, exact case."""
+
+    def test_mdcps_dev_resolves(self):
+        head = self._weekly_briefings_shape()
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["remote"], "MDCPS")
+        self.assertEqual(got["branch"], "dev")
+        self.assertEqual(got["tracking_ref"], "refs/remotes/MDCPS/dev")
+        self.assertEqual(got["repository_slug"], MDCPS_SLUG)
+        self.assertEqual(root_checkout_guard.resolve_remote_master_sha(self.root), head)
+
+    def test_no_remote_named_origin(self):
+        self._weekly_briefings_shape()
+        self.assertEqual(_git(self.root, "remote"), "MDCPS")
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertNotIn("origin", got["tracking_ref"])
+
+    def test_remote_name_case_is_preserved_exactly(self):
+        self._weekly_briefings_shape()
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertEqual(got["remote"], "MDCPS")
+        self.assertNotEqual(got["remote"], "mdcps")
+        # The tracking ref must address the real ref, which is case-sensitive.
+        self.assertEqual(got["tracking_ref"], "refs/remotes/MDCPS/dev")
+        self.assertTrue(
+            _git(self.root, "rev-parse", "--verify", got["tracking_ref"]),
+            "case-preserved tracking ref must resolve",
+        )
+
+    def test_lowercase_candidate_never_supplies_the_remote_name(self):
+        """Guards against silently case-folding MDCPS to the candidate 'mdcps'.
+
+        ``_IDENTITY_REMOTE_CANDIDATES`` contains a lowercase ``mdcps`` entry and
+        is probed *before* the repository's own remote listing. Git remote names
+        live in case-sensitive config subsections on every platform, so the
+        lowercase probe cannot resolve and the exact-case name must arrive from
+        ``git remote``. Asserted through config rather than ref lookup because a
+        case-insensitive filesystem (macOS) resolves loose refs either way, which
+        would make a ref-based assertion test the filesystem instead of the code.
+        """
+        self._weekly_briefings_shape()
+        res = subprocess.run(
+            ["git", "-C", self.root, "remote", "get-url", "mdcps"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        self.assertNotEqual(res.returncode, 0, "git remote names are case-sensitive")
+
+        # A caller naming the wrong case cannot disambiguate, but the target is
+        # unambiguous anyway, so the exact-case name is still resolved.
+        got = crr.resolve_target_base_ref(self.root, explicit_remote="mdcps")
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["remote"], "MDCPS")
+        self.assertEqual(got["tracking_ref"], "refs/remotes/MDCPS/dev")
+        self.assertFalse(got["identity_explicit"], "a non-matching name is not explicit intent")
+
+        name, slug = crr.resolve_identity_remote(self.root)
+        self.assertEqual(name, "MDCPS")
+        self.assertEqual(slug, MDCPS_SLUG)
+
+
+class TestTargetStaleness(_RepoCase):
+    """Required coverage 6/7: matching tip, and behind or divergent checkout."""
+
+    def test_local_equal_to_resolved_tip_is_not_stale(self):
+        self._weekly_briefings_shape()
+        got = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertTrue(got["determinable"])
+        self.assertFalse(got["stale"])
+        self.assertEqual(got["tracking_ref"], "refs/remotes/MDCPS/dev")
+        self.assertEqual(got["base_remote"], "MDCPS")
+        self.assertEqual(got["base_branch"], "dev")
+        self.assertIsNone(got["reason_code"])
+
+    def test_local_behind_resolved_tip_is_stale(self):
+        head = self._weekly_briefings_shape()
+        advanced = _advance(self.root, "remote moved on")
+        _set_remote_branch(self.root, "MDCPS", "dev", advanced)
+        _git(self.root, "reset", "--hard", "--quiet", head)
+
+        got = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertTrue(got["determinable"])
+        self.assertTrue(got["stale"])
+        self.assertEqual(got["checkout_head"], head)
+        self.assertEqual(got["remote_tracking_head"], advanced)
+
+    def test_local_divergent_from_resolved_tip_is_stale(self):
+        head = self._weekly_briefings_shape()
+        remote_side = _advance(self.root, "remote side")
+        _set_remote_branch(self.root, "MDCPS", "dev", remote_side)
+        _git(self.root, "reset", "--hard", "--quiet", head)
+        local_side = _advance(self.root, "local side")
+
+        got = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertTrue(got["stale"])
+        self.assertEqual(got["checkout_head"], local_side)
+        self.assertNotEqual(local_side, remote_side)
+
+
+class TestFailClosed(_RepoCase):
+    """Required coverage 8/9: missing remote or ref, and ambiguous targets."""
+
+    def test_missing_remote_fails_closed(self):
+        _make_repo(self.root, remote=None, url=None)
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_NO_IDENTITY_REMOTE)
+        self.assertEqual(got["tracking_refs"], ())
+        self.assertIsNone(root_checkout_guard.resolve_remote_master_sha(self.root))
+
+    def test_missing_tracking_ref_fails_closed(self):
+        _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        # Remote configured, but nothing has ever been fetched.
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_NO_BASE_BRANCH)
+        self.assertIsNone(root_checkout_guard.resolve_remote_master_sha(self.root))
+
+    def test_configured_upstream_without_a_tracking_ref_fails_closed(self):
+        """A proven target always names a ref that resolves."""
+        _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _set_upstream(self.root, "MDCPS", "dev")  # declared, never fetched
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_NO_BASE_BRANCH)
+        self.assertIsNone(got["tracking_ref"])
+
+    def test_every_proven_target_resolves(self):
+        """No 'proven' result may name an unresolvable tracking ref."""
+        head = self._weekly_briefings_shape()
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertTrue(got["proven"])
+        self.assertEqual(_git(self.root, "rev-parse", got["tracking_ref"]), head)
+
+    def test_ambiguous_integration_branch_fails_closed(self):
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        # Two candidate integration branches and no configured upstream.
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "MDCPS", "main", head)
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_AMBIGUOUS_BASE_BRANCH)
+        self.assertIsNone(root_checkout_guard.resolve_remote_master_sha(self.root))
+
+    def test_ambiguous_identity_remote_fails_closed(self):
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _git(self.root, "remote", "add", "prgs", PRGS_URL)
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "prgs", "master", head)
+
+        got = crr.resolve_target_base_ref(self.root)
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_AMBIGUOUS_REMOTE)
+        self.assertEqual(got["tracking_refs"], ())
+
+    def test_orphan_tracking_ref_from_removed_remote_is_ignored(self):
+        """The live Gitea-Tools symptom: refs/remotes/origin/* outlives its remote."""
+        head = _make_repo(self.root, remote="prgs", url=PRGS_URL)
+        _set_remote_branch(self.root, "prgs", "master", head)
+        _set_upstream(self.root, "prgs", "master")
+        # An abandoned ref left behind by a remote that no longer exists.
+        _set_remote_branch(self.root, "origin", "master", head)
+        _advance(self.root, "orphan must not be consulted")
+
+        got = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertEqual(got["tracking_ref"], "refs/remotes/prgs/master")
+        self.assertEqual(got["repository_slug"], PRGS_SLUG)
+        self.assertNotIn(
+            "target repository identity could not be derived from its git remote",
+            got["reasons"],
+        )
+
+
+class TestExplicitVersusInferredRemote(_RepoCase):
+    """Required coverage 11: explicit disambiguation stays distinct from inference.
+
+    This is B2. A remote the module inferred while probing must never re-enter
+    the resolver as though an operator had named it.
+    """
+
+    def _two_remotes(self) -> str:
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _git(self.root, "remote", "add", "prgs", PRGS_URL)
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "prgs", "master", head)
+        return head
+
+    def test_explicit_remote_disambiguates(self):
+        self._two_remotes()
+        got = crr.resolve_target_base_ref(self.root, explicit_remote="MDCPS")
+        self.assertTrue(got["proven"], got["reasons"])
+        self.assertEqual(got["remote"], "MDCPS")
+        self.assertEqual(got["branch"], "dev")
+        self.assertTrue(got["identity_explicit"])
+
+    def test_inferred_remote_does_not_disambiguate(self):
+        """Feeding the inferred remote back in must not unlock the target."""
+        self._two_remotes()
+        inferred, _ = crr.resolve_identity_remote(self.root)
+        self.assertIsNotNone(inferred, "the first-wins probe still returns a name")
+
+        # The report infers internally and must still refuse.
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertEqual(report["reason_code"], crr.DENY_AMBIGUOUS_REMOTE)
+        self.assertIsNone(report["repository_slug"])
+        self.assertIsNone(report["tracking_ref"])
+        self.assertFalse(report["stale"])
+        self.assertTrue(report["reasons"])
+
+    def test_report_never_passes_a_remote_into_the_resolver(self):
+        """Structural guard against the exact B2 regression."""
+        src = inspect.getsource(master_parity_gate.assess_target_repository_parity)
+        self.assertIn("resolve_target_base_ref(canonical_root)", src)
+        self.assertNotIn("resolve_target_base_ref(canonical_root, remote=", src)
+        self.assertNotIn("explicit_remote=identity", src)
+        # Reporting must use the ambiguity-aware identity resolver.
+        self.assertIn("assess_identity_remote(canonical_root)", src)
+
+    def test_explicit_parameter_is_named_for_its_meaning(self):
+        for fn in (
+            crr.resolve_target_base_ref,
+            root_checkout_guard.resolve_remote_master_sha,
+            root_checkout_guard.resolve_remote_master_ref_state,
+        ):
+            params = inspect.signature(fn).parameters
+            self.assertIn("explicit_remote", params, fn.__name__)
+            self.assertNotIn("remote", params, fn.__name__)
+
+    def test_unmatched_explicit_remote_cannot_unlock_an_ambiguous_target(self):
+        self._two_remotes()
+        got = crr.resolve_target_base_ref(self.root, explicit_remote="nonexistent")
+        self.assertFalse(got["proven"])
+        self.assertEqual(got["reason_code"], crr.DENY_AMBIGUOUS_REMOTE)
+
+
+class TestGatingAndReportingAgree(_RepoCase):
+    """Required coverage 10: guard and parity report make identical decisions."""
+
+    def test_same_resolved_target_for_gate_and_report(self):
+        self._weekly_briefings_shape()
+
+        gate = root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+
+        self.assertEqual(gate["remote"], report["base_remote"])
+        self.assertEqual(gate["branch"], report["base_branch"])
+        self.assertEqual(gate["sha"], report["remote_tracking_head"])
+        self.assertIn(
+            gate["ref"],
+            (report["tracking_ref"], f"{gate['remote']}/{gate['branch']}"),
+        )
+
+    def test_both_sides_refuse_the_same_unresolvable_target(self):
+        _make_repo(self.root, remote=None, url=None)
+
+        gate = root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertIsNone(gate["sha"])
+        self.assertIsNone(report["remote_tracking_head"])
+        self.assertFalse(report["stale"])
+        self.assertTrue(report["reasons"])
+        self.assertEqual(gate["reason_code"], report["reason_code"])
+
+    def test_both_sides_refuse_the_same_ambiguous_target(self):
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _git(self.root, "remote", "add", "prgs", PRGS_URL)
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "prgs", "master", head)
+
+        gate = root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+
+        self.assertIsNone(gate["sha"])
+        self.assertEqual(gate["reason_code"], crr.DENY_AMBIGUOUS_REMOTE)
+        # The report must not name a repository the gate refuses to act on.
+        self.assertEqual(report["reason_code"], gate["reason_code"])
+        self.assertIsNone(report["repository_slug"])
+        self.assertIsNone(report["base_remote"])
+        self.assertIsNone(report["base_branch"])
+        self.assertFalse(report["stale"])
+
+    def test_both_sides_refuse_the_same_ambiguous_branch(self):
+        head = _make_repo(self.root, remote="MDCPS", url=MDCPS_URL)
+        _set_remote_branch(self.root, "MDCPS", "dev", head)
+        _set_remote_branch(self.root, "MDCPS", "main", head)
+
+        gate = root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        report = master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+        self.assertEqual(gate["reason_code"], crr.DENY_AMBIGUOUS_BASE_BRANCH)
+        self.assertEqual(report["reason_code"], gate["reason_code"])
+        self.assertIsNone(report["tracking_ref"])
+
+
+class TestProductionCallers(unittest.TestCase):
+    """Required coverage 13: every production caller consumes the same target."""
+
+    def test_guard_reports_the_ref_it_actually_compared(self):
+        assessment = root_checkout_guard.assess_root_checkout_guard(
+            workspace_path="/tmp/nonexistent-workspace-983",
+            canonical_repo_root="/tmp/nonexistent-root-983",
+            current_branch="dev",
+            head_sha="a" * 40,
+            porcelain_status="",
+            remote_master_sha="b" * 40,
+            remote_master_ref="refs/remotes/MDCPS/dev",
+        )
+        self.assertTrue(assessment["block"])
+        joined = " ".join(assessment["reasons"])
+        self.assertIn("refs/remotes/MDCPS/dev", joined)
+        self.assertNotIn("prgs/master", joined)
+
+    def test_guard_message_without_a_ref_stays_generic(self):
+        assessment = root_checkout_guard.assess_root_checkout_guard(
+            workspace_path="/tmp/nonexistent-workspace-983",
+            canonical_repo_root="/tmp/nonexistent-root-983",
+            current_branch="master",
+            head_sha="a" * 40,
+            porcelain_status="",
+            remote_master_sha="b" * 40,
+        )
+        joined = " ".join(assessment["reasons"])
+        self.assertIn("the tracking integration ref", joined)
+        self.assertNotIn("prgs/master", joined)
+
+    def test_anti_stomp_preflight_forwards_the_resolved_ref(self):
+        sig = inspect.signature(anti_stomp_preflight.assess_anti_stomp_preflight)
+        self.assertIn("remote_master_ref", sig.parameters)
+        src = inspect.getsource(anti_stomp_preflight.assess_anti_stomp_preflight)
+        self.assertIn("remote_master_ref=remote_master_ref", src)
+
+    def test_no_production_caller_inherits_the_prgs_default(self):
+        """Every resolve site must derive, or pass remote_refs explicitly."""
+        import gitea_mcp_server
+
+        src = inspect.getsource(gitea_mcp_server)
+        # The four historical call sites now consume the resolved-target state.
+        self.assertGreaterEqual(src.count("resolve_remote_master_ref_state("), 4)
+        self.assertNotIn("resolve_remote_master_sha(canonical_root)", src)
+
+    def test_no_production_caller_supplies_an_explicit_remote(self):
+        """Nothing in production may suppress the ambiguity gate (#983 B2)."""
+        import gitea_mcp_server
+
+        for module in (gitea_mcp_server, anti_stomp_preflight, master_parity_gate):
+            src = inspect.getsource(module)
+            self.assertNotIn("explicit_remote=", src, module.__name__)
+
+
+class TestRepositoryStructureUntouched(_RepoCase):
+    """Required coverage 12: resolution mutates no ref, remote, config, or checkout."""
+
+    def test_resolution_creates_no_refs_or_branches(self):
+        self._weekly_briefings_shape()
+
+        fmt = "--format=%(refname) %(objectname)"
+        before_refs = _git(self.root, "for-each-ref", fmt)
+        before_remotes = _git(self.root, "remote")
+        before_config = _git(self.root, "config", "--local", "--list")
+        before_head = _git(self.root, "rev-parse", "HEAD")
+        before_branch = _git(self.root, "symbolic-ref", "--short", "HEAD")
+        before_status = _git(self.root, "status", "--porcelain", "--untracked-files=all")
+        before_symref = _git(self.root, "symbolic-ref", "refs/remotes/MDCPS/HEAD")
+
+        crr.resolve_target_base_ref(self.root)
+        crr.assess_identity_remote(self.root)
+        root_checkout_guard.resolve_remote_master_sha(self.root)
+        root_checkout_guard.resolve_remote_master_ref_state(self.root)
+        master_parity_gate.assess_target_repository_parity(
+            canonical_root=self.root, source="test"
+        )
+
+        self.assertEqual(_git(self.root, "for-each-ref", fmt), before_refs)
+        self.assertEqual(_git(self.root, "remote"), before_remotes)
+        self.assertEqual(_git(self.root, "config", "--local", "--list"), before_config)
+        self.assertEqual(_git(self.root, "rev-parse", "HEAD"), before_head)
+        self.assertEqual(_git(self.root, "symbolic-ref", "--short", "HEAD"), before_branch)
+        self.assertEqual(
+            _git(self.root, "status", "--porcelain", "--untracked-files=all"), before_status
+        )
+        # The stale cache is specifically NOT repaired: that would be a mutation.
+        self.assertEqual(_git(self.root, "symbolic-ref", "refs/remotes/MDCPS/HEAD"), before_symref)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_issue_985_project_scoped_launcher.py

@@ -0,0 +1,664 @@
+"""#985 — trusted client-instance identity for project-scoped LLM launches.
+
+Covers the acceptance criteria of issue #985:
+
+* a three-namespace (author/reviewer/merger) launch succeeds with no
+  controller or reconciler profile,
+* every worker of one launch shares exactly one trusted instance ID,
+* two concurrent launches receive distinct IDs and stay distinguishable,
+* reuse, missing, legacy, malformed, unsanctioned, and unsealed identities all
+  fail closed,
+* the existing five-namespace behaviour is unchanged,
+* Claude Code has a documented, runnable launch command.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import mcp_application_launcher as launcher  # noqa: E402
+import mcp_fleet_snapshot as fleet  # noqa: E402
+
+NOW = _dt.datetime(2026, 7, 31, 12, 0, 0, tzinfo=_dt.timezone.utc)
+
+PROJECT_NAMESPACES = ("author", "reviewer", "merger")
+ALL_NAMESPACES = ("author", "reviewer", "merger", "controller", "reconciler")
+
+#: A project-scoped configuration intentionally has no controller/reconciler
+#: profile — that absence is the condition under test, not an omission.
+PROJECT_PROFILES = {ns: f"prgs-{ns}" for ns in PROJECT_NAMESPACES}
+FULL_PROFILES = {ns: f"prgs-{ns}" for ns in ALL_NAMESPACES}
+
+
+def _instance_ids(servers):
+    return {
+        name: entry["env"][launcher.CLIENT_INSTANCE_ENV]
+        for name, entry in servers.items()
+    }
+
+
+class ResolveLaunchNamespacesTests(unittest.TestCase):
+    """The validated subset allow-list."""
+
+    def test_none_resolves_to_all_five_in_canonical_order(self):
+        self.assertEqual(
+            launcher.resolve_launch_namespaces(None), tuple(ALL_NAMESPACES)
+        )
+
+    def test_project_subset_resolves_in_canonical_order(self):
+        # Deliberately out of order on input; canonical order on output.
+        self.assertEqual(
+            launcher.resolve_launch_namespaces(["merger", "author", "reviewer"]),
+            ("author", "reviewer", "merger"),
+        )
+
+    def test_case_and_whitespace_normalised(self):
+        self.assertEqual(
+            launcher.resolve_launch_namespaces([" Author ", "REVIEWER"]),
+            ("author", "reviewer"),
+        )
+
+    def test_unsanctioned_namespace_refused(self):
+        with self.assertRaises(ValueError) as ctx:
+            launcher.resolve_launch_namespaces(["author", "admin"])
+        self.assertIn("admin", str(ctx.exception))
+
+    def test_typo_is_refused_not_silently_dropped(self):
+        with self.assertRaises(ValueError):
+            launcher.resolve_launch_namespaces(["author", "reviewr"])
+
+    def test_empty_subset_refused(self):
+        with self.assertRaises(ValueError):
+            launcher.resolve_launch_namespaces([])
+        with self.assertRaises(ValueError):
+            launcher.resolve_launch_namespaces(["   "])
+
+    def test_duplicate_namespace_refused(self):
+        with self.assertRaises(ValueError):
+            launcher.resolve_launch_namespaces(["author", "author"])
+
+
+class ProjectScopedLaunchTests(unittest.TestCase):
+    """AC: three-namespace launch without controller/reconciler profiles."""
+
+    def _build(self, **kwargs):
+        kwargs.setdefault("client_type", "claude_code")
+        kwargs.setdefault("namespaces", PROJECT_NAMESPACES)
+        kwargs.setdefault("command", "python3")
+        kwargs.setdefault("args", ["mcp_server.py"])
+        profiles = kwargs.pop("profiles", PROJECT_PROFILES)
+        return launcher.build_application_mcp_servers(profiles, **kwargs)
+
+    def test_three_namespace_launch_succeeds_without_controller_reconciler(self):
+        built = self._build(launch_nonce="proj-1", now=NOW)
+        servers = built["mcpServers"]
+        self.assertEqual(
+            sorted(servers), ["gitea-author", "gitea-merger", "gitea-reviewer"]
+        )
+        self.assertEqual(built["namespace_count"], 3)
+        self.assertEqual(list(built["namespaces"]), list(PROJECT_NAMESPACES))
+
+    def test_excluded_namespaces_are_not_started(self):
+        built = self._build(launch_nonce="proj-2", now=NOW)
+        self.assertNotIn("gitea-controller", built["mcpServers"])
+        self.assertNotIn("gitea-reconciler", built["mcpServers"])
+        self.assertEqual(
+            sorted(built["excluded_namespaces"]), ["controller", "reconciler"]
+        )
+        self.assertTrue(built["project_scoped"])
+
+    def test_all_workers_of_one_launch_share_one_trusted_id(self):
+        built = self._build(launch_nonce="proj-3", now=NOW)
+        ids = set(_instance_ids(built["mcpServers"]).values())
+        self.assertEqual(len(ids), 1, ids)
+        shared = next(iter(ids))
+        self.assertTrue(fleet.assess_instance_identity(shared)["trusted"])
+        self.assertEqual(built["client_instance_id"], shared)
+
+    def test_every_worker_env_is_launcher_sealed(self):
+        built = self._build(launch_nonce="proj-4", now=NOW)
+        for name, entry in built["mcpServers"].items():
+            env = entry["env"]
+            self.assertEqual(
+                env[launcher.INSTANCE_PROVENANCE_ENV],
+                fleet.INSTANCE_ID_PROVENANCE_TRUSTED,
+                name,
+            )
+            self.assertEqual(env["GITEA_CLIENT_MANAGED"], "1", name)
+            self.assertFalse(
+                env[launcher.CLIENT_INSTANCE_ENV].startswith("legacy-"), name
+            )
+
+    def test_attribution_proof_holds_for_three_namespace_launch(self):
+        """A subset launch must not read as 'missing two workers'."""
+        built = self._build(launch_nonce="proj-5", now=NOW)
+        proof = launcher.collect_instance_ids_from_mcp_servers(
+            built["mcpServers"], namespaces=PROJECT_NAMESPACES
+        )
+        self.assertTrue(proof["shared_single_trusted_id"], proof)
+        self.assertEqual(proof["missing_servers"], [])
+        # And without an explicit expectation it inspects what is present.
+        inferred = launcher.collect_instance_ids_from_mcp_servers(
+            built["mcpServers"]
+        )
+        self.assertTrue(inferred["shared_single_trusted_id"], inferred)
+
+    def test_missing_profile_for_requested_namespace_refused(self):
+        with self.assertRaises(ValueError) as ctx:
+            self._build(profiles={"author": "prgs-author"})
+        self.assertIn("merger", str(ctx.exception))
+
+    def test_profile_for_unlaunched_namespace_is_ignored_not_started(self):
+        """Extra profiles never widen the launch beyond the validated subset."""
+        built = self._build(profiles=FULL_PROFILES, launch_nonce="proj-6", now=NOW)
+        self.assertEqual(len(built["mcpServers"]), 3)
+        self.assertNotIn("gitea-controller", built["mcpServers"])
+
+    def test_unsanctioned_namespace_refused_at_build(self):
+        with self.assertRaises(ValueError):
+            self._build(
+                profiles={**PROJECT_PROFILES, "admin": "prgs-admin"},
+                namespaces=["author", "admin"],
+            )
+
+
+class ConcurrentLaunchDistinctionTests(unittest.TestCase):
+    """AC: concurrent launches are distinct and distinguishable."""
+
+    def _build(self, nonce, namespaces=PROJECT_NAMESPACES, profiles=None):
+        return launcher.build_application_mcp_servers(
+            profiles or PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=namespaces,
+            launch_nonce=nonce,
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+
+    def test_two_concurrent_launches_receive_different_ids(self):
+        a = self._build("concurrent-a")
+        b = self._build("concurrent-b")
+        self.assertNotEqual(a["client_instance_id"], b["client_instance_id"])
+
+    def test_same_profile_across_launches_stays_distinguishable(self):
+        """Same profile, two launches: distinguishable, so not a false duplicate."""
+        a = self._build("dist-a")
+        b = self._build("dist-b")
+        a_author = a["mcpServers"]["gitea-author"]["env"]
+        b_author = b["mcpServers"]["gitea-author"]["env"]
+        # Same profile on purpose — that alone must never imply duplication.
+        self.assertEqual(a_author["GITEA_MCP_PROFILE"], b_author["GITEA_MCP_PROFILE"])
+        self.assertNotEqual(
+            a_author[launcher.CLIENT_INSTANCE_ENV],
+            b_author[launcher.CLIENT_INSTANCE_ENV],
+        )
+        for env in (a_author, b_author):
+            assessed = launcher.inherit_or_refuse_client_instance(env)
+            self.assertTrue(assessed["trusted"], assessed)
+            self.assertTrue(assessed["launcher_sealed"], assessed)
+
+    def test_no_nonce_still_yields_distinct_ids(self):
+        a = self._build(None)
+        b = self._build(None)
+        self.assertNotEqual(a["client_instance_id"], b["client_instance_id"])
+
+    def test_ids_are_never_persisted_between_launches(self):
+        """No static per-project ID: two runs of one config differ."""
+        first = self._build("static-check-1")
+        second = self._build("static-check-2")
+        self.assertNotEqual(
+            first["mcpServers"]["gitea-author"]["env"][launcher.CLIENT_INSTANCE_ENV],
+            second["mcpServers"]["gitea-author"]["env"][launcher.CLIENT_INSTANCE_ENV],
+        )
+
+
+class FailClosedIdentityTests(unittest.TestCase):
+    """AC: missing / legacy / reused / conflicting / unsealed all fail closed."""
+
+    def test_missing_identity_fails_closed(self):
+        assessed = launcher.inherit_or_refuse_client_instance({})
+        self.assertFalse(assessed["trusted"])
+        self.assertFalse(assessed["launcher_sealed"])
+        self.assertEqual(
+            assessed["provenance"], fleet.INSTANCE_ID_PROVENANCE_MISSING
+        )
+
+    def test_legacy_pid_identity_fails_closed(self):
+        for legacy in ("legacy-pid-40578", "pid-1234", "proc-99"):
+            with self.subTest(legacy=legacy):
+                assessed = launcher.inherit_or_refuse_client_instance(
+                    {
+                        launcher.CLIENT_INSTANCE_ENV: legacy,
+                        launcher.INSTANCE_PROVENANCE_ENV: (
+                            fleet.INSTANCE_ID_PROVENANCE_TRUSTED
+                        ),
+                    }
+                )
+                self.assertFalse(assessed["trusted"], legacy)
+                self.assertFalse(assessed["launcher_sealed"], legacy)
+
+    def test_wellformed_but_unsealed_identity_fails_closed(self):
+        """The decisive case: format alone must not manufacture trust."""
+        forged = fleet.generate_client_instance_id(
+            "claude_code", launch_nonce="forged", now=NOW
+        )
+        # A hand-set env var with a valid-looking ID but no launcher seal.
+        assessed = launcher.inherit_or_refuse_client_instance(
+            {launcher.CLIENT_INSTANCE_ENV: forged}
+        )
+        self.assertFalse(assessed["trusted"], assessed)
+        self.assertFalse(assessed["launcher_sealed"], assessed)
+        self.assertEqual(
+            assessed["provenance"], fleet.INSTANCE_ID_PROVENANCE_UNSEALED
+        )
+        # The value is still reported for diagnosis, not silently dropped.
+        self.assertEqual(assessed["client_instance_id"], forged)
+
+    def test_wrong_provenance_marker_fails_closed(self):
+        forged = fleet.generate_client_instance_id(
+            "claude_code", launch_nonce="wrong-marker", now=NOW
+        )
+        assessed = launcher.inherit_or_refuse_client_instance(
+            {
+                launcher.CLIENT_INSTANCE_ENV: forged,
+                launcher.INSTANCE_PROVENANCE_ENV: "totally_trusted",
+            }
+        )
+        self.assertFalse(assessed["trusted"], assessed)
+        self.assertEqual(
+            assessed["provenance"], fleet.INSTANCE_ID_PROVENANCE_UNSEALED
+        )
+
+    def test_sealed_launcher_env_is_trusted(self):
+        env = launcher.namespace_worker_env(
+            profile_name="prgs-author",
+            client_type="claude_code",
+            client_instance_id=fleet.generate_client_instance_id(
+                "claude_code", launch_nonce="sealed", now=NOW
+            ),
+        )
+        assessed = launcher.inherit_or_refuse_client_instance(env)
+        self.assertTrue(assessed["trusted"], assessed)
+        self.assertTrue(assessed["launcher_sealed"], assessed)
+
+    def test_untrusted_id_refused_on_build_and_worker_env(self):
+        with self.assertRaises(ValueError):
+            launcher.build_application_mcp_servers(
+                PROJECT_PROFILES,
+                client_type="claude_code",
+                namespaces=PROJECT_NAMESPACES,
+                client_instance_id="legacy-pid-1",
+                command="python3",
+                args=["mcp_server.py"],
+            )
+        with self.assertRaises(ValueError):
+            launcher.namespace_worker_env(
+                profile_name="prgs-author",
+                client_type="claude_code",
+                client_instance_id="hand-written",
+            )
+
+    def test_extra_env_cannot_forge_seal_or_identity(self):
+        trusted = fleet.generate_client_instance_id(
+            "claude_code", launch_nonce="seal-guard", now=NOW
+        )
+        env = launcher.namespace_worker_env(
+            profile_name="prgs-author",
+            client_type="claude_code",
+            client_instance_id=trusted,
+            extra_env={
+                launcher.CLIENT_INSTANCE_ENV: "inst-spoof-20260101T000000Z-abcdef",
+                launcher.INSTANCE_PROVENANCE_ENV: "trusted_launcher",
+                "GITEA_CLIENT_MANAGED": "0",
+            },
+        )
+        self.assertEqual(env[launcher.CLIENT_INSTANCE_ENV], trusted)
+        self.assertEqual(env["GITEA_CLIENT_MANAGED"], "1")
+
+    def test_conflicting_ids_across_workers_break_shared_attribution(self):
+        """One launch whose workers disagree must not read as shared."""
+        built = launcher.build_application_mcp_servers(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            launch_nonce="conflict",
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        servers = built["mcpServers"]
+        servers["gitea-merger"]["env"][launcher.CLIENT_INSTANCE_ENV] = (
+            fleet.generate_client_instance_id(
+                "claude_code", launch_nonce="other", now=NOW
+            )
+        )
+        proof = launcher.collect_instance_ids_from_mcp_servers(
+            servers, namespaces=PROJECT_NAMESPACES
+        )
+        self.assertFalse(proof["shared_single_trusted_id"], proof)
+        self.assertEqual(len(proof["unique_instance_ids"]), 2)
+
+    def test_absent_expected_worker_breaks_shared_attribution(self):
+        built = launcher.build_application_mcp_servers(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            launch_nonce="absent",
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        servers = dict(built["mcpServers"])
+        servers.pop("gitea-merger")
+        proof = launcher.collect_instance_ids_from_mcp_servers(
+            servers, namespaces=PROJECT_NAMESPACES
+        )
+        self.assertFalse(proof["shared_single_trusted_id"], proof)
+        self.assertEqual(proof["missing_servers"], ["gitea-merger"])
+
+    def test_reused_trusted_id_is_reuse_not_a_fresh_launch(self):
+        """Resume reuses by design; two *live* launches sharing it is the hazard."""
+        first = launcher.build_application_mcp_servers(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            launch_nonce="reuse-src",
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        resumed = launcher.build_application_mcp_servers(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            client_instance_id=first["client_instance_id"],
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        self.assertEqual(
+            first["client_instance_id"], resumed["client_instance_id"]
+        )
+        # Two independent launches must never collide by default.
+        independent = launcher.build_application_mcp_servers(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        self.assertNotEqual(
+            first["client_instance_id"], independent["client_instance_id"]
+        )
+
+
+class BackwardCompatibilityTests(unittest.TestCase):
+    """AC: existing full five-namespace behaviour remains compatible."""
+
+    def test_omitting_namespaces_launches_all_five(self):
+        built = launcher.build_application_mcp_servers(
+            FULL_PROFILES,
+            client_type="codex",
+            launch_nonce="compat",
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        self.assertEqual(len(built["mcpServers"]), 5)
+        self.assertEqual(built["namespace_count"], 5)
+        self.assertEqual(built["excluded_namespaces"], [])
+        self.assertFalse(built["project_scoped"])
+        ids = set(_instance_ids(built["mcpServers"]).values())
+        self.assertEqual(len(ids), 1)
+
+    def test_five_namespace_missing_profile_still_refused(self):
+        incomplete = {ns: f"prgs-{ns}" for ns in PROJECT_NAMESPACES}
+        with self.assertRaises(ValueError) as ctx:
+            launcher.build_application_mcp_servers(
+                incomplete,
+                client_type="codex",
+                command="python3",
+                args=["mcp_server.py"],
+            )
+        message = str(ctx.exception)
+        self.assertIn("controller", message)
+        self.assertIn("reconciler", message)
+
+    def test_legacy_collect_call_without_namespaces_still_works(self):
+        built = launcher.build_application_mcp_servers(
+            FULL_PROFILES,
+            client_type="codex",
+            launch_nonce="compat-proof",
+            now=NOW,
+            command="python3",
+            args=["mcp_server.py"],
+        )
+        proof = launcher.collect_instance_ids_from_mcp_servers(built["mcpServers"])
+        self.assertTrue(proof["shared_single_trusted_id"], proof)
+        self.assertEqual(proof["namespace_server_count"], 5)
+
+    def test_gitea_config_wrapper_supports_subset(self):
+        import gitea_config
+
+        built = gitea_config.multi_namespace_launcher_entries(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            config_path="/cfg/profiles.json",
+            launch_nonce="cfg-subset",
+        )
+        self.assertEqual(built["namespace_count"], 3)
+        self.assertEqual(
+            sorted(built["excluded_namespaces"]), ["controller", "reconciler"]
+        )
+
+    def test_gitea_config_wrapper_default_is_five(self):
+        import gitea_config
+
+        built = gitea_config.multi_namespace_launcher_entries(
+            FULL_PROFILES,
+            client_type="claude_code",
+            config_path="/cfg/profiles.json",
+            launch_nonce="cfg-full",
+        )
+        self.assertEqual(built["namespace_count"], 5)
+
+
+class RunnableLaunchPathTests(unittest.TestCase):
+    """AC: Claude Code has a documented supported launch command."""
+
+    def test_claude_code_is_a_supported_client(self):
+        self.assertIn("claude_code", launcher.supported_launch_clients())
+
+    def test_claude_code_argv_uses_per_launch_config(self):
+        argv = launcher.build_client_launch_argv("claude_code", "/tmp/launch.json")
+        self.assertEqual(argv[0], "claude")
+        self.assertIn("--mcp-config", argv)
+        self.assertIn("/tmp/launch.json", argv)
+        self.assertIn("--strict-mcp-config", argv)
+
+    def test_extra_args_are_forwarded(self):
+        argv = launcher.build_client_launch_argv(
+            "claude_code", "/tmp/launch.json", extra_args=["--resume"]
+        )
+        self.assertEqual(argv[-1], "--resume")
+
+    def test_unsupported_client_refused(self):
+        with self.assertRaises(ValueError):
+            launcher.build_client_launch_argv("not_a_client", "/tmp/x.json")
+
+    def test_prepare_launch_writes_private_per_launch_config(self):
+        prepared = launcher.prepare_application_launch(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            launch_nonce="prep-1",
+            now=NOW,
+        )
+        path = prepared["launch_config_path"]
+        self.addCleanup(lambda: os.path.exists(path) and os.unlink(path))
+        self.assertTrue(os.path.exists(path))
+        self.assertEqual(os.stat(path).st_mode & 0o777, 0o600)
+        with open(path, encoding="utf-8") as handle:
+            payload = json.load(handle)
+        self.assertEqual(
+            sorted(payload["mcpServers"]),
+            ["gitea-author", "gitea-merger", "gitea-reviewer"],
+        )
+        self.assertTrue(prepared["shared_single_trusted_id"], prepared)
+        self.assertIn(path, prepared["argv"])
+
+    def test_two_prepared_launches_use_distinct_files_and_ids(self):
+        first = launcher.prepare_application_launch(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            now=NOW,
+        )
+        second = launcher.prepare_application_launch(
+            PROJECT_PROFILES,
+            client_type="claude_code",
+            namespaces=PROJECT_NAMESPACES,
+            now=NOW,
+        )
+        for prepared in (first, second):
+            path = prepared["launch_config_path"]
+            self.addCleanup(lambda p=path: os.path.exists(p) and os.unlink(p))
+        self.assertNotEqual(
+            first["launch_config_path"], second["launch_config_path"]
+        )
+        self.assertNotEqual(
+            first["client_instance_id"], second["client_instance_id"]
+        )
+
+    def test_unsupported_client_writes_no_config_file(self):
+        """Fail before creating a file, so a bad invocation leaves no residue."""
+        with self.assertRaises(ValueError):
+            launcher.prepare_application_launch(
+                PROJECT_PROFILES,
+                client_type="not_a_client",
+                namespaces=PROJECT_NAMESPACES,
+                now=NOW,
+            )
+
+
+class CliTests(unittest.TestCase):
+    """The runnable entry point itself."""
+
+    def _run_dry(self, argv):
+        import contextlib
+        import io
+
+        buffer = io.StringIO()
+        with contextlib.redirect_stdout(buffer):
+            code = launcher.main(argv)
+        return code, buffer.getvalue()
+
+    def test_dry_run_project_scoped_plan(self):
+        code, out = self._run_dry(
+            [
+                "--client",
+                "claude_code",
+                "--namespaces",
+                "author,reviewer,merger",
+                "--profile",
+                "author=prgs-author",
+                "--profile",
+                "reviewer=prgs-reviewer",
+                "--profile",
+                "merger=prgs-merger",
+                "--dry-run",
+            ]
+        )
+        self.assertEqual(code, 0)
+        plan = json.loads(out)
+        path = plan["launch_config_path"]
+        self.addCleanup(lambda: os.path.exists(path) and os.unlink(path))
+        self.assertEqual(plan["namespaces"], ["author", "reviewer", "merger"])
+        self.assertEqual(
+            sorted(plan["excluded_namespaces"]), ["controller", "reconciler"]
+        )
+        self.assertTrue(plan["shared_single_trusted_id"])
+        self.assertTrue(
+            fleet.assess_instance_identity(plan["client_instance_id"])["trusted"]
+        )
+        self.assertEqual(plan["argv"][0], "claude")
+
+    def test_cli_refuses_profile_for_unlaunched_namespace(self):
+        with self.assertRaises(SystemExit):
+            self._run_dry(
+                [
+                    "--namespaces",
+                    "author,reviewer,merger",
+                    "--profile",
+                    "author=prgs-author",
+                    "--profile",
+                    "reviewer=prgs-reviewer",
+                    "--profile",
+                    "merger=prgs-merger",
+                    "--profile",
+                    "controller=prgs-controller",
+                    "--dry-run",
+                ]
+            )
+
+    def test_cli_refuses_unsanctioned_namespace(self):
+        with self.assertRaises(SystemExit):
+            self._run_dry(
+                [
+                    "--namespaces",
+                    "author,admin",
+                    "--profile",
+                    "author=prgs-author",
+                    "--dry-run",
+                ]
+            )
+
+    def test_cli_refuses_missing_profile(self):
+        with self.assertRaises(SystemExit):
+            self._run_dry(
+                [
+                    "--namespaces",
+                    "author,reviewer",
+                    "--profile",
+                    "author=prgs-author",
+                    "--dry-run",
+                ]
+            )
+
+    def test_cli_refuses_malformed_profile_pair(self):
+        with self.assertRaises(SystemExit):
+            self._run_dry(
+                ["--namespaces", "author", "--profile", "prgs-author", "--dry-run"]
+            )
+
+    def test_two_cli_runs_receive_distinct_ids(self):
+        args = [
+            "--namespaces",
+            "author,reviewer,merger",
+            "--profile",
+            "author=prgs-author",
+            "--profile",
+            "reviewer=prgs-reviewer",
+            "--profile",
+            "merger=prgs-merger",
+            "--dry-run",
+        ]
+        _, first = self._run_dry(args)
+        _, second = self._run_dry(args)
+        a = json.loads(first)
+        b = json.loads(second)
+        for plan in (a, b):
+            path = plan["launch_config_path"]
+            self.addCleanup(lambda p=path: os.path.exists(p) and os.unlink(p))
+        self.assertNotEqual(a["client_instance_id"], b["client_instance_id"])
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

tests/test_root_checkout_guard.py

@@ -87,13 +87,27 @@ class TestAssessRootCheckoutGuard(unittest.TestCase):
         self.assertTrue(result["block"])
         self.assertIn("tracked local edits", result["reasons"][0])
 
-    def test_head_behind_prgs_master_blocked(self):
+    def test_head_behind_tracking_base_ref_blocked(self):
+        """#983: the base ref is derived, so the message no longer hardcodes PRGS."""
         result = self._assess(
             head_sha=OTHER_SHA,
             remote_master_sha=MASTER_SHA,
         )
         self.assertTrue(result["block"])
-        self.assertIn("does not match prgs/master", result["reasons"][0])
+        self.assertIn(
+            "does not match the tracking integration ref", result["reasons"][0]
+        )
+
+    def test_head_behind_named_base_ref_reports_that_ref(self):
+        """The resolved ref is named, so a non-PRGS target is reported accurately."""
+        result = self._assess(
+            head_sha=OTHER_SHA,
+            remote_master_sha=MASTER_SHA,
+            remote_master_ref="refs/remotes/MDCPS/dev",
+        )
+        self.assertTrue(result["block"])
+        self.assertIn("does not match refs/remotes/MDCPS/dev", result["reasons"][0])
+        self.assertNotIn("prgs/master", result["reasons"][0])
 
     def test_merger_requires_clean_control_checkout(self):
         result = self._assess(